ffmpeg-skill 1.13.0 → 1.15.0

package/scripts/render.py

@@ -60,9 +60,17 @@ from pathlib import Path
 from typing import Any, Dict, List
 
 from export import PRESETS, PLATFORM_OF
+from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, fingerprint, PLAN_VERSION
 
 HERE = Path(__file__).resolve().parent
+TEMPLATE_DIR = HERE.parent / "templates"
+# The placeholders a delivery template carries; a block whose placeholder has no value
+# (no --logo, no --title, no cues) is dropped from the filled project rather than rendered empty.
+PLACEHOLDERS = ("$INPUT", "$OUTPUT", "$CUES", "$SRT", "$LOGO", "$TITLE", "$BRAND", "$CHAPTERS")
+# Intermediates follow the delivery's own media kind: an audio-only project (the podcast
+# template) must not carry its stages through .mp4 containers.
+AUDIO_EXT = frozenset({".wav", ".m4a", ".mp3", ".flac", ".aac", ".ogg", ".opus"})
 
 TEMPLATE = {
     "output": "final.mp4",
@@ -88,18 +96,23 @@ TEMPLATE = {
 # untrimmed, and a mistyped stage name dropped the stage -- both reported as a success (review 9).
 OBJECT_KEYS: Dict[str, frozenset] = {
     "project": frozenset({"output", "frame", "clips", "transition", "silence", "brand", "captions",
-                          "graphics", "overlays", "audio", "loudness", "fit", "export", "check", "chapters"}),
+                          "graphics", "overlays", "audio", "loudness", "fit", "export", "check", "chapters",
+                          "template"}),
     "clips[]": frozenset({"src", "in", "out", "speed"}),
-    "frame": frozenset({"aspect", "width", "height", "fps"}),
+    "frame": frozenset({"aspect", "width", "height", "fps", "fit"}),
     "transition": frozenset({"type", "duration"}),
     "silence": frozenset({"threshold", "min_silence", "margin"}),
     "captions": frozenset({"text", "srt", "ass", "font", "size", "color", "position", "margin",
                            "animate", "highlight_color", "outline", "karaoke", "bold", "box",
                            "lang", "offset", "max_lines", "min_duration"}),
+    # the 1.14 social templates (sticker/hook/meme) take their own text and timing, so a
+    # graphics[] entry can carry them too -- a template that only works from the CLI is not
+    # "usable inside a render.py graphics[] entry" (review 12)
     "graphics[]": frozenset({"template", "name", "title", "subtitle", "start", "end", "position",
-                             "from", "scale", "primary", "text_color", "lang"}),
+                             "from", "scale", "primary", "text_color", "lang",
+                             "text", "top", "bottom", "duration", "margin", "platform"}),
     "overlays[]": frozenset({"logo", "image", "text", "position", "start", "end", "fade", "opacity",
-                             "scale", "font_size", "font", "font_file", "margin", "box"}),
+                             "scale", "font_size", "font", "font_file", "margin", "box", "platform"}),
     "audio": frozenset({"music", "replace", "music_volume", "fade_in", "fade_out", "music_fade_out",
                         "gain", "duck_amount", "duck_threshold", "duck_attack", "duck_release",
                         "voice", "denoise", "duck", "music_loop", "stereo", "mono", "downmix",
@@ -117,6 +130,216 @@ NEAR_KEYS: Dict[str, Dict[str, str]] = {"clips[]": {"start": "in", "end": "out",
                                         "chapters[]": {"start": "at", "time": "at", "name": "title"}}
 
 
+def template_names() -> List[str]:
+    """Every templates/<name>.json that ships with the skill."""
+    return sorted(p.stem for p in TEMPLATE_DIR.glob("*.json"))
+
+
+def load_template(name: str) -> Dict[str, Any]:
+    path = TEMPLATE_DIR / f"{name}.json"
+    if not path.is_file():
+        die(f"unknown template {name!r}", hint="templates: " + ", ".join(template_names()) + " (or 'all')")
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        die(f"cannot read template {path}: {exc}")
+    return {}
+
+
+def fill_template(node: Any, values: Dict[str, Any]) -> "tuple":
+    """Substitute the $PLACEHOLDERS a template carries; return (filled, complete).
+
+    complete=False means a placeholder in this node had no value, and the caller drops the
+    whole block: a template's overlay entry is `{"image": "$LOGO"}`, so a run without --logo
+    must lose the overlay entirely rather than render an overlay of nothing."""
+    if isinstance(node, str):
+        if node in PLACEHOLDERS:
+            value = values.get(node)
+            return value, value is not None
+        return node, True
+    if isinstance(node, list):
+        kept = []
+        for item in node:
+            filled, ok = fill_template(item, values)
+            if ok:
+                kept.append(filled)
+        return kept, True
+    if isinstance(node, dict):
+        out: Dict[str, Any] = {}
+        complete = True
+        for key, value in node.items():
+            filled, ok = fill_template(value, values)
+            if not ok:
+                complete = False
+                continue
+            out[key] = filled
+        return out, complete
+    return node, True
+
+
+def template_project(name: str, args) -> Dict[str, Any]:
+    """One template plus the run's arguments as a ready-to-render project."""
+    tpl = load_template(name)
+    dest = str((tpl.get("check") or {}).get("platform") or name)
+    if args.srt and isinstance(tpl.get("captions"), dict) and "text" in tpl["captions"]:
+        cap = {("srt" if k == "text" else k): ("$SRT" if k == "text" else v) for k, v in tpl["captions"].items()}
+        tpl["captions"] = cap
+    # The caption block's size and margin are the table's, not a literal restated in the JSON:
+    # change a destination's safe zone in scripts/_platforms.py and every template follows.
+    if isinstance(tpl.get("captions"), dict) and dest in PLATFORMS and PLATFORMS[dest].get("frame"):
+        defaults = caption_defaults(dest)
+        tpl["captions"]["size"] = defaults["size"]
+        tpl["captions"]["margin"] = defaults["margin"]
+        for key in ("position", "animate", "outline"):
+            tpl["captions"].setdefault(key, defaults[key])
+    output = args.output or str(template_output(args.input, name, dest))
+    values = {
+        "$INPUT": os.path.abspath(args.input),
+        "$OUTPUT": os.path.abspath(output),
+        "$CUES": os.path.abspath(args.cues) if args.cues else None,
+        "$SRT": os.path.abspath(args.srt) if args.srt else None,
+        "$LOGO": os.path.abspath(args.logo) if args.logo else None,
+        "$BRAND": os.path.abspath(args.brand) if args.brand else None,
+        "$CHAPTERS": os.path.abspath(args.chapters) if args.chapters else None,
+        "$TITLE": args.title,
+    }
+    for flag, path in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
+                       ("--brand", args.brand), ("--chapters", args.chapters)):
+        if path and not os.path.isfile(path):
+            die(f"{flag}: file not found: {path}")
+    proj, _ = fill_template(tpl, values)
+    if args.fit:
+        proj.setdefault("frame", {})["fit"] = args.fit
+    return proj
+
+
+def template_ext(dest: str) -> str:
+    """A destination with no frame delivers audio: the podcast template writes .m4a, not .mp4."""
+    return ".mp4" if (PLATFORMS.get(dest) or {}).get("frame") else ".m4a"
+
+
+def template_output(input_path: str, name: str, dest: str) -> Path:
+    """Where a template writes when no -o was given: next to the input, named after it and the
+    template. One rule for a single template and for a pack, so `--template tiktok` and
+    `--template tiktok,x` put their files in the same place (review 12)."""
+    stem = Path(input_path).with_suffix("").name
+    return Path(input_path).resolve().parent / f"{stem}_{name}{template_ext(dest)}"
+
+
+def list_templates() -> None:
+    """The templates, the destination each delivers to, and the zones its UI covers."""
+    print("%-15s %-11s %-5s %7s  %-10s %s" % ("template", "frame", "fit", "max", "loudness", "safe zones (fraction of the frame)"))
+    for name in template_names():
+        tpl = load_template(name)
+        dest = str((tpl.get("check") or {}).get("platform") or name)
+        plat = PLATFORMS.get(dest) or {}
+        frame = plat.get("frame")
+        spec = plat.get("spec") or {}
+        safe = plat.get("safe") or {}
+        dur = spec.get("max_duration")
+        zones = ", ".join("%s %.2f" % (edge, safe.get(edge, 0)) for edge in ("top", "bottom", "left", "right") if safe.get(edge))
+        size = "%dx%d" % (frame["w"], frame["h"]) if frame else "audio"
+        fit = str((tpl.get("frame") or {}).get("fit") or "-")
+        loud = ("%g LUFS" % spec["lufs"]) if spec.get("lufs") is not None else "-"
+        print("%-15s %-11s %-5s %7s  %-10s %s" % (name, size, fit, ("%gs" % dur) if dur else "-", loud, zones or "none"))
+
+
+# `--template all`: every destination a single edit is normally posted to. The podcast template
+# is audio-only and youtube-shorts is an alias of shorts, so neither belongs in a video pack.
+PACK_DEFAULT = ["tiktok", "reels", "shorts", "youtube", "x", "linkedin", "facebook"]
+
+
+def expand_templates(value: str) -> List[str]:
+    if value.strip() == "all":
+        return list(PACK_DEFAULT)
+    names = [n.strip() for n in value.split(",") if n.strip()]
+    if not names:
+        die("--template needs a name, a comma-separated list, or 'all'")
+    known = template_names()
+    seen: List[str] = []
+    for name in names:
+        # the spellings people write resolve to the destination they mean, the same way
+        # check.py --platform and export.py --preset take them (scripts/_platforms.py)
+        if name not in known:
+            name = resolve_platform(name) or name
+        if name not in known:
+            die(f"unknown template {name!r}", hint="templates: " + ", ".join(known) + " (or 'all')")
+        if name not in seen:
+            seen.append(name)
+    return seen
+
+
+def render_pack(names: List[str], args) -> int:
+    """The social pack: one edit delivered to every named destination, plus a table of what
+    was written. Each destination is a full render (its own frame, captions, loudness, export
+    and platform check), so the pack reports per-platform results rather than one verdict."""
+    stem = Path(args.input).with_suffix("").name
+    outdir = Path(args.output).parent if args.output else Path(args.input).resolve().parent
+    dests = {name: str((load_template(name).get("check") or {}).get("platform") or name) for name in names}
+    rows: List[Dict[str, Any]] = []
+    outputs: List[str] = []
+    failed: List[str] = []
+    for name in names:
+        # the destination decides the container: an audio-only destination in a pack must not be
+        # handed a .mp4 name the single-template form would never have written (review 12)
+        dest_out = str(outdir / (stem + "_" + name + template_ext(dests[name])))
+        argv = [str(HERE / "render.py"), args.input, "--template", name, "-o", dest_out]
+        for flag, value in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
+                            ("--title", args.title), ("--brand", args.brand), ("--fit", args.fit),
+                            ("--chapters", args.chapters)):
+            if value:
+                argv += [flag, str(value)]
+        info(f"→ pack: {name}")
+        proc = run_tool(argv + child_args() + ["--json"])
+        try:
+            doc = json.loads(proc.stdout.strip() or "{}")
+        except ValueError:
+            doc = {}
+        # the child ran with --json, so its planned commands come back in the document: the pack
+        # is the one path that writes seven files, and --dry-run has to show all of them
+        for line in proc.stderr.splitlines():
+            if line.startswith("$ ") or line.startswith("[dry-run]"):
+                STATE.commands.append(line[2:] if line.startswith("$ ") else line)
+        STATE.commands.extend(str(c) for c in (doc.get("commands") or []))
+        out = doc.get("output") or dest_out
+        chk = doc.get("check") or {}
+        ok = proc.returncode == 0 and doc.get("status") == "completed"
+        probe_doc = doc.get("probe") or {}
+        if STATE.dry_run:
+            # A dry run encoded nothing and verified nothing. Reading a size off a file left over
+            # from an earlier real run, or calling an unrun check "pass", reports a verification
+            # result for a run that never happened (review 12).
+            rows.append({"platform": name, "file": os.path.basename(out), "path": out,
+                         "size_bytes": None, "duration": None, "check": "planned", "ok": bool(ok)})
+            continue
+        size = os.path.getsize(out) if os.path.exists(out) else 0
+        rows.append({"platform": name, "file": os.path.basename(out), "path": out,
+                     "size_bytes": size, "duration": probe_doc.get("duration"),
+                     "check": ("pass" if chk.get("ok") else ("%d FAIL" % chk["failed"]) if chk.get("failed") else ("pass" if ok else "failed")),
+                     "ok": bool(ok)})
+        outputs.append(out)
+        if not ok:
+            failed.append(name)
+    pack = str(outdir / f"{stem}_pack.md")
+    lines = [f"# Social pack — {stem}", "",
+             "| platform | file | size | duration | check |", "|---|---|---|---|---|"]
+    for r in rows:
+        dur = f"{r['duration']:.2f} s" if r.get("duration") else "-"
+        mb = f"{r['size_bytes'] / 1024 / 1024:.1f} MB" if r.get("size_bytes") else "-"
+        lines.append(f"| {r['platform']} | {r['file']} | {mb} | {dur} | {r['check']} |")
+    lines += ["", f"{len(rows)} destinations from one edit ({os.path.basename(args.input)}).",
+              "Rendered by ffmpeg-skill; `report.py --pack` turns this table into an HTML report."]
+    if not STATE.dry_run:
+        Path(pack).write_text("\n".join(lines) + "\n", encoding="utf-8")
+    info(("[dry-run] would write " if STATE.dry_run else "wrote ") + pack)
+    if failed:
+        die(f"pack: {len(failed)} of {len(rows)} destinations failed: {', '.join(failed)}",
+            kind="verification", output=pack, dry_run=STATE.dry_run, pack=rows, outputs=outputs)
+    emit(pack, pack=rows, outputs=outputs, stages=["pack"],
+         verification=[{"step": "check", "ok": r["ok"], "platform": r["platform"]} for r in rows])
+    return 0
+
+
 def check_keys(obj: Any, schema: str, label: str) -> None:
     """Refuse an unrecognised key, naming the object, the key and the nearest valid one."""
     if not isinstance(obj, dict):
@@ -275,29 +498,74 @@ def main() -> int:
     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)")
+    tpl = ap.add_argument_group("delivery templates (one command per destination)")
+    tpl.add_argument("--template", metavar="NAME", help="render INPUT with a shipped template: " + ", ".join(template_names())
+                                                        + ", a comma-separated list, or 'all' (the social pack)")
+    tpl.add_argument("--list-templates", action="store_true", help="print the templates with their frames, limits and safe zones, and exit")
+    tpl.add_argument("--cues", help="cue file for the template's captions (caption.py --text format)")
+    tpl.add_argument("--srt", help="SRT file for the template's captions instead of --cues")
+    tpl.add_argument("--logo", help="logo image the template overlays")
+    tpl.add_argument("--title", help="title text for the template's opening card / lower third")
+    tpl.add_argument("--brand", help="brand.json the template's captions, graphics and overlays use")
+    tpl.add_argument("--chapters", help="chapter file (podcast template)")
+    tpl.add_argument("--fit", choices=["crop", "pad", "blur"], help="override how the template reaches its aspect")
+    tpl.add_argument("-o", "--output", help="output file (default: next to the input, <input>_<template>.mp4, "
+                                            "or .m4a for an audio-only destination); for a list of templates "
+                                            "or 'all' its directory is where the pack is written")
+    tpl.add_argument("--write-project", metavar="FILE", help="write the filled project.json for editing and stop (no render)")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
 
+    if args.list_templates:
+        list_templates()
+        return 0
     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)")
+        die("give a project.json (or --init FILE, or --template NAME INPUT)")
     if STATE.plan:
         die("render.py has no --plan: the project file is the plan (use --dry-run to preview it)")
-    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}")
-    if not isinstance(proj, dict):
-        die(f"{args.project}: not a project or plan object (top level is {type(proj).__name__})")
-    if "plan_version" in proj:
-        return execute_plan(proj, os.path.abspath(args.project))
+    if args.template:
+        # `render.py --template tiktok talk.mp4 ...`: the positional is the footage, not a project.
+        args.input = args.project
+        if not os.path.isfile(args.input):
+            die(f"input not found: {args.input}")
+        names = expand_templates(args.template)
+        if len(names) > 1:
+            if args.write_project:
+                die("--write-project writes one project; name a single template")
+            return render_pack(names, args)
+        proj: Dict[str, Any] = template_project(names[0], args)
+        base = Path.cwd()
+    else:
+        for flag, value in (("--cues", args.cues), ("--srt", args.srt), ("--logo", args.logo),
+                            ("--title", args.title), ("--brand", args.brand), ("--chapters", args.chapters),
+                            ("--fit", args.fit), ("--write-project", args.write_project)):
+            if value:
+                die(f"{flag} belongs to --template NAME INPUT; a project.json states it in the project itself")
+        try:
+            proj = json.loads(Path(args.project).read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            die(f"cannot read project: {exc}")
+        if not isinstance(proj, dict):
+            die(f"{args.project}: not a project or plan object (top level is {type(proj).__name__})")
+        if "plan_version" in proj:
+            return execute_plan(proj, os.path.abspath(args.project))
+        base = Path(args.project).resolve().parent
     validate_project(proj)
-    base = Path(args.project).resolve().parent
+    if args.write_project:
+        # Only the filled project: the point is to edit it before rendering, so nothing runs.
+        try:
+            Path(args.write_project).write_text(json.dumps(proj, indent=2) + "\n", encoding="utf-8")
+        except OSError as exc:
+            die(f"cannot write {args.write_project}: {exc}", kind="output")
+        info(f"wrote {args.write_project}; edit it and run: render.py {args.write_project}")
+        emit(args.write_project, template=args.template, stages=[], check=None)
+        return 0
 
     def rel(p: Any) -> str:
         p = str(p)
@@ -330,10 +598,20 @@ def main() -> int:
         import atexit
         import shutil
         atexit.register(lambda: shutil.rmtree(work, ignore_errors=True))
+    # Intermediates keep the delivery's media kind: a .mp4 project is unchanged (every stage file
+    # is still clipNN.mp4 / fit.mp4 / loudnorm.mp4), while an audio-only delivery (the podcast
+    # template) carries its stages through the audio container instead of a video one.
+    mid = Path(output).suffix.lower() if Path(output).suffix.lower() in AUDIO_EXT else ".mp4"
     frame = dict(proj.get("frame") or {})
     trans = proj.get("transition") or {}
     frame_from_preset(frame, proj.get("export") or {})
     brand_args: List[str] = ["--brand", rel(proj["brand"])] if proj.get("brand") else []
+    # A project written from a delivery template names its destination, so the caption and
+    # graphics stages are told which zones that app's UI covers; the template's own explicit
+    # margin/size still win inside those tools. A hand-written project (no "template" key) is
+    # unchanged -- it never gets a --platform it did not ask for.
+    dest = str(((proj.get("check") or {}).get("platform") or "")) if proj.get("template") else ""
+    platform_args: List[str] = ["--platform", dest] if dest in PLATFORMS and PLATFORMS[dest].get("frame") else []
     stages_done: List[str] = []
 
     # ---- clips
@@ -345,7 +623,7 @@ def main() -> int:
         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")
+        part = str(work / f"clip{i:02d}{mid}")
         if needs_cut:
             argv: List[Any] = [src, "-o", part, "--accurate"]
             if c.get("in") is not None:
@@ -361,7 +639,7 @@ def main() -> int:
                 die(f"clip {i}: speed must be a positive number, got {c['speed']!r}")
             if abs(spd - 1.0) > 1e-6:  # speed 1.0 used to cost a full re-encode for nothing
                 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")
+                fitted = str(work / f"clip{i:02d}_speed{mid}")
                 sh("fit.py", part, "--duration", f"{dur / spd:.3f}", "-o", fitted)
                 part = fitted
         parts.append(part)
@@ -373,7 +651,7 @@ def main() -> int:
 
     # ---- join
     if len(parts) > 1:
-        current = str(work / "joined.mp4")
+        current = str(work / f"joined{mid}")
         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"])]
@@ -390,7 +668,7 @@ def main() -> int:
     # ---- silence
     sil = proj.get("silence")
     if sil:
-        nxt = str(work / "tight.mp4")
+        nxt = str(work / f"tight{mid}")
         argv = [current, "-o", nxt]
         for k, flag in (("threshold", "--threshold"), ("min_silence", "--min-silence"), ("margin", "--margin")):
             if sil.get(k) is not None:
@@ -406,6 +684,8 @@ def main() -> int:
     fit = dict(proj.get("fit") or {})
     if frame.get("aspect"):
         fit.setdefault("aspect", frame["aspect"])
+    if frame.get("fit"):
+        fit.setdefault("fit", frame["fit"])
     if frame.get("width") and len(parts) == 1:
         fit.setdefault("width", frame["width"])
     if frame.get("height") and len(parts) == 1:
@@ -413,7 +693,7 @@ def main() -> int:
     if frame.get("fps") and len(parts) == 1:
         fit.setdefault("fps", frame["fps"])
     if fit:
-        nxt = str(work / "fit.mp4")
+        nxt = str(work / f"fit{mid}")
         argv = [current, "-o", nxt]
         for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("height", "--height"), ("fps", "--fps"), ("smooth", "--smooth")):
             if fit.get(k) is not None:
@@ -428,7 +708,7 @@ def main() -> int:
     # ---- captions
     cap = proj.get("captions")
     if cap:
-        nxt = str(work / "captioned.mp4")
+        nxt = str(work / f"captioned{mid}")
         argv = [current, "-o", nxt]
         if cap.get("text"):
             argv += ["--text", rel(cap["text"])]
@@ -444,7 +724,7 @@ def main() -> int:
         for k, flag in (("karaoke", "--karaoke"), ("bold", "--bold"), ("box", "--box")):
             if cap.get(k):
                 argv.append(flag)
-        sh("caption.py", *(argv + brand_args))
+        sh("caption.py", *(argv + brand_args + platform_args))
         current = nxt
         stages_done.append("captions")
     if args.stop_after == "captions":
@@ -453,14 +733,16 @@ def main() -> int:
 
     # ---- graphics
     for i, g in enumerate(proj.get("graphics") or []):
-        nxt = str(work / f"graphics{i:02d}.mp4")
+        nxt = str(work / f"graphics{i:02d}{mid}")
         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"), ("lang", "--lang")):
+        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"), ("lang", "--lang"),
+                        ("text", "--text"), ("top", "--top"), ("bottom", "--bottom"), ("duration", "--duration"), ("margin", "--margin"), ("platform", "--platform")):
             if g.get(k) is not None:
                 argv += [flag, str(g[k])]
-        sh("graphics.py", *(argv + brand_args))
+        # the entry's own "platform" is the more specific statement than the template's destination
+        sh("graphics.py", *(argv + brand_args + ([] if g.get("platform") else platform_args)))
         current = nxt
         if "graphics" not in stages_done:
             stages_done.append("graphics")
@@ -470,7 +752,7 @@ def main() -> int:
 
     # ---- overlays
     for i, ov in enumerate(proj.get("overlays") or []):
-        nxt = str(work / f"overlay{i:02d}.mp4")
+        nxt = str(work / f"overlay{i:02d}{mid}")
         argv = [current, "-o", nxt]
         if ov.get("logo"):
             argv.append("--logo")
@@ -480,12 +762,14 @@ def main() -> int:
             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")):
+        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"), ("platform", "--platform")):
             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))
+        # review 12: the overlay stage was the one stage that never heard which destination this
+        # is, so a template's top-left logo landed 24 px in -- under TikTok's own status bar.
+        sh("overlay.py", *(argv + brand_args + ([] if ov.get("platform") else platform_args)))
         current = nxt
         if "overlays" not in stages_done:
             stages_done.append("overlays")
@@ -509,7 +793,7 @@ def main() -> int:
         for stem, key in (("dialogue", "gain"), ("music", "music_volume"), ("effects", "effects_volume")):
             if stems.get(stem) is not None:
                 au.setdefault(key, stems[stem])
-        nxt = str(work / "audio.mp4")
+        nxt = str(work / f"audio{mid}")
         argv = [current, "-o", nxt]
         for k, flag in (("music", "--music"), ("replace", "--replace"), ("effects", "--effects")):
             if au.get(k):
@@ -533,7 +817,7 @@ def main() -> int:
     # ---- loudness
     ld = proj.get("loudness")
     if ld:
-        nxt = str(work / "loudnorm.mp4")
+        nxt = str(work / f"loudnorm{mid}")
         argv = [current, "-o", nxt]
         if ld.get("lufs") is not None:
             argv += ["-I", str(ld["lufs"])]

package/scripts/report.py

@@ -7,6 +7,7 @@ Examples:
   python3 report.py --before raw.mov --after final.mp4 -o report.html
   python3 report.py --after final.mp4 --platform reels --title "Episode 12 — Reels cut" -o report.html
   python3 report.py --before raw.mov --after final.mp4 --commands commands.txt --notes notes.md
+  python3 report.py --pack talk_pack.md -o pack.html          # the social pack table as HTML
 """
 import argparse
 import base64
@@ -79,9 +80,76 @@ def media_rows(meta: Dict[str, Any], ld: Dict[str, Any]) -> List[List[str]]:
     return rows
 
 
+PACK_CSS = """
+    :root{--bg:#F4F6F8;--paper:#fff;--ink:#161B21;--ink2:#4B5661;--line:#D8DEE4;--ok:#2C8A5B;--bad:#B4362F}
+    @media (prefers-color-scheme:dark){:root{--bg:#111518;--paper:#191E23;--ink:#E8ECEF;--ink2:#AEB6BE;--line:#2A3138;--ok:#5CC38C;--bad:#F07A73}}
+    body{margin:0;background:var(--bg);color:var(--ink);font:15px/1.6 system-ui,-apple-system,"Segoe UI",Roboto,"Noto Sans JP",sans-serif}
+    .wrap{max-width:900px;margin:0 auto;padding:32px 20px 60px}
+    h1{font-size:24px;margin:0 0 16px}
+    table{border-collapse:collapse;width:100%;font-size:14px;background:var(--paper);border:1px solid var(--line);border-radius:6px;overflow:hidden}
+    th,td{text-align:left;padding:7px 10px;border-bottom:1px solid var(--line)}th{color:var(--ink2);font-weight:500}
+    td.pass{color:var(--ok);font-weight:600}td.bad{color:var(--bad);font-weight:600}
+    p.note{color:var(--ink2);font-size:13px}
+    .foot{color:var(--ink2);font-size:12px;margin-top:30px;border-top:1px solid var(--line);padding-top:10px}
+"""
+
+
+def pack_report(args) -> int:
+    """render.py --template all writes <stem>_pack.md: one row per destination. This renders the
+    same rows as HTML, so a pack can be handed over the way a single delivery report is -- no
+    re-measurement, because the pack table is what the renders actually produced."""
+    text = read_text_or_die(args.pack, "--pack")
+    rows: List[List[str]] = []
+    header: List[str] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line.startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip("|").split("|")]
+        if all(set(c) <= set("-: ") for c in cells):
+            continue
+        if not header:
+            header = cells
+        else:
+            rows.append(cells)
+    if not rows:
+        die(f"{args.pack}: no pack table found (expected the Markdown table render.py --template all writes)")
+    title = args.title or f"Social pack — {Path(args.pack).stem.replace('_pack', '')}"
+    output = args.output or str(Path(args.pack).with_suffix(".html"))
+    head = "".join(f"<th>{html.escape(h)}</th>" for h in header)
+    body = ""
+    for r in rows:
+        cells = ""
+        for i, c in enumerate(r):
+            cls = ""
+            if header[i:i + 1] == ["check"]:
+                cls = " class='pass'" if c.lower() == "pass" else " class='bad'"
+            cells += f"<td{cls}>{html.escape(c)}</td>"
+        body += f"<tr>{cells}</tr>"
+    doc = ("<!doctype html><html><head><meta charset='utf-8'><meta name='viewport' content='width=device-width,initial-scale=1'>"
+           f"<title>{html.escape(title)}</title><style>{PACK_CSS}</style></head><body><div class='wrap'>"
+           f"<h1>{html.escape(title)}</h1><table><tr>{head}</tr>{body}</table>"
+           f"<p class='note'>{len(rows)} destination(s) from one edit.</p>"
+           "<p class='foot'>Generated by ffmpeg-skill · local FFmpeg, no cloud.</p></div></body></html>")
+    if STATE.dry_run:
+        info(f"wrote {output}")
+    else:
+        try:
+            Path(output).write_text(doc, encoding="utf-8")
+        except OSError as e:
+            die(f"cannot write {output}: {e}", kind="output")
+        info(f"wrote {output} ({os.path.getsize(output) / 1024:.0f} KB)")
+    emit(None, report=output, pack=[dict(zip(header, r)) for r in rows], check=None,
+         verification=([{"step": "exists", "ok": True}] if not STATE.dry_run else []))
+    if not args.json:
+        print(output)
+    return 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--after", required=True, help="the deliverable")
+    ap.add_argument("--after", help="the deliverable (required unless --pack is given)")
+    ap.add_argument("--pack", metavar="FILE", help="a social pack table written by render.py --template all (<stem>_pack.md): render it as HTML")
     ap.add_argument("--before", help="the source (optional)")
     ap.add_argument("-o", "--output", help="report path (default: <after>_report.html)")
     ap.add_argument("--title", help="report title")
@@ -93,6 +161,10 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    if args.pack:
+        return pack_report(args)
+    if not args.after:
+        die("--after is required (or --pack FILE for a social pack table)")
     after = probe(args.after)
     before = probe(args.before) if args.before else None
     ld_after = loudness(args.after) if after.get("audio") else {}

package/templates/facebook.json

@@ -0,0 +1,47 @@
+{
+  "template": "facebook",
+  "output": "$OUTPUT",
+  "clips": [
+    {
+      "src": "$INPUT"
+    }
+  ],
+  "frame": {
+    "aspect": "16:9",
+    "fit": "pad"
+  },
+  "brand": "$BRAND",
+  "captions": {
+    "text": "$CUES",
+    "animate": "none",
+    "karaoke": false,
+    "size": 20,
+    "position": "bottom",
+    "margin": 14
+  },
+  "graphics": [
+    {
+      "template": "lower-third",
+      "name": "$TITLE",
+      "start": 1,
+      "end": 6
+    }
+  ],
+  "overlays": [
+    {
+      "image": "$LOGO",
+      "position": "top-left"
+    }
+  ],
+  "loudness": {
+    "lufs": -14,
+    "tp": -1.0
+  },
+  "export": {
+    "preset": "facebook",
+    "normalize": true
+  },
+  "check": {
+    "platform": "facebook"
+  }
+}