ffmpeg-skill 1.13.0 → 1.15.0

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.13.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.15.0`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -88,19 +88,19 @@ spelling keeps working until 2.0.
 
 | What 2.0 removes | Since | Replacement | To be ready today |
 |---|---|---|---|
-| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.13.0 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
-| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.13.0 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
-| `json` and `progress` in the MCP `inputSchema` | 1.13.0 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
-| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.13.0 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
-| Overwriting an existing output with only a warning | 1.13.0 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |
+| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.15.0 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
+| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.15.0 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
+| `json` and `progress` in the MCP `inputSchema` | 1.15.0 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
+| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.15.0 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
+| Overwriting an existing output with only a warning | 1.15.0 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |
 
 ## Skill
 
 ```json
 {
   "contract_version": "1.0",
-  "deprecated": [{"what": "...", "since": "1.13.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.13.0", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.15.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.15.0", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -128,7 +128,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `output_schema` | what `--json` prints on stdout |
 | `supports_dry_run`, `dry_run` | whether `--dry-run` plans without running ffmpeg or writing files |
 | `supports_json` | whether `--json` exists |
-| `supports_json_brief` | whether `--json-brief` exists (1.13.0): the same success document with `probe` replaced by a compact `summary` (`duration_s`, `width`, `height`, `fps`, `vcodec`, `acodec`, `channels`, and `lufs` when the tool measured one), `commands` replaced by the number of commands run, and the per-step `verification` list dropped (its verdict stays in `verified`). Tool-specific keys are unchanged, `--json`'s own output is unchanged, and a failure prints the same failure document either way |
+| `supports_json_brief` | whether `--json-brief` exists (1.15.0): the same success document with `probe` replaced by a compact `summary` (`duration_s`, `width`, `height`, `fps`, `vcodec`, `acodec`, `channels`, and `lufs` when the tool measured one), `commands` replaced by the number of commands run, and the per-step `verification` list dropped (its verdict stays in `verified`). Tool-specific keys are unchanged, `--json`'s own output is unchanged, and a failure prints the same failure document either way |
 | `mutates_input` | always `false`: no tool overwrites its input |
 | `produces_artifact` | writes a file (media, PNG, HTML, EDL) |
 | `verification` | `{required, tools}`: which tools to run on the output afterwards |
@@ -264,6 +264,46 @@ downstream analysis/preview, distinct from `export.py`'s delivery
 presets) resolves to `proxy` - itself a mechanical resize + re-encode
 with no opinion on which asset should be proxied or what for.
 
+## Delivery table and templates (1.14)
+
+`scripts/_platforms.py` is the one table every delivery tool reads. Per destination
+(`tiktok`, `reels`, `shorts`, `youtube`, `youtube-hdr`, `youtube-av1`, `x`, `linkedin`,
+`facebook`, `podcast`, plus the `broadcast` / `custom` compliance targets):
+
+| field | meaning |
+|---|---|
+| `frame` | `{w, h, aspect}` the destination is delivered at, or `null` for an audio-only one |
+| `fps` | the frame rate a delivery is conformed to (`null`: leave the source's alone) |
+| `spec` | `check.py`'s row values: `max_duration`, `aspects`, `min_height`, `fps_max`, `codecs`, `max_bytes`, `lufs`, `lufs_tol`, `tp`, `sdr_only` |
+| `safe` | the fraction of the frame the app's own UI covers, per edge (`top`, `bottom`, `left`, `right`) |
+| `caption` | caption defaults a template uses: `size` (fraction of frame height), `position`, `box`, `outline`, `animate` |
+| `preset` | the `export.py` preset that writes this destination |
+| `check` | the `check.py` platform a delivery is verified against |
+
+It is an internal module (leading underscore), not a tool: the public tool count is unchanged.
+`check.py`'s `SPECS`, `export.py`'s `PRESETS` (each platform preset's frame and duration cap)
+and `export.py`'s `PLATFORM_OF` are all built from it, so the loudness `export.py --normalize`
+targets, the frame it writes, the cap it trims at and the spec `check.py` enforces are one
+value. Two presets deliberately differ from their destination's row and say so in the code:
+`youtube4k` delivers to YouTube at 2160p, and no `youtube*` preset trims at YouTube's 12-hour
+limit (`check.py` reports it instead). `_platforms.resolve()` is the one alias map -- 
+`youtube-shorts`/`yt-shorts` = `shorts`, `yt` = `youtube`, `instagram`/`ig` = `reels`,
+`twitter` = `x`, `fb` = `facebook` -- and `check.py --platform`, `export.py --preset`,
+`caption.py`/`graphics.py`/`overlay.py --platform`, `look.py --safe` and
+`render.py --template` all accept those spellings.
+
+New in the same release, all additive: `export.py --preset tiktok|shorts|linkedin|facebook`
+(real presets, not aliases of `reels`/`youtube`), `--preset youtube-hdr` (HEVC Main10 keeping
+the source's HDR tags; `kind: input` on an SDR source) and `--preset youtube-av1`
+(`kind: missing_tool` when the build has neither SVT-AV1 nor libaom); `caption.py --platform`
+and `graphics.py --platform` / `--margin` and `overlay.py --platform` (margins from the safe
+zone, an explicit `--margin`/`--position` wins); `look.py --safe NAME`; `fit.py --fit blur`; `report.py --pack`;
+`graphics.py --template sticker|hook|meme`; and `render.py --template NAME INPUT`
+(`--cues/--srt/--logo/--title/--brand/--chapters/--fit/-o/--write-project/--list-templates`),
+which fills a `templates/<name>.json` project shipped with the skill. `--template all` or a
+comma-separated list renders every named destination and writes a `<stem>_pack.md` table.
+A project may now carry `"template"` (the name it was filled from) and `"frame": {"fit": ...}`.
+
 ## Capabilities
 
 Names: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,
@@ -321,7 +361,8 @@ typeface the caller didn't ask for.
 
 Since 1.12 the same field also carries `scripts`: one entry per writing system the tools detect,
 `{"ja": {"status": "available"|"missing"|"unknown", "file": "/path/to/font.ttc"|null}, "zh": ...,
-"ko": ..., "ar": ..., "he": ..., "hi": ..., "th": ..., "ru": ..., "el": ...}`. It answers "which
+"ko": ..., "ar": ..., "he": ..., "hi": ..., "bn": ..., "ta": ..., "th": ..., "lo": ..., "ru": ...,
+"el": ...}` (`bn`, `ta` and `lo` were added in 1.15). It answers "which
 languages can this machine actually render", which no filter or encoder capability asks:
 `available` means `fc-list :lang=<code>` (Linux/macOS) or a known system font file (Windows) covers
 the script, `missing` means fontconfig knows none, `unknown` means there is no working fontconfig to
@@ -338,6 +379,25 @@ line to one screen width; a longer explanation, and the per-script files, are `-
 `--lang`/`--language` (caption, graphics) is the hint that says whether Han-only text is Chinese,
 Japanese or Korean.
 
+Since 1.15 `fonts` also carries `emoji`: `{"mode": "color"|"png"|"mono"|"none", "color_font": "Noto
+Color Emoji"|null, "color_font_file": "..."|null, "libass_color": true|false|null, "assets":
+"/path"|null, "detail": "...", "fix": "..."}`. `libass_color` comes from a **render probe** — one
+64x64 frame with an emoji cue through `subtitles=`, chroma-tested — because an installed colour
+emoji family proves nothing: Noto Color Emoji installs cleanly on builds whose libass still draws a
+monochrome outline. `null` means the probe was not run: `contract --json --static` (and every other
+static/JSON-only path) skips it, exactly as it skips the rest of the environment detection. `mode`
+is `color` when the probe says colour, else `png` when an emoji assets directory resolves, else
+`mono` when some installed face has a glyph, else `none`. Informational like the rest of `fonts`:
+it never moves `ok` or any tool's `usable`.
+
+`caption.py`, `graphics.py` and `overlay.py` gained `--emoji auto|color|png|mono|none`,
+`--emoji-assets DIR`, `--emoji-scale FLOAT` and `--emoji-max N` in 1.15; `graphics.py` also gained
+`--text-render auto|ass|drawtext` and `--write-ass PATH`. New success keys: `emoji`
+(`{"mode", "count", "clusters", "assets", "missing", "overlays"}`) on `caption.py` and
+`graphics.py`, and `text_renderer` (`"ass"`|`"drawtext"`), `script` and `ass` (the generated file,
+when one was written) on `graphics.py`. `--json-brief` carries `emoji.mode` and `emoji.count` only.
+All additive: `contract_version` stays 1.0.
+
 ## Invocation
 
 Structured arguments are the canonical way to call a tool, on the CLI or through MCP.
@@ -483,6 +543,8 @@ ffmpeg-skill contains no agent-specific code.
 
 ## Where things live
 
+- `scripts/_platforms.py`: the delivery table (destinations, specs, safe zones) read by check/export/render/caption/graphics/look
+- `templates/*.json`: the shipped delivery templates `render.py --template NAME` fills
 - `scripts/_contract.py`: the generator (`--json`, `--static`, `doctor`)
 - `bin/install.js`: `ffmpeg-skill contract` and `ffmpeg-skill doctor`
 - `tests/test_contract.py`: schema, consistency (scripts = MCP = installer), MCP inputSchema derived from the contract (equality, determinism, drift, round trips), dry-run, JSON shapes, verification policy, real-media run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",
@@ -29,6 +29,7 @@
   "files": [
     "bin/",
     "scripts/",
+    "templates/",
     "mcp/",
     "references/scripts.md",
     "references/devices.md",
@@ -42,7 +43,8 @@
   "scripts": {
     "test": "python3 tests/test_all.py && python3 tests/test_contract.py",
     "release-check": "bash tests/release_check.sh",
-    "demo": "bash examples/make_demo.sh",
+    "demo": "python3 demos/build.py",
+    "demo:pipeline": "bash examples/make_demo.sh",
     "contract": "python3 scripts/_contract.py --json",
     "doctor": "python3 scripts/_contract.py doctor"
   },

package/references/gotchas.md

@@ -109,7 +109,7 @@ libass and drawtext draw an empty box per character they have no glyph for, and
 ffmpeg still exits 0 — a video full of tofu is the classic "it worked" failure.
 Since 1.12 `caption.py`, `graphics.py` and `overlay.py --text` detect the script
 of the text they are about to draw (Japanese, Chinese, Korean, Arabic, Hebrew,
-Devanagari, Thai, Cyrillic, Greek) and resolve a font file that covers it,
+Devanagari, Bengali, Tamil, Thai, Lao, Cyrillic, Greek) and resolve a font file that covers it,
 printing one line — `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`.
 **No font for the script is a failed job** (`kind: input`), not a warning.
 
@@ -145,6 +145,75 @@ printing one line — `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`.
   letterforms. Nothing in the tools checks this, so on an unknown machine a
   caption is the safe place for Arabic/Hebrew.
 
+**Shaping is a second problem, and it is not the same one.** A font that covers
+the script still has to be *shaped*: Devanagari matras are reordered, Thai and
+Lao marks re-cluster. drawtext does bidi and Arabic joining correctly on a build
+compiled with fribidi (so Arabic and Hebrew are already right today), but it
+never reorders or re-clusters, because it does not use harfbuzz on any build.
+libass does. Since 1.15 `graphics.py` therefore renders a shaping script
+(`hi bn ta te kn ml gu pa si th lo km my`) through libass automatically — one
+generated `<output>_gfx.ass` next to the file, `text_renderer: "ass"` in the
+JSON — and `--text-render auto|ass|drawtext` overrides it; `--text-render
+drawtext` with such a script is a refusal, not a wrong frame. Latin, CJK and
+Arabic output is unchanged. `overlay.py --text` has no ASS route yet and refuses
+a shaping script, naming `caption.py`/`graphics.py`.
+
+### Emoji
+Colour emoji need **either** a libass that can draw colour glyphs **or** a
+directory of PNGs — and on most builds only the second one exists.
+
+- **An installed colour emoji font proves nothing.** Noto Color Emoji installs
+  cleanly on Ubuntu and libass on the distro ffmpeg still renders a monochrome
+  outline (`Glyph 0x1F389 not found, broken font? Trying all charmaps`). The
+  only honest test is a render, which is what `doctor` runs:
+  `doctor --json` → `.fonts.emoji` (`mode`: `color` / `png` / `mono` / `none`,
+  plus `libass_color` from that render). `contract --json --static` is the way
+  to get the contract without running it; `doctor` itself always probes.
+- **drawtext cannot load an emoji font at all.** Not a degraded render: a
+  CBDT/sbix face fails filter initialisation outright (`Could not set font size
+  to 48 pixels: invalid library handle`, and at the font's own strike
+  `Monocromatic (1bpp) fonts are not supported.`) and no file is written. That
+  is why the colour route is a PNG overlay, never a drawtext font.
+- **PNGs**: `--emoji-assets DIR`, a directory of files named by code point in
+  the Twemoji/Noto convention — lowercase hex joined by `-`: `1f389.png`,
+  `1f1ef-1f1f5.png`, `1f469-200d-1f4bb.png`. Twemoji's `assets/72x72`
+  (CC-BY 4.0) and Noto Emoji's `png/128` (OFL/Apache-2.0) are the two people
+  already have. **The skill never downloads anything**: a missing directory is
+  `kind: input`, never a silent fetch. The same directory can come from
+  `brand.json` (`styles.caption.emoji_assets`) or `FFMPEG_SKILL_EMOJI_ASSETS`.
+- **Mixed lines are the normal case.** The text stays in the ASS with an
+  invisible placeholder reserving exactly the emoji's box, and the PNG is
+  composited on top after the `ass=` filter — libass keeps the shaping and the
+  karaoke, including inside a `\kf` run (the placeholder is its own
+  zero-duration segment).
+- **What counts as an emoji.** A cluster only starts at an emoji *base*.
+  U+200D ZWJ and U+200C ZWNJ are ordinary Indic/Persian orthography (`क्‍ष` is
+  ka + virama + ZWJ + ssa) and are glue only *between* two emoji; a VS16 or a
+  skin-tone modifier after a plain letter is not an emoji either. U+FE0E
+  (VS15) asks for the character, so `❤︎` is text and `❤️` is an emoji.
+- **Placement tolerance.** The position comes from the same averaged em table
+  the wrap uses, so an emoji at the start or end of a line is exact and one in
+  the middle of a Latin line drifts by the accumulated rounding of the
+  characters before it — **measured at 17 px, 0.28 em, about 3 % of the line
+  width** on a 24 px caption over a 1280-wide frame, always landing inside the
+  reserved gap rather than on a glyph. It never leaves the safe area. An RTL
+  line (Arabic, Hebrew) is laid out right-to-left, so the position is measured
+  from the rendered end of the line, not the logical prefix.
+- **Degraded paths are honest, not silent.** `mode: mono` means libass draws
+  whatever glyph the text font has (it has a fallback chain), exits 0, and says
+  so in a `warning:` line and in `notes` — so a `graphics.py` run that would
+  otherwise use drawtext, which loads one font file and has **no** fallback
+  chain, is routed to libass rather than reporting a monochrome glyph it would
+  actually draw as an empty box; a run pinned to `--text-render drawtext`
+  degrades to `none` and says so. `mode: none` strips the cluster from the drawn
+  text (a missing decoration must not fail a delivery) but refuses a
+  `graphics.py` template whose text is *only* emoji — that frame would be blank.
+  `--emoji-max` (default 60) caps the overlay count; `--emoji-max 0` means none.
+- **`--animate` moves the PNG too.** The overlay gets a matching alpha fade, so
+  the emoji arrives and leaves with the line instead of popping in.
+- `overlay.py --text` has no PNG route: `--emoji png|color` there names
+  `caption.py`/`graphics.py` instead.
+
 ### Reframing, fps and duration
 `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot
 loses people at the edges. Check the sheet; pad (bars), `--crop-x`/`--crop-y`
@@ -158,6 +227,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,18 +547,50 @@ 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]
+            [--text-render auto|ass|drawtext] [--write-ass OUT.ass]
+            [--emoji auto|color|png|mono|none] [--emoji-assets DIR] [--emoji-scale 1.0] [--emoji-max 60] [-o OUT]
 ```
 Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
 the frame's short side; colours, font and safe margin come from `--brand`.
 Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.
 Non-Latin `--name`/`--title`/`--subtitle` text picks a font file by script the
 same way `caption.py` does (`--lang XX` disambiguates Han-only text; no font for
-the script fails the job). RTL shaping in drawtext depends on the ffmpeg build
-(`--enable-libfribidi`/`--enable-libharfbuzz` shape it correctly, a build without
-them does not); `caption.py` always shapes, because it renders through libass:
-`references/gotchas.md#fonts-by-script`.
+the script fails the job). Arabic and Hebrew are already correct through drawtext
+on a build with `--enable-libfribidi` (bidi + joining). What drawtext cannot do on
+any build is reorder and re-cluster — Devanagari matras, Thai/Lao mark stacking —
+because it does not use harfbuzz. Since 1.15 `--text-render auto` (the default)
+therefore routes those scripts through libass: the template's geometry is written
+as a generated `<output>_gfx.ass` (`--write-ass PATH` names it) and burned with
+`ass=`, reported as `text_renderer: "ass"` with `script` and `ass` in the JSON.
+Latin/CJK/Arabic frames are pixel-identical to 1.14 (the drawtext command
+line is not: since 1.15 every drawn label is passed as `textfile=<tmp>:expansion=none`
+rather than `text=`, so a `--dry-run` compared against 1.14 differs by design). `--text-render ass` forces the
+route; `--text-render drawtext` with a shaping script is refused by name rather
+than rendering a wrong frame. See `references/gotchas.md#fonts-by-script`.
+`--emoji*` works as on `caption.py` below; a template whose text is *only* emoji
+and that this machine can draw none of is `kind: input`, because that frame would
+be blank. `--emoji none` strips the clusters from the drawn text, and a job whose
+emoji would fall to `mode: mono` is routed through libass (which has a font
+fallback chain) instead of drawtext (which does not, and would draw an empty box).
+
+Every drawn label goes to drawtext as `textfile=<path>:expansion=none`. The file
+is UTF-8, mode 0600, in a private per-run temp directory created with
+`tempfile.mkdtemp()`, written only when the command that names it actually runs
+(so `--dry-run` and the ASS route write nothing) and removed when the process
+ends. A plan printed by `--dry-run` therefore names a path that does not exist.
+
+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
@@ -555,9 +648,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)
 ```
@@ -566,7 +663,8 @@ caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
            [--max-lines N] [--min-duration S]
            [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
            [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N]
-           [--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass] [-o OUT]
+           [--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass]
+           [--emoji auto|color|png|mono|none] [--emoji-assets DIR] [--emoji-scale 1.0] [--emoji-max 60] [-o OUT]
 caption.py --text CUES.txt --write-srt OUT.srt        # generate the SRT only
 ```
 Text cue format, one per line: `0:00-0:03 Hello`, `00:00:03.500 --> 00:00:06 Two | lines`,
@@ -580,7 +678,18 @@ word from `--color` to `--highlight-color` across the cue; `--karaoke-timing
 energy` (default) follows the speech loudness in the audio, `even` splits the
 cue equally (word timing is derived, not transcribed). The ASS is kept next to the
 user can hand-tune timings and re-run with `--ass`.
-Readable by default (1.12): every cue is wrapped to the safe area (90 % of the
+Emoji (1.15): `--emoji-assets DIR` is a directory of PNGs named by code point
+(`1f389.png`, `1f1ef-1f1f5.png`, `1f469-200d-1f4bb.png` — the Twemoji/Noto
+convention), also read from `brand.json` `styles.caption.emoji_assets` and
+`FFMPEG_SKILL_EMOJI_ASSETS`. With one, the cue text keeps its place in the ASS
+with an invisible placeholder reserving the emoji's box and each PNG is
+composited on top (`--emoji-scale` sizes the box, `--emoji-max` caps the count).
+Without one the run still succeeds and says `emoji: {"mode": "mono"}` plus a
+warning; `--emoji none` strips them; `--emoji color` insists on a colour-capable
+libass and refuses otherwise. Nothing is ever downloaded. What this machine can
+do: `doctor --json` → `.fonts.emoji`. Details: `references/gotchas.md#emoji`.
+
+Readable by default (1.12, rebalanced in 1.15): every cue is wrapped to the safe area (90 % of the
 frame width) at the chosen `--size`, measured per script — CJK and Thai count a
 full em per character, Latin per character from a table read off DejaVu Sans (so
 an all-caps line measures as wide as it draws), Cyrillic/Greek about 0.55,
@@ -634,9 +743,13 @@ stream selection would have picked.
 ### overlay.py — logo, image, title, video picture-in-picture, chroma key
 ```
 overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
+                  [--emoji auto|mono|none] [--emoji-assets DIR]
                   | --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
@@ -646,6 +759,14 @@ input's audio is kept, the PiP layer's own audio is dropped. `--chromakey`
 `--fade S` fades the overlay in at `--start` (or 0); the fade-out happens
 only at `--end`, so a logo with no `--end` stays to the last frame.
 
+Since 1.15 the drawn text goes to drawtext in a **file** (`textfile=`,
+`expansion=none`), so `'` and `%` survive verbatim — `--text "it's 100% done"`
+used to lose both. `overlay.py` still draws through drawtext, which cannot shape
+Devanagari/Thai-class scripts and cannot load a colour emoji font: a shaping
+script is refused by name pointing at `caption.py`/`graphics.py`, and
+`--emoji png|color` is refused the same way (`--emoji mono`, the default here,
+draws whatever glyph the text font has; `--emoji none` strips them).
+
 ### sync.py — offset detection, alignment, drift correction
 ```
 sync.py REFERENCE SECOND [--json] [--max-offset 30] [--analyze-seconds 120] [--fix-drift [--drift-window 60]]
@@ -772,7 +893,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 +906,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]