ffmpeg-skill 1.1.0 → 1.1.1

package/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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 40 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/ci-platform-pitfalls.md

@@ -109,3 +109,59 @@ When a test needs to special-case a platform, prefer gating with
 mechanism, and write the skip/relaxation reason as a full sentence
 explaining the underlying platform behaviour — not just "flaky on
 Windows" — 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.

package/scripts/_common.py

@@ -15,7 +15,7 @@ import subprocess
 import sys
 from fractions import Fraction
 from 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) -> Lis
     return ["-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 args
 
 

package/scripts/export.py

@@ -26,7 +26,7 @@ import sys
 from pathlib import Path
 from 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_color
 
 PRESETS: 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"])

package/scripts/graphics.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from 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_boxborderw
 
 TEMPLATES = ["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))

package/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 = None
     for 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:
                 pass
     cuts = [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 = 12
     for i, sc in enumerate(scores):
         if sc < threshold:

package/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)