ffmpeg-skill 0.4.0 → 0.5.0

package/README.md

@@ -17,6 +17,9 @@ npx ffmpeg-skill
 - **Probe first, verify last** — the skill forces the agent to read real duration/fps/resolution before editing and to check the result after, so you get "final.mp4: 59.98 s, 1080×1920, 30 fps" instead of guesses.
 - **Lossless when possible** — cuts and joins use stream copy by default; re-encoding only happens when it must (frame-accurate cuts, filters, format changes).
 - **Cut & join** segments with `mm:ss` / `hh:mm:ss.ms` times.
+- **Declarative edits** — describe the whole edit in a `project.json` (clips, transitions, captions, overlays, music, loudness, export, check) and re-render after every tweak.
+- **Scene detection and highlight picks** — find cuts and loud moments, get a 60-second digest proposal as a cut list.
+- **Delivery checks** — PASS/FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, broadcast and podcast specs, with the fix for each failure.
 - **Multicam** — align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list.
 - **Real-footage verification kit** — run the whole toolchain on your own device files and get a PASS/FAIL report.
 - **Silence removal / jump cuts** — detect dead air, keep a margin around speech, render frame-accurate in one pass; export the cut list for hand editing.
@@ -92,6 +95,9 @@ More examples: [examples/README.md](examples/README.md). To see everything run e
 |--------|--------------|
 | `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision, colour space, rotation, audio channels as JSON; `--analyze` flags Log footage |
 | `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
+| `render.py` | Render a whole edit from `project.json`; `--init`, `--dry-run`, `--stop-after` |
+| `scenes.py` | Scene changes, audio peaks, highlight proposals and per-scene sheet |
+| `check.py` | Pre-delivery compliance per platform (duration, aspect, codec, colour, loudness, size) |
 | `multicam.py` | Align cameras/recorders by audio and switch between them from a time list |
 | `verify.py` | Run the toolchain on real device files and report PASS/FAIL per step |
 | `silence.py` | Detect and remove silences (jump cuts), list or export the cut list |
@@ -119,6 +125,7 @@ All scripts: Python 3.9+, standard library only, `--help`, non-zero exit + stder
 ```bash
 bash examples/make_demo.sh      # generates footage, runs every script, rebuilds assets/demo.gif
 python3 tests/test_all.py       # end-to-end tests incl. VFR, rotated, 5.1, 10-bit HDR10 and drifting sources (needs ffmpeg)
+python3 evals/run.py --list     # routing eval prompts (see evals/)
 node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude
 ```
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ffmpeg-skill
-description: Professional video editing with local FFmpeg — cut, remove silences, join with transitions, multicam switching, caption (animated/karaoke timed to speech), fit to duration/aspect, sync audio with drift correction, HDR/HLG/Dolby Vision to SDR, LUTs and Log detection, denoise/duck/mix audio, loudness, overlays, platform exports, frame inspection and a real-footage verification kit; Python stdlib scripts, no cloud or API keys.
+description: Professional video editing with local FFmpeg — declarative project rendering, scene detection and highlight picks, delivery compliance checks, cut, silence removal, transitions, multicam, captions (animated/karaoke timed to speech), fit to duration/aspect, audio sync with drift correction, HDR/HLG/Dolby Vision to SDR, LUTs, audio clean-up and ducking, loudness, overlays, platform exports, frame inspection and a real-footage verification kit; Python stdlib scripts, no cloud or API keys.
 ---
 
 # ffmpeg-skill
@@ -30,15 +30,23 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
    `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
    prints percent and ETA on stderr for long encodes.
 4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
-   fit → caption/overlay → sync → audio → loudness → export. Do the destructive/aspect changes before burning
-   text so captions are sized for the final frame. Re-encode as few times as
-   possible: if several re-encoding steps are needed, keep intermediates at
-   CRF 18 (the default) and only use `export.py` for the last step.
-5. **Verify the output.** Run `probe.py` on each result and confirm duration,
+   join → silence → fit → caption/overlay → sync → audio → loudness → export.
+   Do frame changes (fit/crop) before captions and overlays so text is sized
+   for the final frame. Re-encode as few times as possible: keep intermediates
+   at CRF 18 (the default) and only use `export.py` for the last step; for
+   anything with more than two steps use `render.py` with a project.json.
+5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X`
+   for the destination the user named; fix FAILs, mention WARNs.
+6. **Verify the output.** Run `probe.py` on each result and confirm duration,
    resolution, fps and audio match what was requested. Report those numbers to
    the user (e.g. "final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo").
-6. **Keep the user's originals.** Never overwrite the source file. Write new
+7. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
+8. **Look at the picture.** After captioning, overlaying, cropping or colour
+   work run `look.py OUTPUT` (contact sheet) or `look.py OUTPUT --at T` and
+   view the PNG: text inside the frame and not over faces, logos where asked,
+   crops keeping the subject, colours not washed out. Fix and re-run before
+   reporting. Numbers from probe are not enough.
 
 ## Request → script
 
@@ -61,6 +69,9 @@ path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
 | "stitch these clips together", "add a crossfade between them" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
 | "show me what it looks like", "check the captions are readable" | `look.py output.mp4` then view the PNG |
 | "what would you run?", "don't render yet" | any script with `--dry-run` |
+| "make a 60 s highlight from this hour", "find the good bits" | `scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt` → `cut.py --segments` |
+| "is this OK to upload?", "check it meets the Reels spec" | `check.py final.mp4 --platform reels` |
+| "set it up so I can tweak and re-render", "several changes to the same edit" | `render.py --init project.json`, edit, `render.py project.json` |
 | "three cameras, cut between them" | `multicam.py camA.mp4 camB.mp4 camC.mp4 --switch "0-20:0,20-40:1,40-60:2"` |
 | "it's an iPhone Dolby Vision clip and players show it wrong" | `color.py clip.mov --to-sdr` or `color.py clip.mov --strip-dovi` (keep HDR, drop the DV layer) |
 | "does it look like Log / S-Log / flat footage?" | `probe.py clip.mp4 --analyze` (`looks_like_log`) then `color.py --lut` |
@@ -132,6 +143,36 @@ Normalises every clip to one frame size, fps, `yuv420p` and 48 kHz stereo
 `acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
 
+### render.py — the whole edit in one project.json
+```
+render.py --init project.json                # starter file
+render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep]
+```
+Stages: clips (cut, optional speed) → join (transition) → silence → fit →
+captions → overlays → audio → loudness → export → check. Keys mirror the
+CLI flags of each script (see the docstring). Use it whenever an edit has
+more than two steps or the user is likely to ask for changes: edit the JSON,
+re-render, and the result is reproducible. `--dry-run --json` prints the
+complete command plan for review.
+
+### scenes.py — scene changes and highlight candidates
+```
+scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
+```
+Lists scenes with audio energy, the loudest moments, and (with
+`--highlights`) proposes N ranges that add up to `--target` seconds, biased to
+the loudest window of each scene. Review the sheet + JSON, adjust the EDL, then
+`cut.py --segments`. It is a proposal engine, not a judgement of content:
+tell the user what it picked and why (energy, scene length).
+
+### check.py — pre-delivery compliance
+```
+check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|broadcast|podcast|custom [--no-loudness] [--json]
+         [--max-duration S] [--aspect 9:16] [--lufs -14] [--tp -1] [--max-mb N]
+```
+PASS/WARN/FAIL per check with the script that fixes it. Run it as the final
+step before reporting a deliverable; fix FAILs, mention WARNs.
+
 ### multicam.py — align several cameras and switch between them
 ```
 multicam.py REF CAM2 [CAM3 ...] [--switch "START-END:CAM,..."] | [--auto N] [--audio IDX] [--fix-drift]
@@ -263,10 +304,14 @@ trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
   After `sync.py`, verify by running it again on the output: offset (and drift
   ppm with `--fix-drift`) should be ~0. Recordings longer than ~10 minutes from
   separate devices: always use `--fix-drift`.
-- **Colour.** All H.264/H.265 outputs are tagged BT.709 and `yuv420p`. When
-  `probe.py` reports `hdr: true` (`hdr_format` HDR10/PQ, HLG or BT.2020), run
-  `color.py --to-sdr` **first**; other scripts would tag the HDR picture as
-  BT.709 and it would look flat and desaturated (`export.py` warns about this).
+- **Colour.** SDR outputs are H.264 tagged BT.709 `yuv420p`. When `probe.py`
+  reports `hdr: true` (HDR10/PQ, HLG, Dolby Vision, BT.2020), every editing
+  script keeps the output HDR (HEVC Main10, source colour tags) so nothing is
+  silently flattened. Decide with the user: keep HDR (fine for YouTube/phones)
+  or run `color.py --to-sdr` first for SDR-only destinations, LUT work or
+  H.264 deliverables. `export.py` platform presets are SDR and warn on HDR
+  input. iPhone `.mov` files also carry timecode/metadata tracks; scripts map
+  only the first audio track, so extra tracks are dropped on re-encode.
   For Log footage (S-Log, V-Log, C-Log: looks grey and low-contrast but is
   tagged SDR) run `probe.py --analyze`; `looks_like_log: true` means apply the
   manufacturer's `.cube` with `color.py --lut` before anything else. Keep

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.4.0",
-  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: cut, silence removal, transitions, multicam, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
+  "version": "0.5.0",
+  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: declarative project rendering, scene detection, delivery checks, cut, silence removal, transitions, multicam, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
   "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
   "license": "MIT",
   "author": "kajisho5",

package/scripts/_common.py

@@ -55,6 +55,7 @@ def require_tool(name: str) -> str:
     return ""  # unreachable
 
 
+X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
 STATE: Dict[str, Any] = {"dry_run": False, "json": False, "commands": [], "progress": False, "fast": False, "duration_hint": None}
 
 
@@ -72,7 +73,7 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE["json"] = bool(getattr(args, "json", False))
     STATE["progress"] = bool(getattr(args, "progress", False))
     STATE["fast"] = bool(getattr(args, "fast", False))
-    if STATE["fast"] and hasattr(args, "preset"):
+    if STATE["fast"] and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
 
 
@@ -163,7 +164,7 @@ def probe(path: str) -> Dict[str, Any]:
     if not os.path.exists(path):
         if STATE["dry_run"]:
             return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
-                    "video": {"codec": None, "width": 0, "height": 0, "fps": None, "pix_fmt": None, "hdr": False,
+                    "video": {"codec": None, "width": 1920, "height": 1080, "fps": 30.0, "pix_fmt": None, "hdr": False,
                               "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
                     "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0}
         die(f"input not found: {path}")
@@ -331,6 +332,25 @@ def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) ->
     return args
 
 
+def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
+    """Encoder args that preserve what the source is.
+
+    SDR sources -> H.264 8-bit tagged BT.709 (x264_args). HDR sources (HDR10/PQ, HLG,
+    Dolby Vision base layer, BT.2020) -> HEVC Main10 with the source's own colour tags,
+    so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
+    washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
+    """
+    v = (meta or {}).get("video") or {}
+    if not v.get("hdr"):
+        return x264_args(crf, preset)
+    cs = v.get("color_space") or "bt2020nc"
+    prim = v.get("color_primaries") or "bt2020"
+    trc = v.get("color_transfer") or "arib-std-b67"
+    x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+    return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf + 2), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
+            "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
+
+
 def aac_args(bitrate: str = "192k") -> List[str]:
     return ["-c:a", "aac", "-b:a", bitrate]
 
@@ -376,14 +396,20 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
         v = vals.get(k) or [0.0]
         return sum(v) / len(v)
     ymin, ymax, yavg, sat = min(vals.get("YMIN") or [0]), max(vals.get("YMAX") or [255]), mean("YAVG"), mean("SATAVG")
+    # signalstats reports in the source bit depth; normalise everything to an 8-bit scale
+    scale = 1.0
+    if ymax > 255 or yavg > 255:
+        scale = 1 / 4.0 if ymax <= 1023 else 1 / 16.0
+    ymin, ymax, yavg, sat = ymin * scale, ymax * scale, yavg * scale, sat * scale
     # 5th/95th percentile of per-frame lows/highs is more robust than the absolute min/max
-    lows = sorted(vals.get("YLOW") or vals.get("YMIN") or [0])
-    highs = sorted(vals.get("YHIGH") or vals.get("YMAX") or [255])
+    lows = sorted(x * scale for x in (vals.get("YLOW") or vals.get("YMIN") or [0]))
+    highs = sorted(x * scale for x in (vals.get("YHIGH") or vals.get("YMAX") or [255]))
     p_low = lows[len(lows) // 20]
     p_high = highs[-1 - len(highs) // 20]
     looks_log = p_low >= 64 and p_high <= 235 and sat < 40
     return {
-        "y_min": ymin, "y_max": ymax, "y_avg": round(yavg, 1), "y_low_p5": p_low, "y_high_p95": p_high,
+        "scale": "8-bit equivalent",
+        "y_min": round(ymin, 1), "y_max": round(ymax, 1), "y_avg": round(yavg, 1), "y_low_p5": round(p_low, 1), "y_high_p95": round(p_high, 1),
         "saturation_avg": round(sat, 1),
         "looks_like_log": looks_log,
         "note": ("flat, low-contrast, desaturated picture tagged as SDR: probably a Log profile (S-Log/V-Log/C-Log). "

package/scripts/caption.py

@@ -22,7 +22,7 @@ import re
 import sys
 from typing import List, Tuple
 
-from _common import add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+from _common import video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -302,7 +302,7 @@ def main() -> int:
         if args.fonts_dir:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + x264_args(args.crf, args.preset) + cfr_args(meta)
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += (aac_args() if meta.get("audio") else ["-an"]) + [output]
     run(cmd)
     result = probe(output)

package/scripts/check.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Pre-delivery compliance check: does this file meet the platform's spec?
+
+Checks duration, frame size / aspect, fps, codec, pixel format, colour tags,
+file size, integrated loudness and true peak against the chosen platform
+and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs.
+
+Platforms: youtube, shorts, reels, tiktok, x, linkedin, broadcast (EBU R128), podcast, custom
+
+Examples:
+  python3 check.py final.mp4 --platform youtube
+  python3 check.py reel.mp4 --platform reels --json
+  python3 check.py spot.mov --platform broadcast
+  python3 check.py clip.mp4 --platform custom --max-duration 30 --aspect 1:1 --lufs -16
+"""
+import argparse
+import json
+import re
+import sys
+from fractions import Fraction
+from typing import Any, Dict, List
+
+from _common import add_common, apply_common, die, emit, info, probe, require_tool, run
+
+SPECS: Dict[str, Dict[str, Any]] = {
+    "youtube":   {"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60, "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+    "shorts":    {"max_duration": 180, "aspects": ["9:16", "1:1"], "min_height": 1080, "fps_max": 60, "codecs": ["h264", "hevc"], "max_bytes": 256 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+    "reels":     {"max_duration": 90, "aspects": ["9:16", "4:5", "1:1"], "min_height": 1080, "fps_max": 60, "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": True},
+    "tiktok":    {"max_duration": 600, "aspects": ["9:16", "1:1"], "min_height": 1080, "fps_max": 60, "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3, "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": True},
+    "x":         {"max_duration": 140, "aspects": ["16:9", "1:1", "9:16"], "min_height": 720, "fps_max": 60, "codecs": ["h264"], "max_bytes": 512 * 1024 ** 2, "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+    "linkedin":  {"max_duration": 600, "aspects": ["16:9", "1:1", "9:16", "4:5"], "min_height": 720, "fps_max": 60, "codecs": ["h264"], "max_bytes": 5 * 1024 ** 3, "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+    "broadcast": {"max_duration": None, "aspects": ["16:9"], "min_height": 1080, "fps_max": 60, "codecs": ["prores", "dnxhd", "h264", "hevc", "mpeg2video"], "max_bytes": None, "lufs": -23, "lufs_tol": 1.0, "tp": -1.0, "sdr_only": False},
+    "podcast":   {"max_duration": None, "aspects": None, "min_height": 0, "fps_max": None, "codecs": None, "max_bytes": None, "lufs": -16, "lufs_tol": 1.0, "tp": -1.0, "sdr_only": False},
+    "custom":    {"max_duration": None, "aspects": None, "min_height": 0, "fps_max": None, "codecs": None, "max_bytes": None, "lufs": None, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+}
+
+
+def measure_loudness(path: str) -> Dict[str, float]:
+    ffmpeg = require_tool("ffmpeg")
+    proc = run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], quiet=True, check=False)
+    m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
+    if not m:
+        return {}
+    d = json.loads(m.group(0))
+    try:
+        return {"lufs": float(d["input_i"]), "tp": float(d["input_tp"]), "lra": float(d["input_lra"])}
+    except (KeyError, ValueError):
+        return {}
+
+
+def aspect_name(w: int, h: int) -> str:
+    f = Fraction(w, h)
+    for name, target in (("16:9", Fraction(16, 9)), ("9:16", Fraction(9, 16)), ("1:1", Fraction(1)), ("4:5", Fraction(4, 5)), ("4:3", Fraction(4, 3)), ("21:9", Fraction(21, 9))):
+        if abs(float(f) - float(target)) < 0.02:
+            return name
+    return f"{f.numerator}:{f.denominator}"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("--platform", choices=sorted(SPECS), default="youtube")
+    ap.add_argument("--max-duration", type=float, help="override max duration in seconds")
+    ap.add_argument("--aspect", help="override allowed aspect (e.g. 9:16 or 16:9,1:1)")
+    ap.add_argument("--lufs", type=float, help="override loudness target")
+    ap.add_argument("--tp", type=float, help="override true-peak ceiling")
+    ap.add_argument("--max-mb", type=float, help="override max file size in MB")
+    ap.add_argument("--no-loudness", action="store_true", help="skip the loudness measurement (faster)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    spec = dict(SPECS[args.platform])
+    if args.max_duration is not None:
+        spec["max_duration"] = args.max_duration
+    if args.aspect:
+        spec["aspects"] = [a.strip() for a in args.aspect.split(",")]
+    if args.lufs is not None:
+        spec["lufs"] = args.lufs
+    if args.tp is not None:
+        spec["tp"] = args.tp
+    if args.max_mb is not None:
+        spec["max_bytes"] = int(args.max_mb * 1024 * 1024)
+
+    meta = probe(args.input)
+    v, a = meta.get("video") or {}, meta.get("audio") or {}
+    rows: List[Dict[str, Any]] = []
+
+    def row(name: str, status: str, value: Any, expect: Any, fix: str = "") -> None:
+        rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix})
+
+    dur = meta.get("duration") or 0.0
+    if spec["max_duration"]:
+        row("duration", "PASS" if dur <= spec["max_duration"] else "FAIL", f"{dur:.2f}s", f"<= {spec['max_duration']:g}s", "fit.py --duration N or cut.py")
+    else:
+        row("duration", "PASS", f"{dur:.2f}s", "any")
+
+    if v:
+        w, h = v["width"], v["height"]
+        if v.get("rotation") in (90, -90, 270, -270):
+            w, h = h, w
+        asp = aspect_name(w, h)
+        if spec["aspects"]:
+            row("aspect", "PASS" if asp in spec["aspects"] else "FAIL", asp, "/".join(spec["aspects"]), f"fit.py --aspect {spec['aspects'][0]} --fit pad|crop")
+        else:
+            row("aspect", "PASS", asp, "any")
+        short = min(w, h)
+        if spec["min_height"]:
+            row("resolution", "PASS" if short >= spec["min_height"] else "WARN", f"{w}x{h}", f"short side >= {spec['min_height']}", "upscaling will not add detail; re-export from the master")
+        fps = v.get("fps") or 0
+        if spec["fps_max"]:
+            row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30")
+        row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")
+        if spec["codecs"]:
+            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"))
+        pf = v.get("pix_fmt") or ""
+        if args.platform in ("reels", "tiktok", "x", "linkedin"):
+            row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p")
+        if spec["sdr_only"] and v.get("hdr"):
+            row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr")
+        else:
+            tags = (v.get("color_primaries"), v.get("color_transfer"))
+            ok = v.get("hdr") or tags == ("bt709", "bt709") or (args.platform in ("podcast", "custom"))
+            row("colour", "PASS" if ok else "WARN", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("hdr") else ""), "bt709/bt709 tagged (or HDR)", "color.py --retag bt709 when the picture really is 709")
+    elif args.platform not in ("podcast", "custom"):
+        row("video", "FAIL", "none", "video stream", "")
+
+    size = meta.get("size_bytes") or 0
+    if spec["max_bytes"]:
+        row("file size", "PASS" if size <= spec["max_bytes"] else "FAIL", f"{size / 1024 / 1024:.1f} MB", f"<= {spec['max_bytes'] / 1024 / 1024:.0f} MB", "export.py --crf 24 or lower resolution")
+
+    if a:
+        row("audio", "PASS", f"{a.get('codec')} {a.get('channels')}ch {a.get('sample_rate')}Hz", "present")
+        if a.get("sample_rate") and a["sample_rate"] not in (44100, 48000):
+            row("sample rate", "WARN", a["sample_rate"], "44100 or 48000", "loudness.py --sample-rate 48000")
+        if not args.no_loudness and spec["lufs"] is not None:
+            lm = measure_loudness(args.input)
+            if lm:
+                diff = abs(lm["lufs"] - spec["lufs"])
+                row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g}")
+                row("true peak", "PASS" if lm["tp"] <= spec["tp"] + 0.05 else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP", f"loudness.py --tp {spec['tp']:g}")
+    elif args.platform in ("podcast",):
+        row("audio", "FAIL", "none", "audio stream", "audio.py --replace")
+    else:
+        row("audio", "WARN", "none", "audio stream", "audio.py --replace (silent uploads are often rejected)")
+
+    failed = [r for r in rows if r["status"] == "FAIL"]
+    warned = [r for r in rows if r["status"] == "WARN"]
+    if not args.json:
+        width = max(len(r["check"]) for r in rows)
+        print(f"{args.input} — {args.platform}")
+        for r in rows:
+            line = f"  {r['status']:4s} {r['check']:{width}s}  {r['value']}  (expected {r['expected']})"
+            if r["status"] != "PASS" and r["fix"]:
+                line += f"  -> {r['fix']}"
+            print(line)
+        print(f"  {len(rows)} checks, {len(failed)} failed, {len(warned)} warnings")
+    emit(None, platform=args.platform, checks=rows, failed=len(failed), warnings=len(warned), ok=not failed)
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/color.py

@@ -99,7 +99,7 @@ def main() -> int:
         if proc.returncode != 0:
             # some codecs cannot carry retagged colour info without a bitstream filter; fall back to re-encode
             info("stream copy could not rewrite tags, re-encoding")
-            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a:0?"] + x264_args(args.crf, args.preset, keep_bt709=False)
             cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
             run(cmd)
         info(f"wrote {output} (tags -> {args.retag})")
@@ -124,7 +124,7 @@ def main() -> int:
         output = args.output or default_output(args.input, "lut")
         tag = "lut"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a?"]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a:0?"]
     cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else []) + [output]
     run(cmd)
     r = probe(output)

package/scripts/cut.py

@@ -16,7 +16,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 
 def parse_segments(spec: str) -> List[Tuple[float, float]]:
@@ -43,7 +43,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     meta = meta or probe(src)
     if reencode:
         cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"]
-        cmd += x264_args(crf, preset) + cfr_args(meta) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
+        cmd += video_args(meta, crf, preset) + cfr_args(meta) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
     else:
         cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}", "-c", "copy", "-avoid_negative_ts", "make_zero", dst]
     proc = run(cmd, check=False)
@@ -126,7 +126,7 @@ def main() -> int:
             proc = run(cmd, check=False)
             if proc.returncode != 0:
                 info("concat with stream copy failed, re-encoding the join")
-                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + x264_args(args.crf, args.preset) + cfr_args(meta) + aac_args() + [output]
+                cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + video_args(meta, args.crf, args.preset) + cfr_args(meta) + aac_args() + [output]
                 run(cmd)
 
     result = probe(output)

package/scripts/export.py

@@ -22,7 +22,7 @@ import argparse
 import sys
 from typing import Dict, List
 
-from _common import add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
+from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
 
 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"},
@@ -94,6 +94,8 @@ def main() -> int:
     video = list(p["video"])
     if args.crf is not None and "-crf" in video:
         video[video.index("-crf") + 1] = str(args.crf)
+    if STATE["fast"] and "-preset" in video:
+        video[video.index("-preset") + 1] = "veryfast"
     cmd += video
     if "-r" not in video:
         cmd += cfr_args(meta)

package/scripts/fit.py

@@ -19,7 +19,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
@@ -102,6 +102,8 @@ def main() -> int:
         if target <= 0:
             die("target duration must be > 0")
         if args.method == "speed":
+            if src_dur <= 0 and STATE["dry_run"]:
+                src_dur = target  # planning against an intermediate that does not exist yet
             factor = src_dur / target  # >1 = speed up
             if factor > args.max_speed or factor < 1 / args.max_speed:
                 die(f"required speed factor {factor:.2f}x exceeds --max-speed {args.max_speed}x; use --method trim or raise the limit")
@@ -153,7 +155,7 @@ def main() -> int:
         cmd += ["-vf", ",".join(vf)]
     if af:
         cmd += ["-af", ",".join(af)]
-    cmd += x264_args(args.crf, args.preset)
+    cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps) if not args.fps else []
     if has_audio:
         cmd += aac_args()

package/scripts/join.py

@@ -14,7 +14,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
+from _common import STATE, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, x264_args
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -44,17 +44,24 @@ def main() -> int:
         if not m.get("video"):
             die(f"{p} has no video stream")
     first = metas[0]["video"]
-    w = args.width or first["width"]
-    h = args.height or first["height"]
-    if first.get("rotation") in (90, -90, 270, -270) and not (args.width or args.height):
-        w, h = h, w
+    fw, fh = first["width"], first["height"]
+    if first.get("rotation") in (90, -90, 270, -270):
+        fw, fh = fh, fw
+    if args.width and args.height:
+        w, h = args.width, args.height
+    elif args.width:
+        w, h = args.width, int(round(args.width * fh / fw))
+    elif args.height:
+        w, h = int(round(args.height * fw / fh)), args.height
+    else:
+        w, h = fw, fh
     fps = args.fps or first.get("fps") or 30.0
     fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
     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):
-        if d and dur <= d * 2:
+        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")
 
     cmd = ffmpeg_base()
@@ -78,8 +85,9 @@ def main() -> int:
         geo = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
     else:
         geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
+    pixfmt = "yuv420p10le" if (metas[0].get("video") or {}).get("hdr") else "yuv420p"
     for i in range(n):
-        parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format=yuv420p,settb=AVTB[v{i}]")
+        parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
         parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts=stereo,asetpts=PTS-STARTPTS[a{i}]")
 
     if args.transition == "none":
@@ -98,7 +106,7 @@ def main() -> int:
 
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    cmd += x264_args(args.crf, args.preset) + aac_args() + [output]
+    cmd += video_args(metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
     expected = sum(durs) - d * (n - 1)
     r = probe(output)

package/scripts/look.py

@@ -44,6 +44,13 @@ def main() -> int:
     stem = Path(args.input).stem
     outdir = str(Path(args.output).parent) if args.output else str(Path(args.input).parent)
     tc = "" if args.no_timecode else "," + timecode_filter()
+    # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
+    if meta["video"].get("hdr"):
+        v = meta["video"]
+        tm = (f"zscale=tin={v.get('color_transfer') or 'arib-std-b67'}:pin={v.get('color_primaries') or 'bt2020'}:min={v.get('color_space') or 'bt2020nc'}:rin=tv:t=linear:npl=1000,"
+              "format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable,zscale=t=bt709:m=bt709:r=tv,format=yuv420p,")
+        tc = "," + tm.rstrip(",") + tc
+        info("HDR source: frames are tone-mapped to SDR for display")
     outputs: List[str] = []
 
     if args.compare: