ffmpeg-skill 0.4.1 → 0.6.0

package/scripts/graphics.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Motion-graphics templates rendered with drawbox/drawtext expressions —
+no After Effects, no image assets, brand colours from brand.json.
+
+Templates:
+  lower-third   name + title bar sliding in from the left (--name, --title)
+  title         centred title card with optional subtitle, fade in/out (--title, --subtitle)
+  chapter       small chip in a corner (--title), e.g. "Part 2 — Setup"
+  progress      thin progress bar along the bottom that fills over the clip (or --start/--end)
+  countdown     big numbers counting down from --from to 0 (--start/--end define the window)
+  bug           persistent text bug (--title) in a corner, e.g. "@handle" or "LIVE"
+
+Examples:
+  python3 graphics.py talk.mp4 --template lower-third --name "Ada Lovelace" --title "Analyst" --start 2 --end 8
+  python3 graphics.py talk.mp4 --template title --title "Episode 12" --subtitle "The math of video" --start 0 --end 4
+  python3 graphics.py talk.mp4 --template progress --brand brand.json
+  python3 graphics.py intro.mp4 --template countdown --from 5 --start 1 --end 6
+  python3 graphics.py clip.mp4 --template chapter --title "Part 2 — Setup" --position top-left --start 0 --end 5
+"""
+import argparse
+import sys
+from typing import List, Optional
+
+from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, video_args
+
+TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
+
+
+def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
+    return f"0x{color_hex(hex_rgb)}@{alpha:g}"
+
+
+def font_opts(brand: dict, font: Optional[str], font_file: Optional[str]) -> str:
+    if font_file or brand.get("font_file"):
+        return f"fontfile={escape_filter_path(font_file or brand['font_file'])}"
+    return f"font='{font or brand.get('font', 'DejaVu Sans')}'"
+
+
+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>_gfx.<ext>)")
+    ap.add_argument("--template", choices=TEMPLATES, required=True)
+    ap.add_argument("--brand", help="brand.json for colours, font, safe margin")
+    ap.add_argument("--name", help="lower-third: name line")
+    ap.add_argument("--title", help="title / chapter / bug text, or lower-third second line")
+    ap.add_argument("--subtitle", help="title: smaller second line")
+    ap.add_argument("--from", dest="count_from", type=int, default=5, help="countdown start number (default 5)")
+    ap.add_argument("--start", help="show from (default 0)")
+    ap.add_argument("--end", help="hide after (default end of clip)")
+    ap.add_argument("--position", choices=["top-left", "top-right", "bottom-left", "bottom-right"], default=None, help="corner for chapter/bug (default bottom-left / top-right)")
+    ap.add_argument("--primary", help="override brand primary colour RRGGBB")
+    ap.add_argument("--text-color", help="override text colour RRGGBB")
+    ap.add_argument("--font")
+    ap.add_argument("--font-file")
+    ap.add_argument("--scale", type=float, default=1.0, help="size multiplier (default 1)")
+    ap.add_argument("--crf", type=int, default=18)
+    ap.add_argument("--preset", default="medium")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    brand = load_brand(args.brand)
+    primary = color_hex(args.primary or brand["colors"]["primary"])
+    text_c = color_hex(args.text_color or brand["colors"]["text"])
+    bg = color_hex(brand["colors"].get("background", "101418"))
+    margin = int(brand.get("safe_margin", 48))
+    fo = font_opts(brand, args.font, args.font_file)
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    W, H = meta["video"]["width"], meta["video"]["height"]
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        W, H = H, W
+    dur = meta.get("duration") or 0.0
+    s = parse_time(args.start) if args.start else 0.0
+    e = parse_time(args.end) if args.end else dur
+    if e <= s:
+        die("--end must be after --start")
+    en = f"enable='between(t,{s:.3f},{e:.3f})'"
+    base = min(W, H) * args.scale  # scale everything from the short side
+    filters: List[str] = []
+    fade_a = f"if(lt(t,{s:.3f}+0.3),(t-{s:.3f})/0.3,if(gt(t,{e:.3f}-0.3),({e:.3f}-t)/0.3,1))"
+
+    extra_inputs: List[str] = []
+    fc: List[str] = []  # filter_complex chains (used by templates that need animated boxes)
+    if args.template == "lower-third":
+        if not args.name:
+            die("lower-third needs --name")
+        h1 = int(base * 0.055)
+        h2 = int(base * 0.038)
+        pad = int(base * 0.02)
+        bar_h = h1 + (h2 + pad if args.title else 0) + pad * 2
+        bar_w = int(base * 0.62)
+        y0 = H - margin - bar_h
+        # slide in from the left over 0.4 s, slide out over 0.3 s (overlay evaluates x per frame)
+        x_expr = f"if(lt(t,{s:.3f}+0.4),-{bar_w}+({bar_w}+{margin})*((t-{s:.3f})/0.4),if(gt(t,{e:.3f}-0.3),{margin}-({bar_w}+{margin})*(1-({e:.3f}-t)/0.3),{margin}))"
+        fc.append(f"color=c=0x{bg}@0.85:s={bar_w}x{bar_h}:r={meta['video'].get('fps') or 30:g},format=rgba[bar]")
+        fc.append(f"color=c=0x{primary}:s={int(base * 0.012)}x{bar_h}:r={meta['video'].get('fps') or 30:g},format=rgba[acc]")
+        fc.append(f"[0:v][bar]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v1]")
+        fc.append(f"[v1][acc]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v2]")
+        tx = f"({x_expr})+{int(base * 0.035)}"
+        chain = f"drawtext=text='{escape_drawtext(args.name)}':{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:x='{tx}':y={y0 + pad}:{en}"
+        if args.title:
+            chain += f",drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={h2}:fontcolor={ff_color(primary)}:x='{tx}':y={y0 + pad + h1 + pad // 2}:{en}"
+        fc.append(f"[v2]{chain}[vout]")
+
+    elif args.template == "title":
+        if not args.title:
+            die("title needs --title")
+        h1 = int(base * 0.11)
+        h2 = int(base * 0.045)
+        filters.append(f"drawbox=x=0:y=0:w=iw:h=ih:color={ff_color(bg, 0.55)}:t=fill:{en}")
+        filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}")
+        filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{h1 // 2 + (0 if args.subtitle else 0)}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
+        if args.subtitle:
+            filters.append(f"drawtext=text='{escape_drawtext(args.subtitle)}':{fo}:fontsize={h2}:fontcolor={ff_color(primary)}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}")
+
+    elif args.template in ("chapter", "bug"):
+        if not args.title:
+            die(f"{args.template} needs --title")
+        pos = args.position or ("bottom-left" if args.template == "chapter" else "top-right")
+        fs = int(base * (0.04 if args.template == "chapter" else 0.032))
+        padx, pady = int(fs * 0.6), int(fs * 0.35)
+        xe = f"{margin}" if "left" in pos else f"w-text_w-{margin}"
+        ye = f"{margin}" if "top" in pos else f"h-text_h-{margin}"
+        box_color = ff_color(primary if args.template == "chapter" else bg, 0.9 if args.template == "chapter" else 0.7)
+        txt_color = ff_color(bg if args.template == "chapter" else text_c)
+        filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={pady}|{padx}:alpha='{fade_a}':{en}")
+
+    elif args.template == "progress":
+        h = max(3, int(base * 0.008))
+        fps = meta['video'].get('fps') or 30
+        fc.append(f"color=c=0x{primary}:s={W}x{h}:r={fps:g},format=rgba[pb]")
+        fc.append(f"[0:v]drawbox=x=0:y=ih-{h}:w=iw:h={h}:color={ff_color(bg, 0.5)}:t=fill:{en}[v1]")
+        fc.append(f"[v1][pb]overlay=x='-w+w*min(1,max(0,(t-{s:.3f})/{e - s:.3f}))':y={H - h}:{en}:eof_action=pass[vout]")
+
+    elif args.template == "countdown":
+        n = args.count_from
+        seg = (e - s) / (n + 1)
+        fs = int(base * 0.32)
+        for k in range(n, -1, -1):
+            ks = s + (n - k) * seg
+            ke = ks + seg
+            pulse = f"1-0.15*min(1,(t-{ks:.3f})/{seg * 0.5:.3f})"
+            filters.append(f"drawtext=text='{k}':{fo}:fontsize={fs}:fontcolor={ff_color(primary)}:borderw={max(2, fs // 40)}:bordercolor={ff_color(bg)}:x=(w-text_w)/2:y=(h-text_h)/2:alpha='{pulse}':enable='between(t,{ks:.3f},{ke:.3f})'")
+
+    output = args.output or default_output(args.input, "gfx")
+    cmd = ffmpeg_base() + ["-i", args.input]
+    if fc:
+        cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", "0:a:0?"]
+    else:
+        cmd += ["-vf", ",".join(filters), "-map", "0:v:0", "-map", "0:a:0?"]
+    cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
+    cmd += aac_args() if meta.get("audio") else ["-an"]
+    cmd.append(output)
+    run(cmd)
+    r = probe(output)
+    info(f"wrote {output} ({r['duration']:.3f}s, {args.template})")
+    emit(output, template=args.template)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/join.py

@@ -14,7 +14,7 @@ import argparse
 import sys
 from typing import List
 
-from _common import video_args, 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()

package/scripts/loudness.py

@@ -18,11 +18,13 @@ import os
 import re
 import sys
 
-from _common import add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
 
 
 
 def measure(path: str, I: float, tp: float, lra: float) -> dict:
+    if STATE["dry_run"]:
+        return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0"}
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
     proc = run(cmd, check=False)

package/scripts/overlay.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -76,9 +76,11 @@ 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>_overlay.<ext>)")
-    src = ap.add_mutually_exclusive_group(required=True)
+    src = ap.add_mutually_exclusive_group()
     src.add_argument("--image", help="PNG/JPG (alpha respected) to composite")
     src.add_argument("--text", help="text to draw (drawtext)")
+    src.add_argument("--logo", action="store_true", help="composite the brand logo from --brand (position/scale/opacity from brand.json)")
+    ap.add_argument("--brand", help="brand.json (logo, font, colours, safe margin)")
     ap.add_argument("--position", default="top-right", help="named position or X,Y (default top-right)")
     ap.add_argument("--margin", type=int, default=24, help="margin from the edges in px (default 24)")
     ap.add_argument("--start", help="show from this time (default: whole video)")
@@ -104,6 +106,26 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    brand = load_brand(args.brand)
+    if args.logo:
+        if not brand.get("logo"):
+            die("--logo needs a brand.json with a 'logo' entry")
+        args.image = brand["logo"]
+        if args.position == ap.get_default("position"):
+            args.position = brand.get("logo_position", "top-right")
+        if not args.scale and not args.scale_percent:
+            args.scale = int(brand.get("logo_scale", 160))
+        if args.opacity == 1.0:
+            args.opacity = float(brand.get("logo_opacity", 1.0))
+    if not (args.image or args.text):
+        die("give --image, --text or --logo")
+    if args.brand:
+        if args.margin == ap.get_default("margin"):
+            args.margin = int(brand.get("safe_margin", args.margin))
+        if args.font == ap.get_default("font"):
+            args.font = brand.get("font", args.font)
+        if not args.font_file and brand.get("font_file"):
+            args.font_file = brand["font_file"]
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")

package/scripts/render.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""Declarative edits: describe the whole edit in one project.json and render it
+in one command. Change a number, re-render. Non-destructive: sources are never
+touched, intermediates live in a work directory.
+
+Project format (all keys optional except clips):
+{
+  "output": "final.mp4",
+  "frame": {"aspect": "9:16", "width": 1080, "fps": 30},
+  "clips": [
+    {"src": "a.mp4", "in": "0:05", "out": "0:20"},
+    {"src": "b.mp4", "in": 3, "out": 12, "speed": 1.25},
+    {"src": "c.mp4"}
+  ],
+  "transition": {"type": "fade", "duration": 0.5},
+  "silence": {"threshold": -38, "min_silence": 0.8},
+  "captions": {"text": "cues.txt", "srt": null, "animate": "pop", "karaoke": true, "font": "Noto Sans CJK JP", "size": 28, "position": "bottom"},
+  "brand": "brand.json",
+  "graphics": [
+    {"template": "title", "title": "Episode 12", "subtitle": "The math of video", "start": 0, "end": 4},
+    {"template": "lower-third", "name": "Ada Lovelace", "title": "Analyst", "start": 5, "end": 11}
+  ],
+  "overlays": [
+    {"logo": true},
+    {"text": "Episode 12", "position": "bottom", "start": 1, "end": 5, "fade": 0.3, "box": true}
+  ],
+  "audio": {"voice": true, "music": "bed.mp3", "music_volume": -16, "duck": true, "fade_out": 2},
+  "loudness": {"lufs": -14, "tp": -1},
+  "fit": {"duration": 60},
+  "export": {"preset": "reels"},
+  "check": {"platform": "reels"}
+}
+
+Stages run in this order: clips (cut) → join → silence → fit → captions →
+graphics → overlays → audio → loudness → export → check. Missing stages are
+skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
+colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
+
+Examples:
+  python3 render.py --init project.json          # write a commented starter project
+  python3 render.py project.json                 # render
+  python3 render.py project.json --dry-run       # show every command without rendering
+  python3 render.py project.json --fast          # preview quality
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+from _common import STATE, add_common, apply_common, die, emit, info, probe
+
+HERE = Path(__file__).resolve().parent
+
+TEMPLATE = {
+    "output": "final.mp4",
+    "frame": {"aspect": "16:9", "width": 1920, "fps": 30},
+    "clips": [{"src": "REPLACE_ME.mp4", "in": "0:00", "out": "0:30"}],
+    "transition": {"type": "fade", "duration": 0.5},
+    "silence": None,
+    "brand": None,
+    "captions": None,
+    "graphics": [],
+    "overlays": [],
+    "audio": None,
+    "loudness": {"lufs": -14, "tp": -1},
+    "fit": None,
+    "export": {"preset": "youtube"},
+    "check": {"platform": "youtube"},
+}
+
+
+def sh(script: str, *argv: Any, extra: List[str] = None) -> str:
+    """Run a sibling script, forwarding --fast / --dry-run, returning its printed output path."""
+    cmd = [sys.executable, str(HERE / script)] + [str(a) for a in argv] + (extra or [])
+    if STATE["fast"]:
+        cmd.append("--fast")
+    if STATE["dry_run"]:
+        cmd.append("--dry-run")
+    info("→ " + " ".join(os.path.basename(c) if i < 2 else c for i, c in enumerate(cmd)))
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    for line in proc.stderr.splitlines():
+        if line.startswith("$ ") or line.startswith("[dry-run]"):
+            STATE["commands"].append(line[2:] if line.startswith("$ ") else line)
+        elif line.strip():
+            info("    " + line)
+    if proc.returncode != 0:
+        die(f"{script} failed")
+    out = proc.stdout.strip().splitlines()
+    return out[-1] if out else ""
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("project", nargs="?", help="project.json")
+    ap.add_argument("--init", metavar="FILE", help="write a starter project file and exit")
+    ap.add_argument("--work", help="work directory for intermediates (default: <output>_work)")
+    ap.add_argument("--keep", action="store_true", help="keep intermediates (default: kept only when --work is given)")
+    ap.add_argument("--stop-after", choices=["clips", "join", "silence", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export"], help="stop after this stage (for iterating)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.init:
+        Path(args.init).write_text(json.dumps(TEMPLATE, indent=2) + "\n", encoding="utf-8")
+        info(f"wrote {args.init}; edit clips/src and run: render.py {args.init}")
+        print(args.init)
+        return 0
+    if not args.project:
+        die("give a project.json (or --init FILE)")
+    try:
+        proj: Dict[str, Any] = json.loads(Path(args.project).read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        die(f"cannot read project: {exc}")
+    base = Path(args.project).resolve().parent
+
+    def rel(p: Any) -> str:
+        p = str(p)
+        return p if os.path.isabs(p) else str(base / p)
+
+    clips = proj.get("clips") or []
+    if not clips:
+        die("project.clips is empty")
+    output = rel(proj.get("output") or "final.mp4")
+    work = Path(args.work) if args.work else Path(str(Path(output).with_suffix("")) + "_work")
+    work.mkdir(parents=True, exist_ok=True)
+    frame = proj.get("frame") or {}
+    trans = proj.get("transition") or {}
+    brand_args: List[str] = ["--brand", rel(proj["brand"])] if proj.get("brand") else []
+    stages_done: List[str] = []
+
+    # ---- clips
+    parts: List[str] = []
+    for i, c in enumerate(clips):
+        src = rel(c["src"])
+        if not STATE["dry_run"]:
+            probe(src)
+        needs_cut = c.get("in") is not None or c.get("out") is not None
+        part = str(work / f"clip{i:02d}.mp4")
+        if needs_cut:
+            argv: List[Any] = [src, "-o", part, "--accurate"]
+            if c.get("in") is not None:
+                argv += ["--start", c["in"]]
+            if c.get("out") is not None:
+                argv += ["--end", c["out"]]
+            sh("cut.py", *argv)
+        else:
+            part = src
+        if c.get("speed"):
+            spd = float(c["speed"])
+            dur = (probe(part).get("duration") or 0.0) if not STATE["dry_run"] else 10.0
+            fitted = str(work / f"clip{i:02d}_speed.mp4")
+            sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)
+            part = fitted
+        parts.append(part)
+    stages_done.append("clips")
+    current = parts[0]
+    if args.stop_after == "clips":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- join
+    if len(parts) > 1:
+        current = str(work / "joined.mp4")
+        argv = list(parts) + ["-o", current, "--transition", trans.get("type", "fade"), "--duration", str(trans.get("duration", 0.5))]
+        if frame.get("width"):
+            argv += ["--width", str(frame["width"])]
+        if frame.get("height"):
+            argv += ["--height", str(frame["height"])]
+        if frame.get("fps"):
+            argv += ["--fps", str(frame["fps"])]
+        sh("join.py", *argv)
+        stages_done.append("join")
+    if args.stop_after == "join":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- silence
+    sil = proj.get("silence")
+    if sil:
+        nxt = str(work / "tight.mp4")
+        argv = [current, "-o", nxt]
+        for k, flag in (("threshold", "--threshold"), ("min_silence", "--min-silence"), ("margin", "--margin")):
+            if sil.get(k) is not None:
+                argv += [flag, str(sil[k])]
+        sh("silence.py", *argv)
+        current = nxt
+        stages_done.append("silence")
+    if args.stop_after == "silence":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- fit (duration and/or frame)
+    fit = dict(proj.get("fit") or {})
+    if frame.get("aspect"):
+        fit.setdefault("aspect", frame["aspect"])
+    if frame.get("width") and len(parts) == 1:
+        fit.setdefault("width", frame["width"])
+    if frame.get("fps") and len(parts) == 1:
+        fit.setdefault("fps", frame["fps"])
+    if fit:
+        nxt = str(work / "fit.mp4")
+        argv = [current, "-o", nxt]
+        for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("fps", "--fps"), ("smooth", "--smooth")):
+            if fit.get(k) is not None:
+                argv += [flag, str(fit[k])]
+        sh("fit.py", *argv)
+        current = nxt
+        stages_done.append("fit")
+    if args.stop_after == "fit":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- captions
+    cap = proj.get("captions")
+    if cap:
+        nxt = str(work / "captioned.mp4")
+        argv = [current, "-o", nxt]
+        if cap.get("text"):
+            argv += ["--text", rel(cap["text"])]
+        elif cap.get("srt"):
+            argv += ["--srt", rel(cap["srt"])]
+        elif cap.get("ass"):
+            argv += ["--ass", rel(cap["ass"])]
+        else:
+            die("captions needs text, srt or ass")
+        for k, flag in (("font", "--font"), ("size", "--size"), ("color", "--color"), ("position", "--position"), ("margin", "--margin"), ("animate", "--animate"), ("highlight_color", "--highlight-color"), ("outline", "--outline")):
+            if cap.get(k) is not None:
+                argv += [flag, str(cap[k])]
+        for k, flag in (("karaoke", "--karaoke"), ("bold", "--bold"), ("box", "--box")):
+            if cap.get(k):
+                argv.append(flag)
+        sh("caption.py", *(argv + brand_args))
+        current = nxt
+        stages_done.append("captions")
+    if args.stop_after == "captions":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- graphics
+    for i, g in enumerate(proj.get("graphics") or []):
+        nxt = str(work / f"graphics{i:02d}.mp4")
+        if not g.get("template"):
+            die(f"graphics[{i}] needs a template")
+        argv = [current, "-o", nxt, "--template", g["template"]]
+        for k, flag in (("name", "--name"), ("title", "--title"), ("subtitle", "--subtitle"), ("start", "--start"), ("end", "--end"), ("position", "--position"), ("from", "--from"), ("scale", "--scale"), ("primary", "--primary"), ("text_color", "--text-color")):
+            if g.get(k) is not None:
+                argv += [flag, str(g[k])]
+        sh("graphics.py", *(argv + brand_args))
+        current = nxt
+        if "graphics" not in stages_done:
+            stages_done.append("graphics")
+    if args.stop_after == "graphics":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- overlays
+    for i, ov in enumerate(proj.get("overlays") or []):
+        nxt = str(work / f"overlay{i:02d}.mp4")
+        argv = [current, "-o", nxt]
+        if ov.get("logo"):
+            argv.append("--logo")
+        elif ov.get("image"):
+            argv += ["--image", rel(ov["image"])]
+        elif ov.get("text"):
+            argv += ["--text", ov["text"]]
+        else:
+            die(f"overlays[{i}] needs image or text")
+        for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin")):
+            if ov.get(k) is not None:
+                argv += [flag, str(ov[k])]
+        if ov.get("box"):
+            argv.append("--box")
+        sh("overlay.py", *(argv + brand_args))
+        current = nxt
+        if "overlays" not in stages_done:
+            stages_done.append("overlays")
+    if args.stop_after == "overlays":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- audio
+    au = proj.get("audio")
+    if au:
+        nxt = str(work / "audio.mp4")
+        argv = [current, "-o", nxt]
+        for k, flag in (("music", "--music"), ("replace", "--replace")):
+            if au.get(k):
+                argv += [flag, rel(au[k])]
+        for k, flag in (("music_volume", "--music-volume"), ("fade_in", "--fade-in"), ("fade_out", "--fade-out"), ("gain", "--gain"), ("duck_amount", "--duck-amount")):
+            if au.get(k) is not None:
+                argv += [flag, str(au[k])]
+        for k, flag in (("voice", "--voice"), ("denoise", "--denoise"), ("duck", "--duck"), ("music_loop", "--music-loop"), ("stereo", "--stereo"), ("mono", "--mono"), ("downmix", "--downmix")):
+            if au.get(k):
+                argv.append(flag)
+        sh("audio.py", *argv)
+        current = nxt
+        stages_done.append("audio")
+    if args.stop_after == "audio":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- loudness
+    ld = proj.get("loudness")
+    if ld:
+        nxt = str(work / "loudnorm.mp4")
+        argv = [current, "-o", nxt]
+        if ld.get("lufs") is not None:
+            argv += ["-I", str(ld["lufs"])]
+        if ld.get("tp") is not None:
+            argv += ["--tp", str(ld["tp"])]
+        sh("loudness.py", *argv)
+        current = nxt
+        stages_done.append("loudness")
+    if args.stop_after == "loudness":
+        emit(current, stages=stages_done)
+        return 0
+
+    # ---- export
+    ex = proj.get("export")
+    if ex and ex.get("preset"):
+        argv = [current, "--preset", ex["preset"], "-o", output]
+        if ex.get("fit"):
+            argv += ["--fit", ex["fit"]]
+        if ex.get("crf") is not None:
+            argv += ["--crf", str(ex["crf"])]
+        sh("export.py", *argv)
+        stages_done.append("export")
+    else:
+        if not STATE["dry_run"]:
+            import shutil
+            shutil.copyfile(current, output)
+        info(f"copied final stage to {output}")
+    current = output
+
+    # ---- check
+    ck = proj.get("check")
+    check_result = None
+    if ck and ck.get("platform") and not STATE["dry_run"]:
+        proc = subprocess.run([sys.executable, str(HERE / "check.py"), output, "--platform", ck["platform"], "--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        try:
+            check_result = json.loads(proc.stdout)
+        except ValueError:
+            check_result = {"error": proc.stderr.strip()[-300:]}
+        if check_result.get("failed"):
+            info(f"check: {check_result['failed']} FAIL — " + "; ".join(f"{r['check']}={r['value']} ({r['fix']})" for r in check_result["checks"] if r["status"] == "FAIL"))
+        else:
+            info(f"check: OK for {ck['platform']}")
+        stages_done.append("check")
+
+    if not args.keep and not args.work and not STATE["dry_run"]:
+        import shutil
+        shutil.rmtree(work, ignore_errors=True)
+    info(f"rendered {output} via {' → '.join(stages_done)}")
+    emit(output, stages=stages_done, check=check_result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())