ffmpeg-skill 1.13.0 → 1.14.0

package/scripts/overlay.py

@@ -24,24 +24,30 @@ import argparse
 import sys
 from typing import List, Optional
 
+from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import STATE, script_font_for_text, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 
+# Per-edge margins: a platform's UI does not cover the same fraction of every edge (TikTok's
+# like column is 14 % of the width, its description block 22 % of the height), so a position
+# names the edges it is measured from rather than one --margin for all four.
 POS = {
-    "top-left": ("{m}", "{m}"),
-    "top": ("(W-w)/2", "{m}"),
-    "top-right": ("W-w-{m}", "{m}"),
-    "left": ("{m}", "(H-h)/2"),
+    "top-left": ("{left}", "{top}"),
+    "top": ("(W-w)/2", "{top}"),
+    "top-right": ("W-w-{right}", "{top}"),
+    "left": ("{left}", "(H-h)/2"),
     "center": ("(W-w)/2", "(H-h)/2"),
-    "right": ("W-w-{m}", "(H-h)/2"),
-    "bottom-left": ("{m}", "H-h-{m}"),
-    "bottom": ("(W-w)/2", "H-h-{m}"),
-    "bottom-right": ("W-w-{m}", "H-h-{m}"),
+    "right": ("W-w-{right}", "(H-h)/2"),
+    "bottom-left": ("{left}", "H-h-{bottom}"),
+    "bottom": ("(W-w)/2", "H-h-{bottom}"),
+    "bottom-right": ("W-w-{right}", "H-h-{bottom}"),
 }
 
 
-def position_exprs(pos: str, margin: int, text_mode: bool):
+def position_exprs(pos: str, margin: int, text_mode: bool, margins: Optional[dict] = None):
+    edges = margins or {}
+    m = {edge: int(edges.get(edge, margin)) for edge in ("top", "bottom", "left", "right")}
     if pos in POS:
-        x, y = (e.format(m=margin) for e in POS[pos])
+        x, y = (e.format(**m) for e in POS[pos])
     else:
         try:
             xs, ys = pos.split(",")
@@ -101,6 +107,10 @@ def main() -> int:
     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("--platform", choices=PLATFORM_CHOICES, default=None,
+                    help="keep the overlay out of this destination's UI: each edge's margin becomes that "
+                         "platform's safe zone (scripts/_platforms.py), so a top-left logo clears TikTok's "
+                         "status bar and a right-hand one clears the like column. An explicit --margin wins")
     ap.add_argument("--start", help="show from this time (default: whole video)")
     ap.add_argument("--end", help="hide after this time")
     ap.add_argument("--fade", type=float, default=0.0, help="fade-in duration in seconds (at --start or 0); the fade-out happens only at --end")
@@ -163,6 +173,20 @@ def main() -> int:
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
     vw = meta["video"]["width"]
+    # --platform: the edges this destination's own UI covers, in pixels of this frame. An
+    # explicit --margin (or a brand safe_margin, applied above) is the more specific statement
+    # and wins; without either, the historical 24 px default is unchanged.
+    safe_margins = None
+    args.platform = resolve_platform(args.platform)
+    if args.platform and args.margin == ap.get_default("margin") and PLATFORMS[args.platform].get("frame"):
+        # a dry run has no real frame to measure (the probe is stubbed rather than guessed), so
+        # fall back to the destination's own delivery frame -- which is what the fitted
+        # intermediate this stage runs on will be anyway
+        frame = PLATFORMS[args.platform]["frame"]
+        pw, ph = vw or frame["w"], meta["video"].get("height") or frame["h"]
+        safe_margins = safe_margins_px(args.platform, pw, ph)
+        info(f"--platform {args.platform}: safe margins top {safe_margins['top']} / bottom {safe_margins['bottom']} / "
+             f"left {safe_margins['left']} / right {safe_margins['right']} px (clear of the app's own UI)")
     fps = meta["video"].get("fps")
     start = time_arg(args.start, "--start", fps) if args.start else None
     end = time_arg(args.end, "--end", fps) if args.end else None
@@ -203,7 +227,7 @@ def main() -> int:
             chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
             if end is not None and end > args.fade:
                 chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
-        x, y = position_exprs(args.position, args.margin, text_mode=False)
+        x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
         ov = f"overlay={x}:{y}:format=auto"
         if enable:
             ov += f":enable='{enable}'"
@@ -237,7 +261,7 @@ def main() -> int:
             chain.append(f"chromakey={args.chromakey}:{args.chromakey_similarity:g}:{args.chromakey_blend:g}")
         if args.opacity < 1:
             chain.append(f"colorchannelmixer=aa={args.opacity:g}")
-        x, y = position_exprs(args.position, args.margin, text_mode=False)
+        x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
         ov = f"overlay={x}:{y}:format=auto"
         if enable:
             ov += f":enable='{enable}'"
@@ -251,7 +275,7 @@ def main() -> int:
         else:
             cmd += ["-shortest"]
     else:
-        x, y = position_exprs(args.position, args.margin, text_mode=True)
+        x, y = position_exprs(args.position, args.margin, text_mode=True, margins=safe_margins)
         opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
                 f"borderw={args.border}", f"bordercolor={args.border_color}"]
         if args.font_file:

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