ffmpeg-skill 1.13.0 → 1.14.0

package/references/gotchas.md

@@ -158,6 +158,21 @@ visibly choppy for sports, gaming, drone pans. Keep 60 when the platform allows.
 trim it drops two thirds of the words. Ask which, or propose a highlight cut with
 `scenes.py`.
 
+### Platform safe zones
+Every vertical app draws its own UI over the delivery: TikTok covers roughly the
+bottom 22 % (description and caption block), the right 14 % (like/comment/share
+column) and the top 10 % (status bar and tabs); Reels 20/12/8 %; Shorts 18/12/6 %.
+The feed destinations (YouTube, X, LinkedIn, Facebook) have no persistent overlay
+and use the conventional 5 % title-safe border instead. A file can pass every
+`check.py` row and still be unreadable because the caption sits under the
+description.
+
+The fractions live in one table (`scripts/_platforms.py`). `caption.py --platform
+NAME`, `graphics.py --platform NAME` and `overlay.py --platform NAME` take their
+margins from it, `render.py --template NAME` passes it to all three, and
+`look.py --safe tiktok` shades the zones on a frame or contact sheet so you can
+see what the app covers. An explicit `--margin` always wins.
+
 ### Dimensions and rotation
 `yuv420p` needs even width/height; `fit.py` and `export.py` round to even values
 automatically. Phone footage often carries a `rotation` tag; `probe.py` reports

package/references/scripts.md

@@ -29,6 +29,7 @@ between tools.
 - silence.py — remove dead air / jump cuts
 - join.py — concatenate with transitions
 - render.py — the whole edit in one project.json
+- delivery templates — one command per destination (`--template`)
 - scenes.py — scene changes and highlight candidates
 - check.py — pre-delivery compliance
 - batch.py — same recipe over a folder, cached
@@ -76,7 +77,7 @@ re-encode, the result's `lossless_alternative` names the nearest keyframe
 ### fit.py — target duration and/or aspect, rotate/flip
 ```
 fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
-             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black] [--pad-fill color|blur [--pad-blur 20]]]
+             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop|blur [--width W] [--height H] [--pad-color black] [--pad-fill color|blur [--pad-blur 20]]]
              [--rotate 90|180|270] [--flip h|v] [--fps N] [-o OUT]
 ```
 `speed` retimes video and audio together (pitch-preserving `atempo`); it
@@ -94,7 +95,13 @@ automatically even without it.
 `--pad-fill blur` fills the letterbox/pillarbox bars with a blurred, scaled-to-cover copy
 of the frame (the look every phone editor gives landscape footage posted as a Short/Reel)
 instead of the solid `--pad-color`; `--pad-blur` is the blur radius. `export.py --fit pad`
-takes the same two flags.
+takes the same two flags. `--fit blur` (1.14) is the same fill named in one word and with the
+background dimmed (`eq brightness=-0.15`) so the picture in front reads as the subject: the
+whole frame is kept (nothing cropped), the borders are a blurred copy of it rather than black.
+A delivery template asks for it as `"frame": {"aspect": "9:16", "fit": "blur"}`, or
+`render.py --template tiktok clip.mp4 --fit blur`. The dimming is applied to SDR sources only:
+an `eq` on PQ/HLG code values is not the −15 % perceptual dim it is on SDR, so an HDR source
+keeps a blurred but undimmed background (and is never silently tone-mapped); `info` says so.
 
 ### crop.py — crop to an exact pixel rectangle
 ```
@@ -430,6 +437,56 @@ more than two steps or the user is likely to ask for changes: edit the JSON,
 re-render, and the result is reproducible. `--dry-run --json` prints the
 complete command plan for review.
 
+### Delivery templates — one command per destination (1.14)
+```
+render.py --template tiktok INPUT [--cues cues.txt | --srt subs.srt] [--logo logo.png] [--title "..."]
+          [--brand brand.json] [--chapters chapters.txt] [--fit crop|pad|blur] [-o OUT]
+render.py --template all INPUT ...        # or a comma list: one delivery per destination + <stem>_pack.md
+render.py --list-templates                # the table below, from the running install
+render.py --template tiktok INPUT --write-project project.json    # fill it, edit it, render it later
+```
+A template is a `render.py` project shipped in `templates/<name>.json` with `$INPUT`, `$OUTPUT`,
+`$CUES`/`$SRT`, `$LOGO`, `$TITLE`, `$BRAND` and `$CHAPTERS` placeholders. Filling it substitutes
+what the run was given and **drops any block whose placeholder has no value** — no `--logo` means
+no overlay stage at all, not an overlay of nothing. The filled project then renders through the
+normal stages, so `--dry-run --json`, `--stop-after` and the work directory behave as always. An
+unknown name is refused (`kind: input`) with the list. Output defaults to
+`<input>_<template>.mp4` **next to the input** (`.m4a` for an audio-only destination such as
+`podcast`) — the same rule for one template and for a pack, whose `-o` names the directory.
+Alias spellings are accepted everywhere one name is: `youtube-shorts`/`yt-shorts` = `shorts`,
+`yt` = `youtube`, `instagram`/`ig` = `reels`, `twitter` = `x`, `fb` = `facebook`
+(`check.py --platform`, `export.py --preset`, `caption.py`/`graphics.py`/`overlay.py
+--platform`, `look.py --safe`, `render.py --template`).
+
+Under `--dry-run` a pack prints every child's planned commands and its table reads `planned`
+with no size or duration: nothing was encoded, so nothing is reported as verified. `--chapters`
+reaches a pack's audio destination like it does the single-template form.
+
+Each template's frame, duration limit, loudness target and safe zones come from the one delivery
+table (`scripts/_platforms.py`). Safe zones are the fraction of the frame the app's own UI covers;
+the template places captions, graphics **and the `--logo` overlay** clear of them, and
+`caption.py --platform`, `graphics.py --platform` and `overlay.py --platform` apply them to a
+hand-built step:
+
+| template | frame | max duration | loudness | safe top | safe bottom | safe left | safe right |
+|---|---|---|---|---|---|---|---|
+| `tiktok` | 1080x1920 (9:16) | 600 s | -14 LUFS / -1 dBTP | 0.10 | 0.22 | 0.05 | 0.14 |
+| `reels` | 1080x1920 (9:16) | 90 s | -14 LUFS / -1 dBTP | 0.08 | 0.20 | 0.05 | 0.12 |
+| `shorts` | 1080x1920 (9:16) | 180 s | -14 LUFS / -1 dBTP | 0.06 | 0.18 | 0.05 | 0.12 |
+| `youtube-shorts` | 1080x1920 (9:16) | 180 s | -14 LUFS / -1 dBTP | 0.06 | 0.18 | 0.05 | 0.12 |
+| `youtube` | 1920x1080 (16:9) | 43200 s | -14 LUFS / -1 dBTP | 0.05 | 0.05 | 0.05 | 0.05 |
+| `x` | 1280x720 (16:9) | 140 s | -14 LUFS / -1 dBTP | 0.05 | 0.05 | 0.05 | 0.05 |
+| `linkedin` | 1080x1080 (1:1) | 600 s | -14 LUFS / -1 dBTP | 0.05 | 0.05 | 0.05 | 0.05 |
+| `facebook` | 1920x1080 (16:9) | 14400 s | -14 LUFS / -1 dBTP | 0.05 | 0.05 | 0.05 | 0.05 |
+| `podcast` | audio only | — | -16 LUFS / -1 dBTP | 0.00 | 0.00 | 0.00 | 0.00 |
+
+`podcast` is audio: silence trim, −16 LUFS / −1 dBTP, chapter markers when `--chapters` is given,
+and `check.py --platform podcast`. `--template all` renders `tiktok, reels, shorts, youtube, x,
+linkedin, facebook` (not the audio template, not the `youtube-shorts` alias) into
+`<stem>_<platform>.mp4`, runs each platform's check and writes `<stem>_pack.md` with one row per
+destination; `report.py --pack <stem>_pack.md` renders that table as a single HTML page. A pack
+whose destinations did not all pass exits non-zero with the per-destination rows in `pack`.
+
 ### scenes.py — scene changes and highlight candidates
 ```
 scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
@@ -446,7 +503,7 @@ and why (energy, scene length).
 
 ### check.py — pre-delivery compliance
 ```
-check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|broadcast|podcast|custom [--no-loudness] [--json]
+check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|facebook|broadcast|podcast|custom [--no-loudness] [--json]
          [--max-duration S] [--aspect 9:16] [--lufs -14] [--tp -1] [--max-mb N]
 ```
 PASS/WARN/FAIL per check with the script that fixes it. Run it as the final
@@ -458,7 +515,11 @@ line, not FAIL: name the platform when the file is a delivery for it.
 stereo, WARN above — podcast players downmix 5.1 unpredictably) and `chapters`
 (PASS when the container carries at least one marker, WARN `none` otherwise —
 write them with `metadata.py --chapters`). Neither can FAIL a delivery, and
-neither appears for another platform.
+neither appears for another platform. Since 1.14 the per-platform numbers (duration, aspects,
+minimum height, fps, codecs, size, LUFS, true peak, SDR-only) come from the one delivery table
+in `scripts/_platforms.py`, which `export.py` and the `render.py` templates read too -- so the
+loudness a preset normalises to and the loudness this tool checks are the same value by
+construction, not by two lists agreeing.
 
 ### batch.py — same recipe over a folder, cached
 ```
@@ -486,8 +547,10 @@ Inside this skill, call the scripts directly; the server is for other hosts.
 
 ### graphics.py — motion-graphics templates
 ```
-graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug [--name] [--title] [--subtitle]
-            [--from N] [--start S] [--end E] [--position CORNER] [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [--lang XX] [-o OUT]
+graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug|sticker|hook|meme
+            [--name] [--title] [--subtitle] [--text] [--top] [--bottom] [--duration 3]
+            [--from N] [--start S] [--end E] [--position CORNER] [--margin PX] [--platform NAME]
+            [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [--lang XX] [-o OUT]
 ```
 Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
 the frame's short side; colours, font and safe margin come from `--brand`.
@@ -499,6 +562,15 @@ the script fails the job). RTL shaping in drawtext depends on the ffmpeg build
 them does not); `caption.py` always shapes, because it renders through libass:
 `references/gotchas.md#fonts-by-script`.
 
+All three are usable from a `render.py` project too: a `graphics[]` entry takes `text`, `top`,
+`bottom`, `duration`, `margin` and `platform` alongside the older keys.
+1.14 adds three social templates: `sticker` (`--text`, a filled chip that pops in at
+`--position`), `hook` (`--title --duration 3`, the full-width opening card with a thin progress
+bar along the top that empties as the card's time runs out) and `meme` (`--top` / `--bottom`,
+upper-case white with a heavy black outline). `--platform NAME` takes each edge's margin from
+that destination's safe zone (see "Delivery templates" above), so a sticker stays off TikTok's
+like column; `--margin PX` sets all four edges and wins over `--platform`.
+
 ### brand.json — one file for fonts, colours, logo, margins
 ```json
 {"font": "Noto Sans CJK JP", "font_file": "fonts/NotoSansCJK-Bold.ttc",
@@ -555,9 +627,13 @@ seen before, and fix or report what fails.
 look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes
 look.py INPUT --at 2.5 [--at 7] [-o basename]                     # single frames -> basename_2.500s.png
 look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame
+look.py INPUT --safe tiktok [--at 3]                              # shade what the app's UI covers
 ```
 Outputs PNG. View it with the Read tool (or any image viewer) and judge the
-frame like an editor would. Use `--compare` to show before/after to the user.
+frame like an editor would. Use `--compare` to show before/after to the user. `--safe NAME` (1.14) shades the zones that
+destination's own UI covers -- TikTok's description block and like column, the Reels/Shorts
+chrome -- on the sheet or the frame, so "is the caption readable" can be answered about the app
+rather than about the file.
 
 ### caption.py — subtitles (static, animated, karaoke)
 ```
@@ -635,8 +711,11 @@ stream selection would have picked.
 ```
 overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
                   | --video CLIP [--chromakey COLOR [--chromakey-similarity 0-1] [--chromakey-blend 0-1]]
-           [--position top-right|bottom-left|center|X,Y] [--margin N] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
+           [--position top-right|bottom-left|center|X,Y] [--margin N] [--platform NAME] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
 ```
+`--platform NAME` (1.14) takes each edge's margin from that destination's safe zone
+(`scripts/_platforms.py`), so a template's top-left logo clears TikTok's status bar instead of
+sitting 24 px into it; an explicit `--margin` (or a brand `safe_margin`) wins.
 Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps
 playing. `--video` composites a second video as a picture-in-picture layer
 (same position/scale/opacity/time-range knobs as `--image`); only the main
@@ -772,7 +851,8 @@ integrated loudness ended more than 1 LU from the target because of it.
 
 ### export.py — delivery presets
 ```
-export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [--normalize] [-o OUT]
+export.py INPUT --preset youtube|youtube4k|reels|tiktok|shorts|linkedin|facebook|x|youtube-hdr|youtube-av1|prores|h265|gif|copy
+                [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [--normalize] [-o OUT]
 export.py --list
 ```
 Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
@@ -784,6 +864,15 @@ that fixes it -- or pass `--normalize`, which runs that call on the written
 file itself (audio re-encoded, video copied; `loudness.normalized: true`) so a
 platform export is one command instead of export, loudness, export again.
 
+Since 1.14 each social destination is its own preset rather than an alias: `tiktok`
+(1080x1920, max 600 s), `shorts` (1080x1920, max 180 s), `reels` (1080x1920, max 90 s),
+`linkedin` (1080x1080), `facebook` (1920x1080), each with its platform's loudness spec from the
+same table `check.py` reads, so `--normalize` and the check agree. `youtube-hdr` writes HEVC
+Main10 keeping the source's own HDR10/HLG tags and refuses an SDR source (`kind: input`, hinting
+at `--preset youtube`) rather than labelling SDR as HDR; `youtube-av1` encodes AV1 with
+SVT-AV1 (libaom fallback) and refuses with `kind: missing_tool` on an ffmpeg built with
+neither.
+
 ### proxy.py — low-bitrate proxy for analysis/preview
 ```
 proxy.py INPUT [--width W | --scale F] [--crf N] [--fps N] [--no-audio] [-o OUT]

package/scripts/_common.py

@@ -140,7 +140,7 @@ def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
     return str(max(vertical, horizontal))
 
 
-def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int) -> str:
+def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0) -> str:
     """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
 
     fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
@@ -148,14 +148,17 @@ def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int) -> str
     phone editor's "make it vertical" does with landscape footage (#139). Built as a small
     graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame
     then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is
-    needed beyond the usual scale/pad set, and that is already required by redact.py."""
+    needed beyond the usual scale/pad set, and that is already required by redact.py.
+    `darken` > 0 also dims that background copy by that much brightness (eq), so the picture in
+    front reads as the subject instead of competing with a bright blurred copy of itself --
+    what `fit.py --fit blur` uses (1.14)."""
     if fill == "blur":
         # boxblur rejects a radius larger than half the smaller dimension ("radius 20, must be
         # <= 8" on a 16 px target); clamp instead of failing an otherwise valid request
         radius = max(1, min(int(blur), max(1, min(out_w, out_h) // 2 - 1)))
         return (f"split[__fitfg][__fitbg];"
                 f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
-                f"boxblur={radius}:2[__fitbgb];"
+                f"boxblur={radius}:2" + (f",eq=brightness=-{darken:g}" if darken else "") + "[__fitbgb];"
                 f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
                 f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
     return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"

package/scripts/_contract.py

@@ -79,7 +79,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                 video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],
                 required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},
-                                                     {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
+                                                     {"capability": "filter:boxblur", "when": "--pad-fill blur or --fit blur"},
+                                                     {"capability": "filter:eq", "when": "--fit blur (the background copy is dimmed)"}],
                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
                  required=FF + [X264, AAC], optional=[HDR_X265],
@@ -187,7 +188,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
                    required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},
                                           {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},
-                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"},
+                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur or --fit blur"},
+                                                     {"capability": "filter:eq", "when": "--fit blur (the background copy is dimmed)"},
                                           {"capability": "filter:loudnorm", "when": "preset youtube / youtube4k / reels / x with audio: the written file is measured against the platform's loudness target (result `loudness`)"}],
                    video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],
@@ -197,10 +199,11 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                    required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"}],
                    video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "look": dict(role="verification", inputs=["video artifact"], outputs=["PNG contact sheet / frames / side-by-side"],
-                 required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
+                 required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"},
+                                                          {"capability": "filter:drawbox", "when": "--safe NAME (the platform's occluded zones)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
                  video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
-    "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)"], outputs=["final video artifact", "work directory of stage outputs (--keep / --work)"],
-                   required=FF, optional=[{"capability": "delegated", "when": "each stage runs cut / join / fit / caption / overlay / audio / loudness / export / check with their capabilities"}],
+    "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)"],
+                   required=FF, optional=[{"capability": "delegated", "when": "each stage (and each destination of --template) runs cut / join / fit / caption / graphics / overlay / audio / loudness / export / check with their capabilities"}],
                    video_required=True, audio_only=False, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],
                   required=FF, optional=[{"capability": "delegated", "when": "each recipe step runs the named script with its capabilities"}],

package/scripts/_platforms.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""One table per delivery destination (internal module, not a tool).
+
+Before 1.14 the same destination was described three times: check.py held the
+compliance spec (duration, aspect, codecs, loudness), export.py held the frame and
+encoder settings, and nothing at all held the part of the frame the app's own UI
+covers. A TikTok export therefore passed every check while its captions sat under
+the description bar. This module is the single table the delivery tools read:
+
+    PLATFORMS[name] = {
+        "frame":   {"w", "h", "aspect"} or None (audio-only destinations),
+        "fps":     the frame rate a delivery is conformed to (None = leave alone),
+        "spec":    check.py's compliance row values (max_duration, aspects,
+                   min_height, fps_max, codecs, max_bytes, lufs, lufs_tol, tp,
+                   sdr_only) -- the keys check.py's SPECS has always had,
+        "safe":    the fraction of the frame each edge's UI covers
+                   (top/bottom/left/right, 0..1) -- nothing readable goes there,
+        "caption": the caption defaults a template uses (size as a fraction of the
+                   frame height, position, box, outline, animate),
+        "preset":  the export.py preset that writes this destination's file,
+        "check":   the check.py platform name a delivery is verified against.
+    }
+
+Read by check.py (SPECS), export.py (PRESETS/PLATFORM_OF), render.py (templates),
+caption.py and graphics.py (--platform margins) and look.py (--safe).
+
+Safe zones are the app's own overlay, measured from each platform's published
+design guidance: TikTok's caption/description block and the like/comment column,
+Instagram's Reels UI, the Shorts player. They are deliberately generous -- a
+caption 2 % too high is readable, a caption under the share button is not. The
+feed destinations (YouTube, X, LinkedIn, Facebook) have no persistent overlay, so
+they carry the conventional 5 % title-safe border instead.
+
+ASS note: caption.py's --size and --margin are in the 288-line ASS script grid, so
+a fraction of the frame height is that fraction * 288 (ass_units() below); the
+burn scales it back to the real frame. graphics.py and look.py work in pixels.
+"""
+from typing import Any, Dict, List, Optional
+
+ASS_SCRIPT_HEIGHT = 288  # caption.py's --size/--margin reference grid
+
+
+def ass_units(fraction: float) -> int:
+    """A fraction of the frame height as a caption.py --size / --margin value."""
+    return int(round(fraction * ASS_SCRIPT_HEIGHT))
+
+
+# The edges a feed destination reserves: no app chrome, just the conventional title-safe border.
+_SAFE_5 = {"top": 0.05, "bottom": 0.05, "left": 0.05, "right": 0.05}
+_NO_SAFE = {"top": 0.0, "bottom": 0.0, "left": 0.0, "right": 0.0}
+
+# caption defaults: size is a fraction of the frame height (0.0833 = the 24 that every
+# vertical job in this repo has used since 1.2), position/box/outline/animate as the
+# caption.py flags of the same name.
+_CAP_VERTICAL = {"size": 0.0833, "position": "bottom", "box": False, "outline": 2, "animate": "pop"}
+_CAP_WIDE = {"size": 0.0694, "position": "bottom", "box": False, "outline": 2, "animate": "none"}
+
+PLATFORMS: Dict[str, Dict[str, Any]] = {
+    "tiktok": {
+        "title": "TikTok",
+        "frame": {"w": 1080, "h": 1920, "aspect": "9:16"},
+        "fps": 30,
+        "spec": {"max_duration": 600, "aspects": ["9:16", "1:1"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": True},
+        # the description/caption block along the bottom, the like/comment/share column on the
+        # right, the status bar and the "Following | For You" tabs at the top
+        "safe": {"top": 0.10, "bottom": 0.22, "left": 0.05, "right": 0.14},
+        "caption": _CAP_VERTICAL,
+        "preset": "tiktok", "check": "tiktok",
+    },
+    "reels": {
+        "title": "Instagram Reels",
+        "frame": {"w": 1080, "h": 1920, "aspect": "9:16"},
+        "fps": 30,
+        "spec": {"max_duration": 90, "aspects": ["9:16", "4:5", "1:1"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": True},
+        "safe": {"top": 0.08, "bottom": 0.20, "left": 0.05, "right": 0.12},
+        "caption": _CAP_VERTICAL,
+        "preset": "reels", "check": "reels",
+    },
+    "shorts": {
+        "title": "YouTube Shorts",
+        "frame": {"w": 1080, "h": 1920, "aspect": "9:16"},
+        "fps": 30,
+        "spec": {"max_duration": 180, "aspects": ["9:16", "1:1"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 256 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+        "safe": {"top": 0.06, "bottom": 0.18, "left": 0.05, "right": 0.12},
+        "caption": _CAP_VERTICAL,
+        "preset": "shorts", "check": "shorts",
+    },
+    "youtube": {
+        "title": "YouTube",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": {"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "youtube", "check": "youtube",
+    },
+    "youtube-hdr": {
+        "title": "YouTube (HDR10)",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": dict({"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60,
+                      "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3,
+                      "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False}),
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "youtube-hdr", "check": "youtube",
+    },
+    "youtube-av1": {
+        "title": "YouTube (AV1)",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": dict({"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60,
+                      "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3,
+                      "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False}),
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "youtube-av1", "check": "youtube",
+    },
+    "x": {
+        "title": "X (Twitter)",
+        "frame": {"w": 1280, "h": 720, "aspect": "16:9"},
+        "fps": 30,
+        "spec": {"max_duration": 140, "aspects": ["16:9", "1:1", "9:16"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264"], "max_bytes": 512 * 1024 ** 2,
+                 "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "x", "check": "x",
+    },
+    "linkedin": {
+        "title": "LinkedIn",
+        "frame": {"w": 1080, "h": 1080, "aspect": "1:1"},
+        "fps": 30,
+        "spec": {"max_duration": 600, "aspects": ["16:9", "1:1", "9:16", "4:5"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264"], "max_bytes": 5 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "linkedin", "check": "linkedin",
+    },
+    "facebook": {
+        "title": "Facebook",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": 30,
+        "spec": {"max_duration": 240 * 60, "aspects": ["16:9", "1:1", "9:16", "4:5"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "facebook", "check": "facebook",
+    },
+    "podcast": {
+        "title": "Podcast (audio)",
+        "frame": None,
+        "fps": None,
+        "spec": {"max_duration": None, "aspects": None, "min_height": 0, "fps_max": None,
+                 "codecs": None, "max_bytes": None,
+                 "lufs": -16, "lufs_tol": 1.0, "tp": -1.0, "sdr_only": False},
+        "safe": _NO_SAFE,
+        "caption": _CAP_WIDE,
+        "preset": None, "check": "podcast",
+    },
+    # Not destinations an app owns, but compliance targets check.py has always had.
+    "broadcast": {
+        "title": "Broadcast (EBU R128)",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": {"max_duration": None, "aspects": ["16:9"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["prores", "dnxhd", "h264", "hevc", "mpeg2video"], "max_bytes": None,
+                 "lufs": -23, "lufs_tol": 1.0, "tp": -1.0, "sdr_only": False},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "prores", "check": "broadcast",
+    },
+    "custom": {
+        "title": "Custom",
+        "frame": None,
+        "fps": None,
+        "spec": {"max_duration": None, "aspects": None, "min_height": 0, "fps_max": None,
+                 "codecs": None, "max_bytes": None,
+                 "lufs": None, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+        "safe": _NO_SAFE,
+        "caption": _CAP_WIDE,
+        "preset": None, "check": "custom",
+    },
+}
+
+# The canonical destination names.
+PLATFORM_NAMES: List[str] = sorted(PLATFORMS)
+# The spellings people actually write for those destinations. resolve() maps them onto the
+# canonical name, and every tool's --platform/--safe/--preset accepts both, so
+# `--platform youtube-shorts` and `--platform shorts` are the same request everywhere.
+ALIASES: Dict[str, str] = {"youtube-shorts": "shorts", "yt-shorts": "shorts", "yt": "youtube",
+                           "instagram": "reels", "ig": "reels", "twitter": "x", "fb": "facebook"}
+# One vocabulary for the word "platform": check.py, caption.py, graphics.py and look.py all
+# offer this list (review 12 found three different ones). It is the compliance targets -- the
+# destinations a delivery is checked against -- plus every alias; youtube-hdr and youtube-av1
+# are export presets of the youtube target, not separate destinations, so they are not in it.
+PLATFORM_CHOICES: List[str] = sorted({n for n in PLATFORMS if PLATFORMS[n]["check"] == n} | set(ALIASES))
+
+
+def has_frame(name: str) -> bool:
+    """True when this destination has a frame, and therefore a safe zone to place text inside."""
+    return bool(PLATFORMS.get(resolve(name) or "", {}).get("frame"))
+
+
+def spec_of(name: str) -> Dict[str, Any]:
+    """check.py's compliance row values for a destination."""
+    return dict(PLATFORMS[name]["spec"])
+
+
+def safe_of(name: str) -> Dict[str, float]:
+    return dict(PLATFORMS[name]["safe"])
+
+
+def loudness_of(name: str) -> Dict[str, float]:
+    s = PLATFORMS[name]["spec"]
+    return {"lufs": s["lufs"], "lufs_tol": s["lufs_tol"], "tp": s["tp"]}
+
+
+def safe_margins_px(name: str, width: int, height: int) -> Dict[str, int]:
+    """The safe zone in pixels for a frame of this size, as whole pixels per edge."""
+    s = PLATFORMS[name]["safe"]
+    return {"top": int(round(s["top"] * height)), "bottom": int(round(s["bottom"] * height)),
+            "left": int(round(s["left"] * width)), "right": int(round(s["right"] * width))}
+
+
+def caption_defaults(name: str) -> Dict[str, Any]:
+    """caption.py flag values for this destination: --size/--margin in ASS units."""
+    cap = dict(PLATFORMS[name]["caption"])
+    safe = PLATFORMS[name]["safe"]
+    edge = safe["top"] if cap["position"].startswith("top") else safe["bottom"]
+    cap["size"] = ass_units(cap["size"])
+    cap["margin"] = ass_units(edge)
+    return cap
+
+
+def resolve(name: Optional[str]) -> Optional[str]:
+    """Accept the spellings people write for a destination ('youtube-shorts', 'ig')."""
+    if not name:
+        return None
+    key = str(name).strip().lower()
+    return ALIASES.get(key, key)

package/scripts/caption.py

@@ -40,6 +40,7 @@ import unicodedata
 from pathlib import Path
 from typing import List, Optional, Tuple
 
+from _platforms import PLATFORMS, PLATFORM_CHOICES, ass_units, resolve as resolve_platform
 from _common import STATE, brand_states_font, char_script, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
@@ -759,7 +760,10 @@ def main() -> int:
     sty.add_argument("--shadow", type=float, default=0.0, help="shadow depth (default 0)")
     sty.add_argument("--bold", action="store_true")
     sty.add_argument("--position", choices=sorted(ALIGN), default=None, help="on-screen placement (default bottom)")
-    sty.add_argument("--margin", type=int, default=30, help="vertical margin from the edge (default 30)")
+    sty.add_argument("--margin", type=int, default=None, help="vertical margin from the edge in ASS units (default 30, or the --platform safe zone)")
+    sty.add_argument("--platform", choices=PLATFORM_CHOICES, default=None,
+                     help="keep the captions out of this destination's UI: the margin becomes the platform's safe "
+                          "zone (TikTok's description bar, the Reels/Shorts chrome). An explicit --margin/--position wins")
     sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")
     sty.add_argument("--max-lines", type=int, default=2, help="most lines one cue may occupy; a longer cue is split into consecutive cues (default 2)")
     sty.add_argument("--min-duration", type=float, default=1.0, help="shortest time a cue stays on screen in seconds, never past the next cue (default 1.0)")
@@ -792,6 +796,18 @@ def main() -> int:
     args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))
     args.outline = args.outline if args.outline is not None else (float(bcap.get("outline", 2)) if args.brand else 2.0)
     args.position = args.position or (bcap.get("position", "bottom") if args.brand else "bottom")
+    # --platform: the margin is the fraction of the frame that platform's own UI covers
+    # (scripts/_platforms.py). An explicit --margin is the more specific statement and wins;
+    # without either, the historical default 30 is unchanged.
+    # every tool resolves the spellings people write ('youtube-shorts' is 'shorts') in one place
+    args.platform = resolve_platform(args.platform)
+    if args.margin is None and args.platform and PLATFORMS[args.platform].get("frame"):
+        edge = PLATFORMS[args.platform]["safe"]["top" if args.position.startswith("top") else "bottom"]
+        args.margin = ass_units(edge)
+        info(f"--platform {args.platform}: caption margin {args.margin} ASS units ({edge * 100:.0f}% of the frame height, "
+             f"clear of the app's own UI)")
+    if args.margin is None:
+        args.margin = 30
     # a brand's caption.animate is a burn-in default; over --mode mux (soft subtitles) it used
     # to be applied anyway and then refused as "animation is burn only" -- ignore it there
     args.animate = args.animate or (bcap.get("animate", "none") if args.brand and args.mode != "mux" else "none")