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 three FFmpeg 5.x incompatibilities and run CI on FFmpeg 5.1.1 and 7.1 (#156)
Shogo Kajiyamaaf6948252e8d
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 53a81ac..c494b04 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -109,3 +109,81 @@ jobs:- run: python tests/test_contract.pyif: "!cancelled()"- run: node bin/install.js++ # The docs promise FFmpeg 5.0+; the matrix above only ever ran 6.1 (apt), 8.x (Homebrew) and+ # 9.x (gyan.dev). These two Linux-only (1x cost) jobs pin the other two majors. Both are kept+ # as plain jobs rather than matrix rows because each needs a different way of *getting*+ # ffmpeg, and the 7.x one needs a different base image altogether. See #146.+ #+ # 5.1.1: John Van Sickle's static build (the same source the README recommends for Linux+ # users without a recent apt). Verified locally before this job existed: doctor ok, the full+ # contract and end-to-end suites pass. The tarball is pinned by version, not "release".+ test-ffmpeg-5:+ name: test (ubuntu-latest, py3.9, ffmpeg 5.1.1 static)+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ with:+ fetch-depth: 0+ - uses: actions/setup-python@v7+ with:+ python-version: "3.9"+ - name: Install ffmpeg 5.1.1 (static) and fonts+ run: |+ sudo apt-get update && sudo apt-get install -y fonts-dejavu-core+ curl -sSL -o ffmpeg.tar.xz https://johnvansickle.com/ffmpeg/old-releases/ffmpeg-5.1.1-amd64-static.tar.xz+ mkdir -p "$HOME/ffmpeg5" && tar -xJf ffmpeg.tar.xz -C "$HOME/ffmpeg5" --strip-components=1+ echo "$HOME/ffmpeg5" >> "$GITHUB_PATH"+ - name: ffmpeg version, listings and doctor+ run: |+ mkdir -p listings+ ffmpeg -version | head -1 | tee listings/version.txt+ ffmpeg -hide_banner -filters > listings/ffmpeg_filters.txt+ ffmpeg -hide_banner -encoders > listings/ffmpeg_encoders.txt+ ffmpeg -hide_banner -bsfs > listings/ffmpeg_bsfs.txt+ python scripts/_contract.py doctor --json > listings/doctor.json || echo "doctor exit $?"+ cat listings/doctor.json+ - uses: actions/upload-artifact@v7+ if: always()+ with:+ name: ffmpeg-listings-ubuntu-latest-ffmpeg5+ path: listings/+ - run: python tests/test_all.py+ - run: python tests/test_contract.py+ if: "!cancelled()"++ # 7.1.x: no maintained static build carries drawtext any more (John Van Sickle's 7.0.2 lacks+ # the filter; BtbN dropped 7.x), but Debian trixie's apt ffmpeg is 7.1 with libass, freetype+ # and zimg, so this job runs inside a trixie container. It also happens to give Python 3.13.+ test-ffmpeg-7:+ name: test (debian-trixie container, py3.13, ffmpeg 7.1 apt)+ runs-on: ubuntu-latest+ container: debian:trixie+ steps:+ - name: Install ffmpeg 7.1, Python, fonts, git and node+ run: |+ apt-get update -qq+ DEBIAN_FRONTEND=noninteractive apt-get install -y -qq ffmpeg python3 fonts-dejavu-core git nodejs ca-certificates+ git config --global --add safe.directory "$GITHUB_WORKSPACE"+ - uses: actions/checkout@v4+ with:+ fetch-depth: 0+ - name: ffmpeg version, listings and doctor+ run: |+ mkdir -p listings+ ffmpeg -version | head -1 | tee listings/version.txt+ python3 --version+ ffmpeg -hide_banner -filters > listings/ffmpeg_filters.txt+ ffmpeg -hide_banner -encoders > listings/ffmpeg_encoders.txt+ ffmpeg -hide_banner -bsfs > listings/ffmpeg_bsfs.txt+ python3 scripts/_contract.py doctor --json > listings/doctor.json || echo "doctor exit $?"+ cat listings/doctor.json+ - uses: actions/upload-artifact@v7+ if: always()+ with:+ name: ffmpeg-listings-debian-trixie-ffmpeg7+ path: listings/+ - run: python3 tests/test_all.py+ - run: python3 tests/test_contract.py+ if: "!cancelled()"+diff --git a/README.md b/README.mdindex e01b511..310e326 100644--- a/README.md+++ b/README.md@@ -312,12 +312,13 @@ npx ffmpeg-skill doctor --json # available / missing / missing_optional / unkn## FFmpeg compatibility-The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 6.1 (Ubuntu), 8.x (macOS) and 9.x (Windows), all on Python 3.9, plus Ubuntu on Python 3.13 (the two ends of the supported range); 5.x and 7.x are expected to work from the filter/encoder names used but are not run ([#146](https://github.com/kajisho5/ffmpeg-skill/issues/146) tracks widening the matrix). The capability parser has been run against the listings of these builds:+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:| FFmpeg | `-filters` row layout | Source ||---|---|---|+| 5.1.1 | three flag characters, same as 6.x | johnvansickle.com static build on the Linux CI runner || 6.1.1 | three flag characters: `..C acompressor A->A` | Ubuntu 24.04 apt, captured |-| 7.x | same as 6.x | constructed fixture (no capture at hand) |+| 7.1.x | same as 6.x | Debian trixie apt in a CI container (plus a constructed fixture in tests/) || 8.1.2 | two flag characters: `TS aap AA->A`, three-character legend, `------` separator | Homebrew on the macOS CI runner, captured || 9.0.1 | same as 8.x, CRLF | gyan.dev build on the Windows CI runner, captured |@@ -403,7 +404,7 @@ python3 evals/run.py --list # agent eval prompts (see evals/)node bin/install.js --dir /tmp/skills # try the installer without touching ~/.claude```-CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `main`, on Ubuntu (FFmpeg 6.1), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), and uploads each runner's FFmpeg listings as an artifact.+CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `main`, on Ubuntu (FFmpeg 6.1, Python 3.9 and 3.13), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), plus two Linux jobs on FFmpeg 5.1.1 (static build) and 7.1 (Debian trixie container), and uploads each runner's FFmpeg listings as an artifact.`tests/test_contract.py` runs on all three OSes, but a handful of its tests build a fake `ffmpeg` as a `#!/bin/sh` script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through `doctor`'s parser — that technique isn't portable to Windows, so `test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class (fixture-driven layout parsing) are individually `skipIf`'d there and show as `skipped`, not silently absent, in the Windows job's log. Everything else — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract, including `cut.py`'s provenance fields — runs against the real Windows `ffmpeg` on every PR. See [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.diff --git a/references/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.mdindex 09f3aa9..39a5500 100644--- a/references/ci-platform-pitfalls.md+++ b/references/ci-platform-pitfalls.md@@ -109,3 +109,59 @@ When a test needs to special-case a platform, prefer gating withmechanism, and write the skip/relaxation reason as a full sentenceexplaining the underlying platform behaviour — not just "flaky onWindows" — so a future reader doesn't have to re-derive it from the CI log.++## FFmpeg 5.x (the 5.1.1 static-build CI job)++Found the day the job was added (#146); 6.1+ behaves the same on all three OSes, so none of+these had ever shown up before.++- **`scdet=...:sc_pass=1` passes only frames whose score exceeds the threshold.** On 5.x every+ truly static frame (score exactly 0: a title card, colour bars) is dropped before the next+ filter and the frame numbers are re-counted without them. `scenes.py` used it with+ `threshold=0` expecting every frame through, so a 4 s smptebars scene made the cuts on both+ sides of it disappear from its neighbourhood test. 6.1+ passes every frame regardless.+ Dropped the option; scores are also indexed by frame number now, missing frames counting as 0.+- **`drawtext` `boxborderw=v|h` (and the four-value form) is 6.1+.** 5.x and 6.0 fail the whole+ filter with "Error setting option boxborderw to value 9|16". `_common.drawtext_boxborderw()`+ emits the larger single value on older builds (`_common.ffmpeg_version()` parses+ `ffmpeg -version` once; it is the only place the tools branch on a version string).+- **`showwaves` keeps emitting frames after the audio ends, `-shortest` notwithstanding.** A+ 12 s source came out 14.08 s on 5.1.1. `waveform.py` now also passes `-t <source duration>`.+- **`-display_rotation` is 6.0+.** Only the test fixture builder used it (to make a rotated+ phone-style clip); on 5.x it writes the stream's `rotate` tag instead, which every probe here+ reads identically.+- **John Van Sickle's 7.0.2 static build has no `drawtext`** (built with freetype, yet the+ filter is absent), and BtbN no longer publishes 7.x; the 7.1 job therefore runs in a Debian+ trixie container (apt ffmpeg 7.1.5 with libass, freetype and zimg).++## FFmpeg 7.1+ (the debian-trixie container CI job)++- **Output `-colorspace bt709` is no longer just a tag: on an untagged source it converts.**+ 7.1 added colourspace negotiation to libavfilter, and the CLI feeds the encoder's+ `-colorspace/-color_primaries/-color_trc` into the graph's output constraints. A source+ whose bitstream carries no colour tags (`color_space=unknown` -- test sources, screen+ recordings, many cameras) then *differs* from the requested BT.709, so ffmpeg auto-inserts+ a real matrix conversion (swscale guesses bt601 for "unknown"): every SDR re-encode through+ `x264_args()` shifted the picture, and a `--lut-strength 0` no-op grade came back ~24 dB+ PSNR from its source. 5.x/6.x wrote the same options as tags only (47 dB, no conversion).+ The 7.0.2 static build does *not* show it; 7.1.1 (conda-forge) reproduces it locally, so+ that is the build to use when the trixie job goes red on a colour test.+ Fix: `_common.bt709_tag_args()` writes the tags through the encoder's own VUI parameters+ (`-x264-params colorprim=...:transfer=...:colormatrix=...`, x265 likewise) from 7.1 on,+ which libavfilter never sees; older builds keep the output options, since those were the+ only way to get an mp4 `colr` atom there. A decoder-side `-colorspace bt709 ... -i` override+ was tried first and rejected: it also tags a `-c copy` output of an untagged source (export+ copy must stay a real copy), and it exposed a separate, pre-existing `--correct` bug (below).+ Verified on 5.1.1, 6.1.1, 7.1.1 and 8.1.2. 8.x has the same encode-time conversion; it+ went unnoticed there because 8.x's `psnr` filter *also* negotiates colourspace and undid it+ before measuring (40 dB for re-matrixed pixels), and it then flagged the fixed, byte-clean+ output as 26 dB instead. The tests' `_psnr` helper now pins identical colour tags on both+ inputs so every build reports the same number for the same two files.+- **The conda-forge 7.1.1 build deadlocks on `tpad` + `adelay`/`apad` (pad.py) and ignores+ SIGTERM.** Debian's 7.1.5 in CI does not. Run pad tests against CI, not that build, and note+ that the tools have no subprocess timeout to get an agent out of such a hang.+- **Not a 7.1 issue, found while chasing it: `color --correct` desaturates a bt709-*tagged*+ source by ~8 % at identity settings on 6.1 and 7.1 alike** (113.6 → 103.9 saturation_avg):+ the RGB stages (exposure/colortemperature/colorbalance) make swscale go yuv→rgb with the+ frame's bt709 matrix and back with its bt601 default. The identity test only ever used an+ untagged source, where both legs pick bt601 and cancel out. Tracked separately.diff --git a/scripts/_common.py b/scripts/_common.pyindex 8ca2d0f..baeedbc 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -15,7 +15,7 @@ import subprocessimport sysfrom fractions import Fractionfrom pathlib import Path-from typing import Any, Dict, List, Optional, Sequence+from typing import Any, Dict, List, Optional, Sequence, Tuple# 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@@ -74,6 +74,38 @@ ERROR_CODE = {ERROR_RETRYABLE = False+_FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None+++def ffmpeg_version() -> "Tuple[int, int]":+ """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)+ when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run+ ffmpeg (docs/contract.md: ffmpeg_execution "none") while ffprobe always may, and the two+ ship from the same build. Used only to pick between two spellings of an option where FFmpeg+ changed behaviour between releases (the tools otherwise never branch on the version: doctor's+ capability listing is the source of truth for what a build can do)."""+ global _FFMPEG_VERSION+ if _FFMPEG_VERSION is None:+ _FFMPEG_VERSION = (0, 0)+ try:+ out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True).stdout+ m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)+ if m:+ _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))+ except OSError:+ pass+ return _FFMPEG_VERSION+++def drawtext_boxborderw(vertical: int, horizontal: int) -> str:+ """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)+ arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"+ (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""+ if ffmpeg_version() >= (6, 1):+ return f"{vertical}|{horizontal}"+ return str(max(vertical, horizontal))++def die(msg: str, code: int = 1, kind: str = "input") -> "None":"""Exit with a message. Under --json also print a machine-readable failure document(status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged."""@@ -698,10 +730,30 @@ def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Lisreturn ["-fps_mode", "cfr", "-r", f"{rate:g}"]+def bt709_tag_args(encoder: str = "libx264") -> List[str]:+ """Tag an SDR output as BT.709 without touching its pixels.++ Up to FFmpeg 7.0 the output options -colorspace/-color_primaries/-color_trc were tags only.+ 7.1 added colourspace negotiation to libavfilter and feeds those options into the graph's+ output constraints, so on a source whose bitstream carries no colour tags (test sources,+ screen recordings, many cameras) the CLI now auto-inserts a *real* matrix conversion (its+ guess for "unknown" is bt601) into every SDR re-encode: a --lut-strength 0 no-op grade+ came back ~24 dB PSNR from its source on 7.1. From 7.1 on, the tags therefore go through+ the encoder's own VUI parameters instead, which libavfilter never sees; a source that is+ genuinely tagged bt601/bt2020 is left alone either way (it keeps its own tags on the old+ path, and the encoder VUI is a label, not a conversion, on the new one).+ """+ if ffmpeg_version() < (7, 1):+ return ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]+ if encoder == "libx265":+ return ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]+ return ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]++def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]if keep_bt709:- args += ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]+ args += bt709_tag_args("libx264")return argsdiff --git a/scripts/export.py b/scripts/export.pyindex e2ca5f7..1a1b025 100755--- a/scripts/export.py+++ b/scripts/export.py@@ -26,7 +26,7 @@ import sysfrom pathlib import Pathfrom typing import Dict, List-from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color+from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_colorPRESETS: Dict[str, Dict] = {"youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},@@ -39,7 +39,6 @@ PRESETS: Dict[str, Dict] = {"copy": {"w": None, "h": None, "ext": None, "video": ["-c:v", "copy"], "audio": ["-c:a", "copy"], "max": None, "desc": "stream copy, no re-encode (source codecs/container/colour tags unchanged)"},}-BT709 = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]def main() -> int:@@ -110,7 +109,7 @@ def main() -> int:if "-r" not in video:cmd += cfr_args(meta)if args.preset not in ("prores",):- cmd += BT709+ cmd += bt709_tag_args(video[video.index("-c:v") + 1])if out_ext == "mp4":cmd += ["-movflags", "+faststart"]cmd += (p["audio"] if has_audio else ["-an"])diff --git a/scripts/graphics.py b/scripts/graphics.pyindex 9741bd5..d24b43a 100755--- a/scripts/graphics.py+++ b/scripts/graphics.py@@ -21,7 +21,7 @@ import argparseimport sysfrom typing import List, Optional-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args+from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderwTEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]@@ -139,7 +139,7 @@ def main() -> int:ye = f"{margin}" if "top" in pos else f"h-text_h-{margin}"box_color = ff_color(primary if args.template == "chapter" else bg, 0.9 if args.template == "chapter" else 0.7)txt_color = ff_color(bg if args.template == "chapter" else text_c)- filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={pady}|{padx}:alpha='{fade_a}':{en}")+ filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={drawtext_boxborderw(pady, padx)}:alpha='{fade_a}':{en}")elif args.template == "progress":h = max(3, int(base * 0.008))diff --git a/scripts/scenes.py b/scripts/scenes.pyindex 1ee4ca4..df4d637 100755--- a/scripts/scenes.py+++ b/scripts/scenes.py@@ -39,25 +39,35 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,equal recall compared with the raw scdet threshold."""ffmpeg = require_tool("ffmpeg")proc = subprocess.run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",- "scale=320:-2,scdet=threshold=0:sc_pass=1,metadata=print:file=-", "-f", "null", "-"],+ "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"],stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)- times: List[float] = []- scores: List[float] = []- cur_t = None+ # No `sc_pass=1` on scdet: on FFmpeg 5.x that option means "pass only the frames whose+ # score exceeds the threshold", so every truly static frame (score exactly 0 -- a title+ # card, colour bars) is dropped before metadata=print and the frame numbers are re-counted+ # without them. The +-12-frame neighbourhood around a real cut then fills with the moving+ # segment's scores instead of the still one's zeros, the cut fails the ratio test, and a+ # 4 s smptebars scene made the cuts on both sides of it disappear (found by the 5.1.1 CI+ # job, #146). 6.1+ passes every frame either way. Scores are still indexed by frame number+ # and any frame the filter did not report counts as 0, so a build that drops frames again+ # cannot shift the neighbourhood.+ by_frame: Dict[int, Tuple[float, float]] = {}+ cur = Nonefor line in proc.stdout.splitlines():m = SCORE_RE.match(line)if m:- cur_t = float(m.group(2))+ cur = (int(m.group(1)), float(m.group(2)))continue- if line.startswith("lavfi.scd.score=") and cur_t is not None:+ if line.startswith("lavfi.scd.score=") and cur is not None:try:- times.append(cur_t)- scores.append(float(line.split("=", 1)[1]))+ by_frame[cur[0]] = (cur[1], float(line.split("=", 1)[1]))except ValueError:passcuts = [0.0]- if not scores:+ if not by_frame:return cuts+ n_frames = max(by_frame) + 1+ times: List[float] = [by_frame[i][0] if i in by_frame else -1.0 for i in range(n_frames)]+ scores: List[float] = [by_frame[i][1] if i in by_frame else 0.0 for i in range(n_frames)]w = 12for i, sc in enumerate(scores):if sc < threshold:diff --git a/scripts/waveform.py b/scripts/waveform.pyindex c65e92e..61009a5 100644--- a/scripts/waveform.py+++ b/scripts/waveform.py@@ -78,6 +78,11 @@ def main() -> int:cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", f"0:a:{args.audio_stream}"]cmd += ["-c:v", "libx264", "-preset", args.preset, "-crf", str(args.crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]cmd += aac_args()+ # -shortest alone is not enough on FFmpeg 5.x: showwaves keeps emitting frames after the+ # audio ends (a 12 s source came out 14.08 s on 5.1.1, #146), so the output is also capped+ # at the source's own duration when probe knows it.+ if meta.get("duration"):+ cmd += ["-t", f"{float(meta['duration']):.3f}"]cmd += ["-shortest", output]run(cmd)diff --git a/tests/test_all.py b/tests/test_all.pyindex c9a9d2c..0250316 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -73,7 +73,14 @@ class FFmpegSkillTests(unittest.TestCase):"-t", "12", "-vf", "select='gt(random(1)\\,0.3)'", "-fps_mode", "vfr","-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", cls.vfr)cls.rot = OUT / "rot.mp4"- sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-i", cls.src, "-t", "6", "-c", "copy", cls.rot)+ # -display_rotation arrived in FFmpeg 6.0; on 5.x the rotation is written the old way,+ # as the stream's rotate tag, which every probe here reads the same. Only the fixture+ # builder cares -- the tools under test never emit either.+ if subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-f", "lavfi", "-i", "color=c=black:s=16x16:d=0.1", "-f", "null", "-"],+ stdout=subprocess.PIPE, stderr=subprocess.PIPE).returncode == 0:+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-i", cls.src, "-t", "6", "-c", "copy", cls.rot)+ else:+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", cls.src, "-t", "6", "-c", "copy", "-metadata:s:v:0", "rotate=90", cls.rot)cls.surround = OUT / "surround.mov"six = "|".join([TONES, TONES, "0.5*" + TONES, "0.2*sin(2*PI*60*t)", "0.3*" + TONES, "0.3*" + TONES])sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",@@ -1301,6 +1308,7 @@ class FFmpegSkillTests(unittest.TestCase):zero = OUT / "lut_zero.mp4"script("color.py", self.src, "--lut", lut, "--lut-strength", "0", "--preset", "veryfast", "-o", zero)self.assertGreater(self._psnr(self.src, zero), 40, "--lut-strength 0 must leave the picture unchanged, not fully inverted")+ self.assertEqual(self._frame_count(zero), self._frame_count(self.src), "no frame may be dropped or duplicated by a no-op grade")script("color.py", self.src, "--lut", lut, "--lut-strength", "2.5", "-o", OUT / "lut_oob.mp4", expect_fail=True)script("color.py", self.src, "--lut", lut, "--lut-strength", "-1", "-o", OUT / "lut_oob2.mp4", expect_fail=True)@@ -1886,6 +1894,15 @@ class FFmpegSkillTests(unittest.TestCase):link = stub_dir / exeif not link.exists():os.symlink(real, link)+ # Python's own bin dir has to stay on PATH, and on a system-python machine (the Debian+ # container job) that dir is /usr/bin, which also holds the real fc-match -- so "hidden+ # by PATH" was not hidden at all there and the tool resolved a real fontfile= instead of+ # taking the font= fallback this test exists to exercise. A stub fc-match that always+ # fails sits first on PATH so the resolver returns None on every layout.+ if platform.system() != "Windows":+ stub = stub_dir / "fc-match"+ stub.write_text("#!/bin/sh\nexit 1\n", encoding="utf-8")+ stub.chmod(0o755)env = dict(os.environ)env["PATH"] = os.pathsep.join([str(stub_dir), str(Path(sys.executable).parent)])@@ -2808,10 +2825,29 @@ class FFmpegSkillTests(unittest.TestCase):# ------------------------------------------------------------------ FFmpeg 8+ / Windows compatibility+ @staticmethod+ def _frame_count(path):+ proc = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-count_packets", "-show_entries", "stream=nb_read_packets", "-of", "csv=p=0", str(path)],+ stdout=subprocess.PIPE, text=True)+ return int(proc.stdout.strip())+@staticmethoddef _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", "-"],+ # Two things make this compare pixels and nothing else. (1) Both inputs are re-stamped by+ # frame *number*, so the psnr filter (which pairs frames by timestamp) never compares a+ # frame with its neighbour; frame *count* equality is asserted separately by the callers+ # that care, so a genuinely dropped frame still fails. (2) Both inputs get the *same*+ # colour tags before psnr. From FFmpeg 7.1 libavfilter negotiates colourspace, and psnr+ # on an untagged source vs a bt709-tagged output auto-inserts a real bt709->bt601+ # conversion on one side (8.x: 26 dB for a byte-identical picture) -- and, worse, hides+ # an encode-time conversion by undoing it (8.x reported 40 dB for an output whose pixels+ # had been re-matrixed, which is how the 7.1+ -colorspace bug in #156 went unnoticed on+ # macOS). With the tags pinned identical, every build from 5.1 to 8.1 reports the same+ # number for the same two files.+ same = "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv"+ proc = subprocess.run(["ffmpeg", "-hide_banner", "-i", str(a), "-i", str(b), "-lavfi",+ f"[0:v]setpts=N/FRAME_RATE/TB,{same}[a];[1:v]setpts=N/FRAME_RATE/TB,{same}[b];[a][b]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:]diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 7739e66..078f66c 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -23,6 +23,7 @@ CORPUS = ROOT / "tests" / "corpus"sys.path.insert(0, str(SCRIPTS))sys.path.insert(0, str(ROOT / "mcp"))import _contract # noqa: E402+import _common # noqa: E402import server as mcp_server # noqa: E402@@ -701,6 +702,48 @@ class ContractTests(unittest.TestCase):with self.assertRaises(SystemExit):rv.resolve("1.0.3", ["Fix y (#152)", "Big (#154)"], labels({152: ["fix"], 154: ["major"]}))+ # ------------------------------------------------------------------ FFmpeg-version-dependent spellings+ def test_drawtext_boxborderw_spelling_follows_the_ffmpeg_version(self):+ """drawtext's per-side `boxborderw=v|h` arrived in FFmpeg 6.1; 5.x and 6.0 reject the+ `|` outright ("Error setting option boxborderw"), which is how graphics.py's chapter and+ bug templates failed on the 5.1.1 CI job (#146). The helper picks the spelling from the+ parsed `ffmpeg -version`; pinned here with the version forced, so the rule survives+ without a 5.x binary on the machine running the tests."""+ saved = _common._FFMPEG_VERSION+ try:+ for version, expected in (((5, 1), "16"), ((6, 0), "16"), ((6, 1), "9|16"), ((7, 1), "9|16"), ((0, 0), "16")):+ _common._FFMPEG_VERSION = version+ self.assertEqual(_common.drawtext_boxborderw(9, 16), expected, version)+ finally:+ _common._FFMPEG_VERSION = saved+ _common._FFMPEG_VERSION = None+ major, minor = _common.ffmpeg_version()+ self.assertGreaterEqual(major, 5, "the real ffmpeg on PATH must parse to a sane version")+ self.assertIn(_common.drawtext_boxborderw(9, 16), ("16", "9|16"))++ def test_bt709_tags_go_through_encoder_vui_from_ffmpeg_7_1(self):+ """FFmpeg 7.1 added colourspace negotiation to libavfilter and feeds the output options+ -colorspace/-color_primaries/-color_trc into the graph's constraints: on a source with+ no colour tags at all, the CLI then auto-inserts a *real* matrix conversion (guessing+ bt601) into every SDR re-encode -- `color --lut-strength 0` came back 23.9 dB PSNR from+ its source on the debian-trixie job (#156), and every x264_args() user was affected.+ 5.x/6.x only ever wrote tags. From 7.1 the tags are written through the encoder's own+ VUI parameters, which libavfilter never sees; before it the old spelling stays, so the+ mp4 keeps its colr atom on the builds where that was the only way to get one."""+ saved = _common._FFMPEG_VERSION+ try:+ old = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]+ for version, expected in (((5, 1), old), ((6, 1), old), ((7, 0), old), ((0, 0), old),+ ((7, 1), ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]),+ ((8, 0), ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"])):+ _common._FFMPEG_VERSION = version+ self.assertEqual(_common.bt709_tag_args("libx264"), expected, version)+ self.assertEqual(_common.x264_args()[-len(expected):], expected, version)+ _common._FFMPEG_VERSION = (7, 1)+ self.assertEqual(_common.bt709_tag_args("libx265"), ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"])+ finally:+ _common._FFMPEG_VERSION = saved+# ------------------------------------------------------------------ consistency: MCP and installerdef test_mcp_tools_match_contract(self):mcp_names = [t["name"] for t in mcp_server.tool_list()]