ffmpeg-skill 2.24.0 → 2.24.1

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.24.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.24.1`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -131,7 +131,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"},
                  {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.24.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.24.1", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},
@@ -851,7 +851,7 @@ dry-run measurement of an earlier stage's output), `ffmpeg_list_unreadable` (`ff
 tool used to print to stderr only (emoji fallbacks, silent or short inputs, memory-heavy jobs,
 `--strip-dovi` without Dolby Vision, `render.py`'s frame-from-preset and `--normalize` defaults).
 `render.py`'s plan, check and cache records (`check_dry_run`, `check_output_unparsed`, `cache_entry_damaged`, ...),
-`export.py`'s `loudness_not_measured`, `loudness_outside_spec` and `colour_not_converted`, `multicam.py`'s
+`export.py`'s `loudness_not_measured`, `loudness_outside_spec`, `colour_not_converted`, `size_over_limit` and `repair_incomplete`, `multicam.py`'s
 `camera_not_started`, `report.py`'s `report_section_missing` and `batch.py`'s cache records
 (`batch_cache_reset`, `batch_cache_output_changed`, ...) are listed there too. Every one of them
 still prints its stderr line; the record is additive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.24.0",
+  "version": "2.24.1",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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/scripts/_common/probe.py

@@ -830,7 +830,9 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
 
 
 # What a stream-copy join compares (cut.py --segments, join.py --copy).
-IN_BAND_CONFIG = ("mp3", "mp2")
+# codecs that carry no out-of-band configuration in these containers, so no extradata on
+# either side is a match, not a difference
+IN_BAND_CONFIG = ("mp3", "mp2", "vp8", "vp9")
 TS_EXTS = (".ts", ".m2ts", ".mts")
 _SIG_FIELDS = {"video": ("codec_name", "profile", "pix_fmt", "width", "height", "r_frame_rate", "time_base",
                          "sample_aspect_ratio", "color_space", "color_range", "color_transfer", "color_primaries"),
@@ -879,8 +881,9 @@ def signatures_match(sigs: list, ext: str) -> bool:
 
 # check.py --compare (2.24): the output's picture against a reference, frame by frame.
 COMPARE_SSIM_WARN = 0.98   # mean SSIM below this: a visible difference somewhere is likely
-_SSIM_SUMMARY = re.compile(r"SSIM Y:[0-9.]+ .*All:([0-9.]+)")
-_PSNR_SUMMARY = re.compile(r"PSNR y:\S+ .*average:(\S+)")
+# the channel letters follow the negotiated format: Y U V (or y u v) for YUV, R G B for RGB
+_SSIM_SUMMARY = re.compile(r"SSIM [A-Za-z]:[0-9.]+ .*All:([0-9.]+)")
+_PSNR_SUMMARY = re.compile(r"PSNR [a-z]:\S+ .*average:(\S+)")
 _SSIM_FRAME = re.compile(r"n:(\d+) .*All:([0-9.]+)")
 
 
@@ -894,8 +897,13 @@ def compare_pictures(path: str, reference: str) -> "Optional[Dict[str, Any]]":
         stats = os.path.join(tmp, "ssim.log")
         # frames paired by index (settb/setpts=N): ssim and psnr otherwise pair by timestamp, so a
         # shifted or irregular timestamp would meet the wrong reference frame
-        graph = ("[0:V:0]settb=1/1000,setpts=N,split[a0][a1];[1:V:0]settb=1/1000,setpts=N,split[b0][b1];"
-                 f"[a0][b0]ssim=stats_file={escape_filter_path(stats, bind=False)};[a1][b1]psnr")
+        # shortest=1: by default the shorter file's last frame is repeated against the rest of
+        # the longer one, which measures pairs that do not exist. format=yuv444p on both: the
+        # filters otherwise take the first input's format, so an RGB file against a YUV one
+        # measured differently by argument order
+        graph = ("[0:V:0]settb=1/1000,setpts=N,format=yuv444p,split[a0][a1];"
+                 "[1:V:0]settb=1/1000,setpts=N,format=yuv444p,split[b0][b1];"
+                 f"[a0][b0]ssim=shortest=1:stats_file={escape_filter_path(stats, bind=False)};[a1][b1]psnr=shortest=1")
         proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-i", path, "-i", reference,
                              "-filter_complex", graph, "-f", "null", "-"], check=False, record=True)
         if proc.returncode != 0:

package/scripts/check.py

@@ -35,7 +35,7 @@ import json
 import re
 import sys
 from fractions import Fraction
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Tuple
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, resolve as resolve_platform
 from _common.probe import (COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
@@ -95,6 +95,12 @@ def frame_time(n: int, v: Dict[str, Any], meta: Dict[str, Any], pts: "Optional[L
     return f"~{lead + n / fps:.2f}s" if fps else f"frame {n}"
 
 
+def display_size(v: Dict[str, Any]) -> "Tuple[int, int]":
+    """The frame size as decoded and auto-rotated, which is what --compare's ffmpeg pass sees."""
+    w, h = int(v.get("width") or 0), int(v.get("height") or 0)
+    return (h, w) if int(v.get("rotation") or 0) % 180 == 90 else (w, h)
+
+
 def _span_total(spans: Any) -> float:
     return sum(max(0.0, e - s) for s, e in spans)
 
@@ -147,6 +153,15 @@ def main() -> int:
     if args.max_mb is not None:
         spec["max_bytes"] = int(args.max_mb * 1024 * 1024)
 
+    expected_identity = None
+    if args.expect_identity is not None:
+        # parsed before any measurement; "" (an unset shell variable) is malformed, not absent
+        try:
+            size, mtime_ns = (int(x) for x in args.expect_identity.split(":"))
+        except ValueError:
+            die(f"--expect-identity takes SIZE:MTIME_NS from a tool's output_identity, got {args.expect_identity!r}")
+        expected_identity = {"size": size, "mtime_ns": mtime_ns}
+
     # read before anything is measured and again after: a file replaced mid-check is not the one graded
     identity_before = None if dry_run_input_pending(args.input) else file_identity(args.input)
     meta = probe(args.input)
@@ -368,8 +383,8 @@ def main() -> int:
         if not v or not rv:
             row("similarity", "WARN", "not compared", "two pictures", "--compare needs a video stream in both files",
                 reason="one of the files has no picture")
-        elif (v.get("width"), v.get("height")) != (rv.get("width"), rv.get("height")):
-            row("similarity", "WARN", f"not compared: {v.get('width')}x{v.get('height')} vs {rv.get('width')}x{rv.get('height')}",
+        elif display_size(v) != display_size(rv):
+            row("similarity", "WARN", "not compared: %dx%d vs %dx%d (as displayed)" % (display_size(v) + display_size(rv)),
                 "the same frame size", "compare against a reference at the delivery size (fit.py or export.py it first)",
                 reason="SSIM and PSNR compare pixels, so the two frames must be the same size")
         else:
@@ -393,17 +408,15 @@ def main() -> int:
                 nref = rv.get("nb_frames") or len(presentation_times(args.compare, float(rv.get("start_time") or 0.0))) or None
                 if nref and nout and int(nref) != int(nout):
                     STATE_NOTES.append(f"--compare: {nout} frames against the reference's {nref}; frames were paired in "
-                                       f"order, so an added or dropped frame shifts every later pair")
+                                       f"order, so an added or dropped frame shifts every later pair, and only the "
+                                       f"first {min(int(nref), int(nout))} were compared")
     # read after every measurement, --compare's included, so a replacement at any point shows
     identity = None if dry_run_input_pending(args.input) else file_identity(args.input)
-    if identity is not None and identity != identity_before and not args.expect_identity:
+    if identity is not None and identity != identity_before and expected_identity is None:
         STATE_NOTES.append("the file changed while it was being checked: input_identity is the file as it was "
                            "at the end, and the rows may describe an earlier one; check it again")
-    if args.expect_identity:
-        try:
-            size, mtime_ns = (int(x) for x in args.expect_identity.split(":"))
-        except ValueError:
-            die(f"--expect-identity takes SIZE:MTIME_NS from a tool's output_identity, got {args.expect_identity!r}")
+    if expected_identity is not None:
+        size, mtime_ns = expected_identity["size"], expected_identity["mtime_ns"]
         if identity is not None:
             changed = identity != identity_before
             same = identity == {"size": size, "mtime_ns": mtime_ns} and not changed

package/scripts/cut.py

@@ -80,7 +80,11 @@ def keep_ranges_after_removing(removed: List[Tuple[float, float]], total: float,
     piece anyone asked to keep. Refuses a removal that would leave nothing."""
     least = 1.0 / fps if fps else 0.01
     keep, cursor = [], 0.0
-    for s, e in sorted((max(0.0, s), min(total, e)) for s, e in removed):
+    outside = [(s, e) for s, e in removed if min(total, e) <= min(total, max(0.0, s))]
+    if outside:
+        die("--remove " + ", ".join(f"{s:g}-{e:g}" for s, e in outside) + f" lies outside the file (0-{total:.3f}s), "
+            "so it removes nothing; check the units (seconds, mm:ss)")
+    for s, e in sorted((min(total, max(0.0, s)), min(total, e)) for s, e in removed):
         if e <= cursor:
             continue
         if s - cursor >= least:

package/scripts/export.py

@@ -249,16 +249,20 @@ _TIMESTAMP_WARNING = re.compile(r"(?i)\b(dts|pts)\b|timestamp")
 def media_damage(path: str) -> Dict[str, int]:
     """One full decode of `path` at -v warning: lines about timestamps (non-monotonic DTS, invalid
     PTS) and every other error line, counted. What --repair is measured by, before and after."""
-    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "warning", "-i", path, "-f", "null", "-"],
+    # repeat+: every occurrence on its own line, not "Last message repeated N times", which hid
+    # N timestamp warnings and was itself counted as a decode error
+    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "repeat+warning", "-i", path, "-f", "null", "-"],
                         check=False, record=True)
     lines = [ln for ln in (proc.stderr or "").splitlines() if ln.strip()]
-    stamps = sum(1 for ln in lines if _TIMESTAMP_WARNING.search(ln))
+    # "Packet corrupt (stream = 0, dts = ...)" names a dts but is damage, not a timestamp problem
+    stamps = sum(1 for ln in lines if _TIMESTAMP_WARNING.search(ln) and "corrupt" not in ln.lower())
     return {"timestamp_warnings": stamps, "decode_errors": len(lines) - stamps}
 
 
 MIB = 1024 * 1024
 SIZE_HEADROOM = 0.97        # of the byte budget given to the streams; the rest is container overhead
 SIZE_MIN_VIDEO_KBPS = 100   # below this the picture is not worth delivering; refused instead
+SIZE_MAX_VIDEO_KBPS = 400_000  # 400 Mb/s: above any delivery line, and libx264 refuses far larger values
 
 
 def size_video_args(args, video: List[str], p: Dict, meta: Dict, has_audio: bool) -> List[str]:
@@ -281,6 +285,9 @@ def size_video_args(args, video: List[str], p: Dict, meta: Dict, has_audio: bool
     if has_audio and "-b:a" in p["audio"]:
         audio_kbps = float(p["audio"][p["audio"].index("-b:a") + 1].rstrip("k"))
     video_kbps = args.max_mb * MIB * 8 * SIZE_HEADROOM / dur / 1000 - audio_kbps
+    if video_kbps > SIZE_MAX_VIDEO_KBPS:
+        die(f"--max-mb {args.max_mb:g} allows {video_kbps / 1000:.0f} Mb/s over {dur:.1f}s, beyond any delivery bitrate; "
+            "a limit that large constrains nothing", hint="drop --max-mb (the preset's quality setting applies)")
     if video_kbps < SIZE_MIN_VIDEO_KBPS:
         die(f"--max-mb {args.max_mb:g} leaves {max(video_kbps, 0):.0f} kb/s for the picture over {dur:.1f}s "
             f"(after {audio_kbps:.0f} kb/s of audio); under {SIZE_MIN_VIDEO_KBPS} kb/s it is not watchable",
@@ -365,6 +372,9 @@ def main() -> int:
             vf.append(f"scale={p['w']}:-2")
     if args.repair and args.preset != "copy":
         die("--repair is a remux: use it with --preset copy (a re-encoding preset already rebuilds every frame)")
+    if args.max_mb is not None and args.preset == "gif":
+        # the GIF branch below returns before the size is ever applied or measured
+        die("--max-mb runs a two-pass x264 encode; --preset gif does not encode with x264 (shorten or shrink the GIF instead)")
     cmd = ffmpeg_base() + (REPAIR_INPUT_ARGS if args.repair else []) + ["-i", args.input]
     # Subtitle and data streams (a soft-subtitle track muxed upstream, a camera's timecode) are
     # kept where the container can hold them: ffmpeg's default stream selection takes one video

package/scripts/join.py

@@ -345,6 +345,45 @@ def _video_packets(path: str, limit: "Optional[int]" = None) -> "List[str]":
     return (proc.stdout or "").split() if proc.returncode == 0 else []
 
 
+SPAN_HEAD_PACKETS = 64     # enough to see the earliest presentation time past B-frame reordering
+SPAN_TAIL_SECONDS = 10.0   # read from this far before the end, so a seek that lands early still reaches it
+
+
+def _stream_span(path: str, kind: str, duration: float = 0.0, start: float = 0.0) -> "Optional[Tuple[float, float]]":
+    """First packet's time and last packet's time plus its duration for the first `kind` stream
+    (V or a): measured, because Matroska/WebM state no stream length and MPEG-TS only an estimate.
+    None when the packets cannot be read or one has no time: a partial span would invent a gap."""
+    # JSON, not csv: older ffprobe builds (5.1) print side-data rows between the packet rows in csv.
+    # A long clip is read at its head and its tail only: every packet of a two-hour file is
+    # hundreds of thousands of entries for two numbers
+    cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", f"{kind}:0", "-show_entries",
+           "packet=pts_time,dts_time,duration_time", "-of", "json"]
+    if duration > 3 * SPAN_TAIL_SECONDS:
+        # read_intervals takes timestamps, so the tail starts from the file's own start time
+        # (an MPEG-TS clock can start hours in; an edit list can start it below zero)
+        cmd += ["-read_intervals", f"%+#{SPAN_HEAD_PACKETS},{start + duration - SPAN_TAIL_SECONDS:.3f}%"]
+    proc = run(cmd + [path], quiet=True, check=False)
+    try:
+        packets = json.loads(proc.stdout or "{}").get("packets") or [] if proc.returncode == 0 else []
+    except ValueError:
+        return None
+    times = []
+    for pkt in packets:
+        try:
+            # a packet ffprobe gives no pts (some muxers leave it on B-frames) still has its dts
+            t = float(pkt.get("pts_time", pkt.get("dts_time")))
+        except (TypeError, ValueError):
+            return None
+        try:
+            d = float(pkt.get("duration_time") or 0.0)
+        except (TypeError, ValueError):
+            d = 0.0
+        times.append((t, t + d))
+    if not times:
+        return None
+    return min(t for t, _ in times), max(e for _, e in times)
+
+
 def join_copy(args, metas: List[Dict[str, Any]]) -> int:
     """--copy: the concat demuxer with -c copy, after checking that the clips can be joined that
     way, and measured afterwards (video packet count and length against the clips')."""
@@ -354,6 +393,11 @@ def join_copy(args, metas: List[Dict[str, Any]]) -> int:
         die("--copy keeps every clip's own frame and rate: --width, --height and --fps need a re-encode, so drop --copy")
     if args.sample_rate or args.channels:
         die("--copy keeps every clip's own sound: --sample-rate and --channels need a re-encode, so drop --copy")
+    encoder = [f for f, on in (("--codec", STATE.codec), ("--hw", STATE.hw and STATE.hw_source == "flag"),
+                               ("--quality", getattr(args, "quality_given", False)))
+               if on]
+    if encoder:
+        die(f"--copy keeps every clip's own encoding: {', '.join(encoder)} choose(s) an encode, so drop --copy")
     output = args.output or default_output(args.inputs[0], "joined", os.path.splitext(args.inputs[0])[1].lstrip(".") or "mp4")
     guard_sidecar(output, *args.inputs)
     ext = os.path.splitext(output)[1].lower()
@@ -391,15 +435,19 @@ def join_copy(args, metas: List[Dict[str, Any]]) -> int:
                    hint="drop --copy, or re-cut those clips with cut.py --accurate", clips=[{"path": p, "differs": {"edit_list": True}} for p in hidden])
         gaps = []
         for p, m in zip(args.inputs, metas):
-            # each stream's start, and its end (start plus length) where the container states one;
-            # Matroska/WebM give no stream length, but the starts still have to agree
-            vs, as_ = m.get("video") or {}, m.get("audio") or {}
-            if not (vs and as_):
+            # each stream's span from its packets: Matroska/WebM state no stream length and an
+            # MPEG-TS stream length is an estimate, so a stated duration missed or invented gaps
+            if not (m.get("video") and m.get("audio")):
                 continue
-            vb, ab = float(vs.get("start_time") or 0.0), float(as_.get("start_time") or 0.0)
-            vd, ad = vs.get("duration"), as_.get("duration")
-            ve, ae = (vb + vd if vd else None), (ab + ad if ad else None)
-            if abs(vb - ab) > COPY_AV_GAP or (ve is not None and ae is not None and abs(ve - ae) > COPY_AV_GAP):
+            length, origin = float(m.get("duration") or 0.0), float(m.get("start_time") or 0.0)
+            v_span, a_span = _stream_span(p, "V", length, origin), _stream_span(p, "a", length, origin)
+            if v_span is None or a_span is None:
+                refuse("input", "join_copy_mismatch",
+                       f"--copy: could not measure where picture and sound start and end in {p} (a packet without a "
+                       "time), so a gap at the join could not be ruled out", hint="drop --copy to re-encode the join",
+                       clips=[{"path": p, "differs": {"av_span": "unmeasured"}}])
+            (vb, ve), (ab, ae) = v_span, a_span
+            if abs(vb - ab) > COPY_AV_GAP or abs(ve - ae) > COPY_AV_GAP:
                 gaps.append({"path": p, "video": [round(vb, 3), None if ve is None else round(ve, 3)],
                              "audio": [round(ab, 3), None if ae is None else round(ae, 3)]})
         if gaps:
@@ -452,7 +500,8 @@ def join_copy(args, metas: List[Dict[str, Any]]) -> int:
     info(f"wrote {output} ({fmt_secs(r.get('duration'))}, {n} clips, stream copy)")
     emit(output, mode="copy", **reported(), clips=n, transition="none", reencoded=False,
          verification=verification, expect_streams={"video": 1, "audio": 1 if all(m.get("audio") for m in metas) else 0},
-         stream_reference=metas)
+         stream_reference=metas,
+         dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0
 
 
@@ -492,6 +541,8 @@ def main() -> int:
     aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
     add_common(ap)
     args = ap.parse_args()
+    # given at all, not only different from the default: --quality 18 asks for an encode as much as 23 does
+    args.quality_given = any(a == "--quality" or a.startswith("--quality=") for a in sys.argv[1:])
     apply_common(args)
     if args.fps is not None and args.fps <= 0:
         die(f"--fps must be positive, got {args.fps:g}")

package/scripts/render.py

@@ -1192,7 +1192,12 @@ def main() -> int:
         work.mkdir(parents=True, exist_ok=True)
     except OSError as e:
         die(f"cannot create the work directory {work}: {e}")
-    if not args.keep and not args.work:
+    # --stop-after before the export reports a stage file inside the work directory as its output:
+    # removing the directory at exit deleted the file the result named (and its output_identity)
+    previewing = bool(args.stop_after) and args.stop_after != "export" and not STATE.dry_run
+    if previewing and not args.keep and not args.work:
+        info(f"--stop-after {args.stop_after}: keeping the work directory {work}, since the result's output is in it")
+    if not args.keep and not args.work and not previewing:
         # a failed or dry run used to leave <output>_work_<pid>/ behind (sweep F15): the
         # auto-named directory is ours alone, so remove it on every exit path
         import atexit