ffmpeg-skill 2.2.2 → 2.2.3

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.2.2`) | any release |
+| `skill.version` | the npm / package.json version (`2.2.3`) | 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`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.2.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.2.3", "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)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -492,6 +492,12 @@ Per-tool keys added in 1.18.0, all additive:
 | `sources` | `sync.py` | `[{path, offset_s, confidence, drift_ppm}]`, one entry per SOURCE. Present for every run, including the original single-SOURCE shape (where it mirrors the top-level `second`/`offset_seconds`/`confidence` additively). With 2+ SOURCEs it is the *only* per-source shape: there is no top-level `second`/`offset_seconds` because there is no single pair to put there |
 | `switch_mode`, `min_shot` | `multicam.py --switch energy` | `"energy"` and the `--min-shot` value used (default 1.5s), alongside the existing `cuts` (`[[start, end, camera], ...]`) which already carries the camera index for `--edl`'s companion cut list |
 
+Per-tool keys added after 2.2.2, all additive:
+
+| key | tool | what it holds |
+|---|---|---|
+| `sdr_path`, `notes` | `color.py --to-sdr` | `sdr_path` is `"tonemap"` for PQ / HLG / Dolby Vision input (and `--force` on an untagged file) or `"gamut"` for BT.2020 primaries on an SDR transfer, which is converted to BT.709 without a tone map (`--tonemap`/`--peak`/`--desat` do not apply); `notes` says which path was taken and why |
+
 `check.py` also gains an informational `subtitles` row on **every** platform:
 `PASS` when every soft subtitle stream carries a language tag, `WARN` when one
 does not (or when there are none). Like `channels` and `chapters` it is never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "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/references/scripts.md

@@ -573,7 +573,11 @@ frame, rate or xfade offsets that rest on a pending input's unmeasured placehold
 Normalises every clip to one frame size, fps, `yuv420p`, 48 kHz and one
 channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`;
 silent track generated for clips without audio), then chains `xfade` +
-`acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
+`acrossfade`. With a transition each clip has one length for picture and sound
+-- the video stream's, or the audio's when it runs more than a frame longer --
+and the shorter stream is padded (silence / last frame held), so every clip's
+sound stays with its picture. Output length = sum of clip lengths −
+transition × (n−1); `verified` checks the output's video-stream length against it. Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
 A subtitle/data track in the source is not carried into the retimed/concatenated
 output; the result says so with `dropped_non_av_streams: true`.

package/scripts/_common/probe.py

@@ -283,6 +283,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "color_range": video.get("color_range"),
             "rotation": rotation,
             "nb_frames": _to_int(video.get("nb_frames")),
+            # the stream's own length (a container's also counts audio priming and a longer track)
+            "duration": _to_float(video.get("duration")),
             "bitrate": _to_int(video.get("bit_rate")),
         }
     if audio:
@@ -292,6 +294,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "channel_layout": audio.get("channel_layout"),
             "sample_rate": _to_int(audio.get("sample_rate")),
             "bitrate": _to_int(audio.get("bit_rate")),
+            "duration": _to_float(audio.get("duration")),
         }
         # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
         out["audio_streams"] = [{

package/scripts/_contract.py

@@ -443,6 +443,11 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"measured": {"type": "object", "description": "the loudnorm measurement of the input (input_i, input_tp, input_lra, input_thresh, target_offset); with --measure-only it is the whole result"},
                  "targets": {"type": "object", "description": "the requested lufs / tp / lra"},
                  "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"}}
+    elif name == "color":
+        extra = {"dropped_non_av_streams": {"type": "boolean"},
+                 "sdr_path": {"enum": ["tonemap", "gamut"], "description": "--to-sdr only: tonemap for PQ / HLG / Dolby Vision (and --force on an untagged file); gamut for BT.2020 primaries on an SDR transfer, converted to BT.709 without a tone map"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--to-sdr only: which path was taken and why"},
+                 "measurements": {"type": "object", "description": "--correct only: signalstats levels of input and output"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},

package/scripts/color.py

@@ -169,12 +169,36 @@ def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str
     return ",".join(chain)
 
 
+def bt2020_sdr_to_bt709_chain(meta: dict) -> str:
+    """Gamut conversion only, for BT.2020 primaries on an SDR transfer (probe: `bt2020_or_hdr`
+    true, `hdr_signal` false). Such a file is already display-referred SDR: linearising it with
+    its own transfer, mapping the primaries to BT.709 and re-applying the BT.709 transfer keeps
+    white at white and grey at grey. The tone map the HDR chain adds would treat 100 % SDR white
+    as a fraction of a 1000-nit peak and darken the picture (white Y 235 -> 151, grey 126 -> 90)."""
+    v = meta["video"]
+    trc = v.get("color_transfer") or "bt709"
+    space = v.get("color_space") or "bt2020nc"
+    return ",".join([
+        f"zscale=tin={trc}:pin=bt2020:min={space}:rin={v.get('color_range') or 'tv'}:t=linear",
+        "format=gbrpf32le",
+        "zscale=p=bt709",
+        "zscale=t=bt709:m=bt709:r=tv",
+        "format=yuv420p",
+    ])
+
+
+def is_bt2020_sdr(v: dict) -> bool:
+    """BT.2020 primaries on a non-HDR transfer and no Dolby Vision: gamut-only --to-sdr."""
+    return bool(v.get("bt2020_or_hdr")) and not v.get("hdr_signal") and not v.get("dolby_vision") \
+        and v.get("color_transfer") not in ("smpte2084", "arib-std-b67")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_sdr / _lut / _retag)")
     mode = ap.add_mutually_exclusive_group(required=True)
-    mode.add_argument("--to-sdr", action="store_true", help="tone-map HDR (PQ/HLG/BT.2020) to SDR BT.709")
+    mode.add_argument("--to-sdr", action="store_true", help="convert to SDR BT.709: tone-map HDR (PQ/HLG/Dolby Vision); BT.2020 primaries on an SDR transfer get a gamut conversion only, no tone map")
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
@@ -183,7 +207,7 @@ def main() -> int:
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
     ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
-    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
+    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is tagged neither HDR nor BT.2020 (tone-mapped as PQ; a BT.2020 SDR file never needs it)")
     ap.add_argument("--exposure", type=float, default=CORRECTION["exposure"][0], help="--correct: exposure in stops, -3..3 (default 0)")
     ap.add_argument("--contrast", type=float, default=CORRECTION["contrast"][0], help="--correct: contrast, 0..2, 1=unchanged (default 1)")
     ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
@@ -278,10 +302,21 @@ def main() -> int:
         return 0
 
     measurements = None
+    sdr_extra: dict = {}
     if args.to_sdr:
         if not v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
-        vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+        if is_bt2020_sdr(v):
+            vf = bt2020_sdr_to_bt709_chain(meta)
+            sdr_path = "gamut"
+            note = (f"BT.2020 primaries on an SDR transfer ({v.get('color_transfer')}): converted the gamut to BT.709 "
+                    f"without a tone map (--tonemap/--peak/--desat do not apply)")
+        else:
+            vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+            sdr_path = "tonemap"
+            note = f"tone-mapped {v.get('hdr_format') or 'untagged input as PQ (--force)'} to SDR BT.709 with {args.tonemap}"
+        info(f"note: {note}")
+        sdr_extra = {"sdr_path": sdr_path, "notes": [note]}
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
     elif args.correct:
@@ -323,7 +358,7 @@ def main() -> int:
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
-    extra = {"dropped_non_av_streams": dropped_streams}
+    extra = {"dropped_non_av_streams": dropped_streams, **sdr_extra}
     if measurements is not None:
         measurements["output"] = analyze_levels(output)
         extra["measurements"] = measurements

package/scripts/join.py

@@ -63,6 +63,20 @@ def unpending_length(durs: List[float], d: float) -> Optional[float]:
     return round(sum(durs) - d * (len(durs) - 1), 3)
 
 
+def clip_length(meta: Dict[str, Any], fps: float) -> float:
+    """The one length a clip holds in a crossfaded join, for its picture and its sound alike: the
+    video stream's, or the audio stream's when the sound runs more than a frame past the picture
+    (narration is never cut; an AAC tail adds no frame). The container duration (audio priming,
+    a longer track) is only the fallback when a stream length is unknown (a pending input)."""
+    v = (meta.get("video") or {}).get("duration")
+    a = (meta.get("audio") or {}).get("duration")
+    if not v:
+        return meta.get("duration") or 0.0
+    if a and fps and a > v + 1.0 / fps:
+        return a
+    return v
+
+
 def expected_text(expected: Optional[float]) -> str:
     """unpending_length() as the stderr summary line puts it."""
     return f"expected ~{expected:.3f}s" if expected is not None else "expected length unknown until the pending inputs exist"
@@ -293,7 +307,10 @@ def main() -> int:
     w, h = w - (w % 2), h - (h % 2)
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
-    for p, dur in zip(args.inputs, durs):
+    # a crossfaded join gives each clip one length for both streams, so the offsets that place
+    # every picture also place its sound; the plain cut (concat) keeps the streams paired itself
+    lens = [clip_length(m, fps) for m in metas] if d else durs
+    for p, dur in zip(args.inputs, lens):
         if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
 
@@ -347,14 +364,22 @@ def main() -> int:
         chain = "".join(f"[v{i}][a{i}]" for i in range(n))
         parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
     else:
-        vprev, aprev = "v0", "a0"
+        # pad the shorter stream to the clip's length: the audio with silence, the picture by
+        # holding its last frame, then cut both there -- each xfade and acrossfade then starts
+        # at the same clip boundary instead of the audio chain drifting by every clip's gap
+        for i in range(n):
+            vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
+            hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
+            parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
+            parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
+        vprev, aprev = "vp0", "ap0"
         offset = 0.0
         for i in range(1, n):
-            offset += durs[i - 1] - d
+            offset += lens[i - 1] - d
             vout = f"vx{i}" if i < n - 1 else "vout"
             aout = f"ax{i}" if i < n - 1 else "aout"
-            parts.append(f"[{vprev}][v{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
-            parts.append(f"[{aprev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
+            parts.append(f"[{aprev}][ap{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
             vprev, aprev = vout, aout
 
     # A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
@@ -367,12 +392,26 @@ def main() -> int:
                            "by its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    if d:
+        # the fps filter already made the picture constant-rate and xfade places every frame: FFmpeg
+        # 5.1's default cfr output mode still duplicated the last one to meet the AAC tail (a 51-frame
+        # dissolve came out 52), which newer builds no longer do -- pass the frames through as built
+        cmd += ["-fps_mode", "passthrough"]
     cmd += video_args(hdr_meta or metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
-    expected = unpending_length(durs, d)
+    expected = unpending_length(lens, d)
     r = probe(output, role="output")
-    info(f"wrote {output} ({fmt_secs(r['duration'])}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
+    # the picture is what the offsets place: measure the video stream, not the container (whose
+    # length also counts the AAC tail), against the length the clips add up to
+    measured = (r.get("video") or {}).get("duration") or r.get("duration")
+    verification = []
+    if expected is not None and measured is not None and not STATE.dry_run:
+        tol = max(1.5 / fps, 0.05)
+        verification.append({"step": "duration", "ok": abs(measured - expected) <= tol,
+                             "measured": round(measured, 3), "expected": expected, "tolerance": round(tol, 3)})
+    info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     emit(output, mode="video", **reported(), clips=n, transition=args.transition, expected_duration=expected,
+         verification=verification,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0