ffmpeg-skill 0.4.1 → 0.6.0

package/README.md

@@ -17,6 +17,12 @@ 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.
+- **Brand kit** — one `brand.json` (fonts, colours, logo, safe margins, caption style) applied by captions, overlays, graphics and projects.
+- **Motion graphics without assets** — lower-thirds, title cards, chapter chips, progress bars, countdowns and corner bugs drawn by FFmpeg.
+- **HTML delivery report** — before/after contact sheets, media facts, loudness, compliance and the commands run, in one file.
+- **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 +98,11 @@ 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` |
+| `graphics.py` | Lower-third, title, chapter, progress, countdown, bug templates (brand colours) |
+| `report.py` | Single-file HTML delivery report with sheets, facts, loudness, compliance, commands |
+| `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 +130,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, brand kits, motion-graphics templates (lower-thirds, titles, countdowns), HTML delivery reports, 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,12 @@ 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` |
+| "add a lower third with my name", "title card", "countdown intro", "progress bar" | `graphics.py input.mp4 --template lower-third --name "..." --title "..." --start 2 --end 8` |
+| "use our brand fonts/colours/logo" | pass `--brand brand.json` to caption/overlay/graphics, or `"brand"` in project.json |
+| "send me a summary of what you did" | `report.py --before raw.mov --after final.mp4 --platform youtube -o report.html` |
 | "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 +146,65 @@ 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 → graphics → 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.
+
+### graphics.py — motion-graphics templates
+```
+graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug [--name] [--title] [--subtitle]
+            [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [-o OUT]
+```
+Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
+the frame's short side; colours, font and safe margin come from `--brand`.
+Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.
+
+### brand.json — one file for fonts, colours, logo, margins
+```json
+{"font": "Noto Sans CJK JP", "font_file": "fonts/NotoSansCJK-Bold.ttc",
+ "colors": {"primary": "FF6A00", "text": "FFFFFF", "outline": "000000", "background": "0B1D2A"},
+ "logo": "logo.png", "logo_position": "top-right", "logo_scale": 160, "logo_opacity": 0.9,
+ "safe_margin": 48, "caption": {"size": 28, "position": "bottom", "animate": "pop", "karaoke": true, "bold": true}}
+```
+`caption.py --brand`, `overlay.py --brand --logo`, `graphics.py --brand`, and
+`"brand": "brand.json"` in a render project. Explicit flags still win. When a
+user mentions brand guidelines, colours, "our font" or a logo, ask for or
+write a brand.json once and reuse it across every output.
+
+### report.py — HTML delivery report
+```
+report.py --after FINAL [--before SOURCE] [--platform youtube] [--commands cmds.txt] [--notes notes.md] [--title T] [--no-sheets] [-o report.html]
+```
+One self-contained HTML: before/after facts and contact sheets, loudness,
+compliance table with fixes, commands. Produce it for any multi-step job and
+hand the path to the user together with the numbers.
+
 ### multicam.py — align several cameras and switch between them
 ```
 multicam.py REF CAM2 [CAM3 ...] [--switch "START-END:CAM,..."] | [--auto N] [--audio IDX] [--fix-drift]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.4.1",
-  "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.6.0",
+  "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: declarative project rendering, brand kits, motion-graphics templates, HTML delivery reports, 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}")
@@ -416,6 +417,55 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     }
 
 
+BRAND_DEFAULTS: Dict[str, Any] = {
+    "font": "DejaVu Sans",
+    "font_file": None,
+    "colors": {"primary": "FFD200", "text": "FFFFFF", "outline": "000000", "background": "101418", "accent": "1E6F8E"},
+    "logo": None,
+    "logo_position": "top-right",
+    "logo_scale": 160,
+    "logo_opacity": 0.9,
+    "safe_margin": 48,
+    "caption": {"size": 26, "position": "bottom", "animate": "pop", "karaoke": False, "bold": True, "outline": 2},
+    "loudness": {"lufs": -14, "tp": -1},
+}
+
+
+def load_brand(path: Optional[str]) -> Dict[str, Any]:
+    """Load brand.json (fonts, colours, logo, safe margins, caption defaults); missing keys fall back to defaults."""
+    import copy
+    brand = copy.deepcopy(BRAND_DEFAULTS)
+    if not path:
+        return brand
+    if not os.path.exists(path):
+        die(f"brand file not found: {path}")
+    try:
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+    except ValueError as exc:
+        die(f"brand file is not valid JSON: {exc}")
+    base = Path(path).resolve().parent
+    for k, v in data.items():
+        if isinstance(v, dict) and isinstance(brand.get(k), dict):
+            brand[k].update(v)
+        else:
+            brand[k] = v
+    for key in ("logo", "font_file"):
+        if brand.get(key) and not os.path.isabs(brand[key]):
+            brand[key] = str(base / brand[key])
+    brand["_path"] = str(path)
+    return brand
+
+
+def color_hex(value: str) -> str:
+    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
+    v = str(value).strip().lstrip("#")
+    if v.lower().startswith("0x"):
+        v = v[2:]
+    if len(v) != 6:
+        die(f"colour must be RRGGBB, got '{value}'")
+    return v.upper()
+
+
 def print_json(obj: Any) -> None:
     sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
 

package/scripts/caption.py

@@ -20,9 +20,10 @@ import argparse
 import os
 import re
 import sys
+from pathlib import Path
 from typing import List, Tuple
 
-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
+from _common import color_hex, load_brand, 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}
 
@@ -220,21 +221,22 @@ def main() -> int:
     src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
     src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
     sty = ap.add_argument_group("style (SRT only)")
-    sty.add_argument("--font", default="DejaVu Sans", help="font family, e.g. 'Noto Sans CJK JP' for Japanese")
+    sty.add_argument("--brand", help="brand.json: font, colours, caption size/position/animation defaults")
+    sty.add_argument("--font", default=None, help="font family, e.g. 'Noto Sans CJK JP' for Japanese (default DejaVu Sans or brand font)")
     sty.add_argument("--fonts-dir", help="directory with extra .ttf/.otf files")
-    sty.add_argument("--size", type=int, default=24, help="font size in ASS points (relative to a 288p script height, scales automatically)")
-    sty.add_argument("--color", default="FFFFFF", help="text colour RRGGBB (default FFFFFF)")
-    sty.add_argument("--outline-color", default="000000", help="outline colour RRGGBB")
-    sty.add_argument("--outline", type=float, default=2.0, help="outline width (default 2)")
+    sty.add_argument("--size", type=int, default=None, help="font size in ASS points (relative to a 288p script height, scales automatically)")
+    sty.add_argument("--color", default=None, help="text colour RRGGBB (default FFFFFF or brand text colour)")
+    sty.add_argument("--outline-color", default=None, help="outline colour RRGGBB")
+    sty.add_argument("--outline", type=float, default=None, help="outline width (default 2)")
     sty.add_argument("--shadow", type=float, default=0.0, help="shadow depth (default 0)")
     sty.add_argument("--bold", action="store_true")
-    sty.add_argument("--position", choices=sorted(ALIGN), default="bottom", help="on-screen placement (default bottom)")
+    sty.add_argument("--position", choices=sorted(ALIGN), default=None, help="on-screen placement (default bottom)")
     sty.add_argument("--margin", type=int, default=30, help="vertical margin from the edge (default 30)")
     sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")
     anim = ap.add_argument_group("animation (generates ASS; needs --text or --srt input)")
-    anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default="none", help="per-cue entrance animation")
+    anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default=None, help="per-cue entrance animation (default none, or brand caption.animate)")
     anim.add_argument("--karaoke", action="store_true", help="word-by-word highlight (fills from --color to --highlight-color across each cue)")
-    anim.add_argument("--highlight-color", default="FFD200", help="karaoke fill colour RRGGBB (default FFD200)")
+    anim.add_argument("--highlight-color", default=None, help="karaoke fill colour RRGGBB (default FFD200 or brand primary)")
     anim.add_argument("--karaoke-timing", choices=["even", "energy"], default="energy",
                       help="how words are timed inside a cue: 'energy' follows the speech loudness in the audio (default), 'even' splits time equally")
     anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
@@ -245,6 +247,22 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    brand = load_brand(args.brand)
+    bc, bcap = brand["colors"], brand["caption"]
+    args.font = args.font or brand.get("font") or "DejaVu Sans"
+    args.size = args.size if args.size is not None else (bcap.get("size", 24) if args.brand else 24)
+    args.color = color_hex(args.color or bc.get("text", "FFFFFF"))
+    args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))
+    args.outline = args.outline if args.outline is not None else (float(bcap.get("outline", 2)) if args.brand else 2.0)
+    args.position = args.position or (bcap.get("position", "bottom") if args.brand else "bottom")
+    args.animate = args.animate or (bcap.get("animate", "none") if args.brand else "none")
+    args.highlight_color = color_hex(args.highlight_color or bc.get("primary", "FFD200"))
+    if args.brand and bcap.get("bold") and not args.bold:
+        args.bold = True
+    if args.brand and bcap.get("karaoke") and not args.karaoke:
+        args.karaoke = True
+    if args.brand and brand.get("font_file") and not args.fonts_dir:
+        args.fonts_dir = str(Path(brand["font_file"]).parent)
     if not (args.srt or args.ass or args.text):
         die("give one of --srt, --ass or --text")
 

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

@@ -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")