ffmpeg-skill 1.12.0 → 1.14.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.12.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.14.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.12.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.12.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.12.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.12.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.12.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.14.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.14.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.14.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.14.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.14.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.12.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.12.0", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.14.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.14.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.12.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.14.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>`,
@@ -354,6 +394,21 @@ runs a shell, evaluates strings, or executes anything other than the named scrip
 
 ## JSON output
 
+Per-tool keys added in 1.13: `audio` (`audio.py`) reports the mix it built — the
+`--voice` level, `stereo_widen`, whether an `--effects` bed was mixed, and with
+`--music` the `music_volume` plus a `duck` object naming the threshold (dB and
+linear), ratio, attack and release actually used, or `null` when `--duck` was not
+given. `loudness.py` reports `measured` (the input's loudnorm measurement,
+including `input_lra`) and `targets` (the requested lufs / tp / lra).
+`check.py --platform podcast` adds two informational rows to `checks`,
+`channels` and `chapters`.
+
+The MCP `audio` tool publishes `voice` as `{"type": "string", "enum": ["light",
+"medium", "strong"]}`. A client that still sends the 1.12 boolean `{"voice":
+true}` keeps working: `true` emits the bare `--voice`, which is `medium` — the
+chain the flag has always produced. Send the string when you can; the boolean
+is accepted at runtime and means `medium`.
+
 Success (`exit 0`): one document matching `output_schema`, always with
 `status: "completed"`, `output`, `dry_run`, `commands`, and `probe` of the output when a
 file was written. `probe` prints its measurement document directly.
@@ -468,6 +523,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.12.0",
+  "version": "1.14.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

@@ -74,6 +74,14 @@ clip measured at -40 LUFS or below is room tone, wind or nothing; raising it
 25 dB raises the noise, not the content. Leave the level, say so, and offer music
 or narration.
 
+Do not add a speech gate in front of the measurement either: `loudnorm`'s EBU
+R128 integrated loudness already applies the −70 LUFS absolute and −10 LU
+relative gates, which drop the same quiet blocks a `silencedetect` pass would.
+A speech-span gate was measured against the whole-file measurement on every
+fixture in the repo, including one that is half digital silence, and moved the
+result by at most 0.6 LU — inside `check.py`'s own ±1 LU tolerance — for the
+cost of a second full decode. That is why `loudness.py` has no speech-gate flag.
+
 ## Text and framing
 
 ### Captions, fonts and text order
@@ -150,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
 ```
@@ -404,8 +411,25 @@ so the rendered file meets the platform's loudness without a separate pass. Sinc
 1.9.0 it is on by default when the preset is a platform (`youtube|youtube4k|reels|x`)
 and the project has no `loudness` stage; `"normalize": false` opts out.
 
+`"audio": {"stems": {"dialogue": -2, "music": -18, "effects": -24}}` names one
+level per element of the mix: `dialogue` is the main track's gain, `music` the
+bed's level, `effects` the level of the third file `"audio": {"effects":
+"sfx.wav"}` adds (never ducked). Each maps to the flag of the same meaning
+(`--gain`, `--music-volume`, `--effects-volume`); an explicit flag next to a
+stem wins, and a stems level with no file to apply it to (`effects` without
+`"effects"`, `music` without `"music"`) is refused, `kind: input`.
+`"audio": {"voice": "light"|"medium"|"strong"}` picks the voice strength
+(`true` is `medium`).
+
+`"chapters"` is a chapters file path, or an inline list of `{"at": TIME,
+"title": STR}`; it runs `metadata.py` on the delivered file as the last stage
+before `check`, so the markers are in the file that ships (streams copied). The
+entries and the file path are validated before the first stage runs, and the
+stage plans its `metadata.py` command under `--dry-run`/`--plan` like every
+other stage, so the plan lists `chapters` and the run does the same work.
+
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
-captions → graphics → overlays → audio → loudness → export → check. Keys mirror the
+captions → graphics → overlays → audio → loudness → export → chapters → check. Keys mirror the
 CLI flags of each script (see the docstring); a key `render.py` does not read -- at
 the top level or in any stage/clip object -- is refused (`kind: input`) naming the
 key and the nearest valid one, never silently ignored. Use it whenever an edit has
@@ -413,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]
@@ -429,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
@@ -437,6 +511,15 @@ step before reporting a deliverable; fix FAILs, mention WARNs. Without
 `--platform` the youtube spec is assumed and the judgement rows (duration,
 aspect, fps, resolution, loudness, true peak) come back as WARN with a `notes`
 line, not FAIL: name the platform when the file is a delivery for it.
+`--platform podcast` adds two informational rows: `channels` (PASS for mono or
+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. 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
 ```
@@ -464,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`.
@@ -477,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",
@@ -533,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)
 ```
@@ -613,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
@@ -684,13 +785,42 @@ first on HDR or Log sources.
 
 ### audio.py — clean-up, music, ducking, layout
 ```
-audio.py INPUT [--voice | --denoise [--denoise-strength 25]] [--gain dB]
-         [--music FILE [--music-volume -14] [--duck [--duck-amount 12]] [--music-loop]]
+audio.py INPUT [--voice [light|medium|strong] | --denoise [--denoise-strength 25]] [--gain dB]
+         [--music FILE [--music-volume -14] [--duck [--duck-amount 12] [--duck-threshold -26.02]
+          [--duck-attack 20] [--duck-release 400]] [--music-loop]]
+         [--effects FILE [--effects-volume -14]] [--stereo-widen 0..1]
          [--fade-in S] [--fade-out S] [--stereo | --mono | --downmix] [--replace FILE] [-o OUT]
 ```
-`--voice` = highpass 80 Hz → de-esser → FFT denoise → gentle compressor, the
-standard talking-head chain. `--duck` uses a sidechain compressor keyed by the
-speech so music dips under dialogue and swells in pauses. `--downmix` uses the
+`--voice` takes a strength; a bare `--voice` is `medium`, the chain it has always
+produced. The exact filter chains:
+
+| level | chain |
+| --- | --- |
+| `light` | `highpass=f=80,acompressor=threshold=-18dB:ratio=2:attack=5:release=80:makeup=1` |
+| `medium` | `highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2` |
+| `strong` | the `medium` chain, then `deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled` |
+
+`light` for a good room (rumble and level only, noise floor and sibilance left
+alone), `medium` for a normal talking head, `strong` for phone/laptop audio.
+`strong` is the only level with a limiter, so it is the only one whose peaks
+stop at −1 dBFS: `medium` (the default, and the chain a bare `--voice` gets) can
+clip a hot source, since its make-up gain has nothing above it — normalise
+afterwards with `loudness.py`, or use `strong`, which measures quieter and safer.
+`--duck` uses a sidechain compressor keyed by the speech so music dips under
+dialogue and swells in pauses:
+`sidechaincompress=threshold=0.05:ratio=<amount/3, min 2>:attack=20:release=400:makeup=1`
+by default. `--duck-threshold DB` (default −26.02 dBFS, i.e. the 0.05 linear),
+`--duck-attack MS` (20) and `--duck-release MS` (400) move each one; a lower
+threshold ducks on quieter speech, a shorter release brings the bed back faster.
+`--json`'s `audio` block reports the settings the run actually used.
+`--effects FILE` mixes a third track (sound effects, atmos) at
+`--effects-volume` and is never ducked — effects are cut to the picture.
+`--stereo-widen 0..1` widens the stereo image (`extrastereo=m=1+2*amount`) and
+needs a real stereo source: it scales the side signal (L−R), so a mono track
+duplicated to two channels has nothing to scale. A 1-channel input is refused
+(`kind: input`) — `--stereo` duplicates it but does not widen it — and more than
+two channels are refused unless `--downmix` is given too, in which case the
+widening runs on the stereo fold-down. `--downmix` uses the
 ITU centre/LFE weights for 5.1/7.1 → stereo. `--mono` averages a stereo pair,
 leaves a 1-channel input untouched and downmixes >2 channels through
 swresample. Video is always stream-copied, and so is a subtitle/data track
@@ -701,6 +831,12 @@ Run `loudness.py` after this for final levels.
 ```
 loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
 ```
+`--lra N` is the loudness-range target in LU (default 11): lower it to squeeze a
+wide-dynamic mix into a phone speaker, raise it to leave a film mix alone.
+`--json` reports the measured range on both sides — `measured.input_lra` for the
+input, `result.input_lra` for the written file, with `targets` echoing the
+requested lufs / tp / lra.
+
 Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
 the true-peak ceiling allows). Video and any subtitle/data track are
 stream-copied (`dropped_non_av_streams` reports a track the container refused); audio becomes AAC in
@@ -715,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`,
@@ -727,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],
@@ -157,9 +158,11 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "multicam": dict(role="execution", inputs=["reference camera", "other cameras / recorders"], outputs=["switched multicam video artifact"],
                      required=FF + [X264, AAC], optional=[HDR_X265],
                      video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
+    "audio": dict(role="execution", inputs=["video or audio asset", "music bed (--music) or replacement track (--replace)", "effects/atmos track (--effects)"], outputs=["artifact with the processed audio (video stream-copied, or dropped when -o has an audio extension)"],
                   required=FF, optional=[{"capability": "filter:afftdn", "when": "--denoise / --voice"}, {"capability": "filter:sidechaincompress", "when": "--duck"},
-                                        {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit"}, {"capability": "filter:agate", "when": "--gate"},
+                                        {"capability": "filter:acompressor", "when": "--compress / --voice"}, {"capability": "filter:alimiter", "when": "--limit / --voice strong"}, {"capability": "filter:agate", "when": "--gate"},
+                                        {"capability": "filter:deesser", "when": "--voice medium (the default) / --voice strong"},
+                                        {"capability": "filter:extrastereo", "when": "--stereo-widen"},
                                         {"capability": AAC, "when": "output extension isn't .mp3/.opus/.ogg/.flac (audio_codec_for()'s default)"}] + AUDIO_OUT,
                   video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "loudness": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["loudness measurement JSON (--measure-only)", "normalised artifact (video stream-copied)"],
@@ -185,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)"],
@@ -195,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"}],
@@ -411,7 +416,9 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"loudness": {"type": "object", "description": "platform presets with audio: the written file's lufs/tp against the platform's target_lufs/target_tp, ok true when inside the spec; normalized true when --normalize ran loudness.py on the file"},
                  "notes": {"type": "array", "items": {"type": "string"}}}
     elif name == "loudness":
-        extra = {"measured": {"type": "object", "description": "--measure-only prints the loudnorm measurement instead (input_i, input_tp, input_lra, input_thresh, target_offset)"}}
+        extra = {"measured": {"type": "object", "description": "the loudnorm measurement of the input (input_i, input_tp, input_lra, input_thresh, target_offset); with --measure-only it is the whole result"},
+                 "targets": {"type": "object", "description": "the requested lufs / tp / lra"},
+                 "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
@@ -426,7 +433,8 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
     elif name == "audio":
         extra = {"video": {"type": "boolean", "description": "true when the input's video stream was copied; false for an audio output extension (extraction)"},
                  "audio_stream": {"type": "integer", "description": "which input audio stream was processed (--audio-stream)"},
-                 "dynamics": {"type": "array", "items": {"enum": ["agate", "acompressor", "alimiter"]}, "description": "typed dynamics filters applied, in graph order"}}
+                 "dynamics": {"type": "array", "items": {"enum": ["agate", "acompressor", "alimiter"]}, "description": "typed dynamics filters applied, in graph order"},
+                 "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
     props = dict(base)
     props.update(extra)
     required = ["status", "output", "dry_run", "commands"]