ffmpeg-skill 1.16.0 → 1.17.0

package/README.md

@@ -82,7 +82,7 @@ An agent that "knows FFmpeg" still guesses: it assumes a frame rate, picks a cod
 - **Structured tools, not shell strings.** Each operation is a script with typed arguments. Nothing runs through a shell; no filter graph is accepted from the caller.
 - **A contract the agent can read.** `contract --json` states, for every tool, what it takes, what it writes, which FFmpeg components it needs and how the result is verified. The MCP surface is derived from it.
 - **Verification after execution.** The result is probed, checked against the destination's spec and, when the picture changed, looked at as a contact sheet.
-- **Local first.** No cloud, no API keys, no Python dependencies. Optional local transcription is used when a whisper is installed, never required.
+- **Local first.** No cloud, no API keys, no Python dependencies. Optional local transcription is used when a whisper is installed, never required — by `caption.py --transcribe` and, since 1.17, by `silence.py --filler --transcribe`; both take a transcript you already have instead, and both refuse with the install lines rather than guessing.
 
 ## Quick start
 
@@ -190,16 +190,16 @@ These are the rules the skill file gives the agent and the code enforces.
 | Tool | What it does |
 |---|---|
 | `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, bit depth, HDR format incl. Dolby Vision (`hdr` for BT.2020 or PQ/HLG, `hdr_signal` for a real PQ/HLG/DV transfer only), colour space, rotation, every audio stream; `--analyze` flags Log footage |
-| `scenes.py` | Scene changes, audio peaks, highlight proposals (`--rank-by audio` loudest, or `--rank-by duration` longest — both proxies, not "best") and a per-scene sheet; cut list for `cut.py --segments` |
+| `scenes.py` | Scene changes, audio peaks, highlight proposals (`--rank-by audio` loudest, or `--rank-by duration` longest — both proxies, not "best") and a per-scene sheet; cut list for `cut.py --segments`; `--beats` measures the music's beat grid (tempo, beat times, confidence) |
 | `look.py` | Contact sheet, single frames, side-by-side comparison as PNG so the agent can see what it made; `--safe NAME` shades the zones a platform's own UI covers |
 
 **Editing**
 
 | Tool | What it does |
 |---|---|
-| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio; reports `precision` |
+| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio; reports `precision`; `--snap beats` moves the in/out points onto a measured beat, or refuses when there is no measurable pulse |
 | `join.py` | Concatenate clips with xfade transitions, normalising size, fps, sample rate and channel layout (the widest clip's, or `--channels`); audio-only inputs are joined as audio |
-| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list |
+| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list; `--filler` also removes filler words, but only where a speech engine timed them |
 | `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad, crop or `--fit blur`'s blurred, darkened fill, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps |
 | `crop.py` | Crop to an exact pixel rectangle (`--x --y --width --height`) — distinct from `fit.py --fit crop`, which crops to an aspect ratio it computes itself |
 | `cropdetect.py` | Measure existing black letterbox/pillarbox bars and report the `crop.py`-ready rectangle that removes them — analysis only, writes no file |
@@ -234,7 +234,7 @@ These are the rules the skill file gives the agent and the code enforces.
 
 | Tool | What it does |
 |---|---|
-| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; wraps to the safe area with a phrase-aware breaker (`--wrap phrase|measured`) and `--max-lines`/`--min-duration`/`--offset`; `--mode mux` takes a repeated `--srt file:lang` for several language-tagged, toggleable tracks in one file; picks a font by script for non-Latin text (`--lang`); animated and word-by-word karaoke timed to the speech energy or real word timings; optional local transcription |
+| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; wraps to the safe area with a phrase-aware breaker (`--wrap phrase|measured`) and `--max-lines`/`--min-duration`/`--offset`; `--mode mux` takes a repeated `--srt file:lang` for several language-tagged, toggleable tracks in one file; picks a font by script for non-Latin text (`--lang`); animated and word-by-word karaoke timed to the speech energy or real word timings; `--fit-size` shrinks the size until a cue fits `--max-lines` instead of splitting the sentence; optional local transcription |
 | `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--platform NAME` keeps them clear of that destination's UI; `--video` for picture-in-picture, `--chromakey` for green-screen compositing |
 | `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs, social stickers, opening hook cards and meme captions drawn by FFmpeg from a brand kit; `--platform NAME` keeps them inside that destination's safe zone; `--text-render` routes shaping scripts through libass and `--emoji-assets` composites colour emoji |
 | `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/gamma/white balance/lift-gain/levels/curves) |
@@ -252,8 +252,8 @@ These are the rules the skill file gives the agent and the code enforces.
 
 | Tool | What it does |
 |---|---|
-| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table) |
-| `batch.py` | Apply a step recipe or a project to a folder with a content-hash cache; `--watch` |
+| `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table) |
+| `batch.py` | Apply a step recipe or a project to a folder with a content-hash cache; `--watch`; `--jobs N` processes several files at once under one shared `--timeout` |
 | `multicam.py` | Align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list |
 | `verify.py` | Run the toolchain on real device files and report PASS / FAIL per step |
 
@@ -361,7 +361,11 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 - **Loudness targets.** −14 LUFS / −1 dBTP for YouTube and social platforms (the `loudness.py` default), `-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: `check.py file --platform podcast` measures both.
 - **Frame changes first, text second.** Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.
 - **Cropping 16:9 to 9:16 discards 70 % of the width.** `fit.py --fit crop` centres by default; pass `--crop-x`/`--crop-y` toward the subject, or pad with `--fit pad --pad-fill blur`. Look at the contact sheet before deciding.
-- **Phrase-aware caption breaking (1.16).** `caption.py`/`graphics.py --wrap phrase` (the default) never breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or punctuation pair on a line, prefers Japanese sentence ends and particles over a mid-word break, and never ends a line on an article or preposition. All four are penalties over break positions that already fit, so no line is widened and the line count never changes; `--wrap measured` restores 1.15's width-only wrap. The text itself is never rewritten or shortened.
+- **Phrase-aware caption breaking (1.16).** `caption.py`/`graphics.py --wrap phrase` (the default) never breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or punctuation pair on a line, prefers Japanese sentence ends and particles over a mid-word break, and never ends a line on an article or preposition. All four are penalties over break positions that already fit, so no line is widened and the line count never changes; `--wrap measured` restores 1.15's width-only wrap. The text itself is never rewritten or shortened. Since 1.16.1 a Thai run and a katakana word are never broken inside (Thai writes no space inside a phrase and there is no dictionary: the break goes where you put a space or `|`), and a line wider than the safe width is reported as `overlong` with the fix named.
+- **Caption size fitted to the cue (1.17).** At a platform caption size a line holds about six em, so an ordinary sentence needs four lines and `--max-lines 2` used to cut it into consecutive cues — half the sentence arriving late. `caption.py --fit-size` (default `auto`) now walks the size down until every cue fits, *before* laying the cues out, with a legibility floor of 4.5 % of the frame height (`--min-size`, default 13 ASS units). `--fit-size off` is 1.16 byte for byte, an explicit `--size` or a `brand.json` size is never overridden, and the caption text is still never rewritten to make it fit.
+- **Beat-synced cuts (1.17).** `scenes.py --beats` reports the measured grid — tempo, beat times, and a confidence built from how far the winning autocorrelation lag stands above the others and how many onsets land on it. `cut.py --snap beats` (and a `"snap"` block in a `render.py` project) moves in/out points to the nearest beat within `--snap-tolerance` — and only onto the grid points a measured onset actually marks, never onto the regular grid's continuation through a passage with no music in it. Below `--min-confidence` it **refuses**: a cut point may move to a measured beat and may not appear from one, so speech and ambience get an honest "no steady pulse here" instead of an invented grid.
+- **Filler words (1.17).** `silence.py --filler --words transcript.json` removes "um" and "uh" through the same cut graph the silences use. Never without measured word timings — there is no heuristic that finds an "um" without them that would not also cut real speech — and `like`, `tipo` and `cioè` are deliberately not in the built-in lists, because a discourse marker is a content word. Whisper stays optional: `--transcribe` with no engine installed refuses and names the three installs.
+- **Throughput (1.17).** `batch.py --jobs N` runs several files at once, capped at `min(N, cpu_count, 8)` and sharing one `--timeout` budget rather than one per item; the per-item table keeps its order. `render.py --cache DIR` reuses stages whose inputs and arguments did not change, so swapping an export preset re-runs export only. The cache is opt-in with no default directory, and the ffmpeg, skill and contract versions are part of every key, so a cache is never reused across them.
 - **Audiogram (1.16).** `waveform.py --image cover.png` (or `render.py --template audiogram`) puts the waveform over a still plate for an episode that has no picture, with `--platform` for the frame, `--title` and burnt-in captions. The image is a local file you give: nothing is fetched and no cover art is ever invented.
 - **Emoji in captions and titles (1.15).** `caption.py`/`graphics.py --emoji-assets DIR` composites a PNG per emoji (Twemoji/Noto naming, `1f389.png`) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — `doctor --json`'s `fonts.emoji` answers that from a render probe. Without assets the run still succeeds and reports `mode: mono`. Nothing is ever downloaded.
 - **Indic and Thai text shaped correctly in titles and lower-thirds (1.15).** `graphics.py` renders Devanagari, Bengali, Tamil, Thai and Lao through libass automatically (`text_renderer: "ass"`), because drawtext never reorders matras or re-clusters marks; Arabic and Hebrew were already correct on a fribidi build. `--text-render drawtext` with such a script is refused, never rendered wrongly.
@@ -407,6 +411,7 @@ type on every OS.
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **90 / 90** | 1.16.0 run (2026-09-14, one pass per prompt, Sonnet agent, regex grader + focused Opus grader on 30 runs, chapters and subtitle streams re-probed, check.py re-run on every delivery output) on the set grown to 90 prompts (audiogram, auto chapters, multi-language tracks, caption breaking): routing 90/90, honest refusals and failures 90/90 with 0 false successes and 0 raw ffmpeg calls, report format 89/90 (one `Done (partially):`), user's language 90/90 by regex (89/90 by Opus), audiogram 2/2 with the cover behind the waveform and nothing fetched, auto chapters 2/2 with `Chapter N` titles only, delivery 16/16 platform pass, trigger set 45/45, Opus quality mean 4.17. The honest part: the phrase breaker never gets to act at the platform caption sizes (a five-word cue does not fit two lines at TikTok size, so the split is byte-identical to 1.15.1), Thai still breaks inside words, and a katakana word was split — 1.16.1 is the patch and the finding is written up in `evals/results/iteration-17.json` |
 | **82 / 82** | 1.15.0 run (2026-09-13, one pass per prompt, Sonnet agent, regex grader + focused Opus grader on 28 runs, stills extracted inside the emoji window, check.py re-run on every delivery output) on the set grown to 82 prompts (emoji captions and title cards, a Hindi and a Thai lower-third): routing 82/82, honest refusals and failures 82/82 with 0 false successes and 0 raw ffmpeg calls, report format 82/82 (both iteration-15 label defects closed: `dl8` and `he2` now carry one `Failed:`), user's language 82/82 by regex (81/82 by Opus: one Spanish report with three English labels), non-Latin glyphs 11/11 (Devanagari through `graphics.py` is fixed; Thai lower-third and captions correct), emoji visible in colour in 3/3 runs given PNG assets and reported monochrome in the one that was not, visual check 23/24, delivery 12/13 one encode and 13/13 platform pass, trigger set 40/40, Opus quality mean 4.68. Still open: the caption breaker splits phrases (`dl1`, `dl4` unchanged) — queued for 1.16.0. Tokens per run flat at 73.3k on the same 76. Details in `evals/results/iteration-16.json` |
 | **76 / 76** | 1.14.0 run (2026-09-13, one pass per prompt, Sonnet agent, regex grader + focused Opus grader on 26 runs, check.py re-run on every delivery output): routing 76/76, honest refusals and failures 76/76 with 0 false successes and 0 raw ffmpeg calls, report format 76/76, user's language 76/76 by regex (75/76 by Opus: one Spanish report with three English labels), visual check 18/18, trigger set 38/38, Opus quality mean 4.58. The delivery templates did their job: 12 of 13 delivery requests went through `render.py --template`, finished in one encode (was 3 of 7) and all 13 pass their platform check (was 7 of 8). Tokens per run flat at 73.4k. Details in `evals/results/iteration-15.json` |
 | **76 / 76** | 1.13.0 run (2026-09-13, one pass per prompt, Sonnet agent, regex grader + focused Opus grader) on the set grown to 76 prompts: 18 in Thai, Hindi, Hebrew, Russian, Greek, Vietnamese, Indonesian, Turkish and Italian, and 8 delivery requests (TikTok, Reels, Shorts, LinkedIn, Douyin, podcast): routing 76/76, honest refusals and failures 76/76 with 0 false successes and 0 raw ffmpeg calls, report format 76/76, user's language 76/76 across seventeen languages, visual check 18/18, trigger set 38/38, Opus quality mean 4.65 over the 26 new runs. One real defect found: Hindi through `graphics.py` (drawtext) comes out wrong-shaped even though the font covers Devanagari; captions through libass are fine (queued for 1.15.0). Four delivery runs spent a second encode for loudness, which 1.14.0's templates address. Tokens per run flat at 72.3k. Details in `evals/results/iteration-14.json` |

package/SKILL.md

@@ -93,6 +93,7 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 | "add subtitles from this SRT", "burn in captions" | `caption.py input.mp4 --srt subs.srt` |
 | "caption it with these lines" (text with times) | `caption.py input.mp4 --text cues.txt` |
 | "keep the subtitles toggleable", "mux in an SRT" | `caption.py input.mp4 --srt subs.srt --mode mux`; repeat `--srt file:lang` for several languages, `.mkv` for more than two |
+| "the captions are tiny / three lines on a Short" | `caption.py` shrinks the size until the cue fits `--max-lines` before splitting it (`--fit-size off` for 1.16 behaviour, `--min-size` sets the floor) |
 | "our logo top-right", "a watermark" | `overlay.py input.mp4 --image logo.png --position top-right --scale 200` |
 | "a title for the first 4 seconds" | `overlay.py input.mp4 --text "Title" --position top --start 0 --end 4 --fade 0.4` |
 | "webcam clip in the corner", "picture-in-picture" | `overlay.py input.mp4 --video webcam.mp4 --position bottom-right --scale 480` |
@@ -180,17 +181,17 @@ When a step fails, replace `Done:` with `Failed:` and keep the rest honest:
 Failed: color.py --lut grade.cube exited 1 — ffmpeg: "Unable to parse LUT file" (the .cube is not a valid LUT)
 Steps: probe -> color (failed); nothing written
 Check: nothing to verify
-Look: not needed (nothing written)
+Look: not needed
 Notes: send a valid .cube, or say if you want the clip left as is
 ```
 
-A refusal (a judgement this skill does not make, or something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run, `Look: not needed`. The shortest failure still gets all five labels, never prose headings. A refusal that still delivers something is `Failed:` — the label answers the request as asked; the alternative goes in `Notes:`. When a failure JSON carries `error.hint`, quote it in `Notes:`: it is the flag change that makes a retry meaningful.
+A refusal (a judgement this skill does not make, or something outside its scope) uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run, `Look: not needed`. The shortest failure still gets all five labels, never prose headings. A refusal that still delivers something is `Failed:`, never a third label like `Done (partially):` — the label answers the request as asked; the alternative goes in `Notes:`. When a failure JSON carries `error.hint`, quote it in `Notes:`: it is the flag change that makes a retry meaningful.
 
 Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}}` with `--json` and exits non-zero; quote the message, never paraphrase it.
 
 ## Things that look right but are wrong
 
-One line each, each enough to act on; open the linked `references/gotchas.md` section only when the job is in that area and the line leaves a question.
+One line each; open the linked `references/gotchas.md` section when the job is in that area.
 
 - HDR (iPhone, HDR10) re-encoded through an SDR path goes flat; the scripts keep HDR, and `hdr: true` is wider than `hdr_signal: true` (a real PQ/HLG/DV transfer). Details: [#hdr-and-colour](references/gotchas.md#hdr-and-colour)
 - Log footage (S-Log/V-Log/C-Log) is tagged SDR and looks grey: `probe.py --analyze`, then `color.py --lut` before anything else. Details: [#log-footage](references/gotchas.md#log-footage)
@@ -198,7 +199,7 @@ One line each, each enough to act on; open the linked `references/gotchas.md` se
 - VFR phone/screen recordings: re-encodes conform to CFR, `cut.py` switches to `--accurate`; pick the rate with `fit.py --fps` when the average is odd. Details: [#variable-frame-rate](references/gotchas.md#variable-frame-rate)
 - Sync/multicam `confidence` under 0.3 (or a huge offset) is probably wrong — check every camera; these align audio, never lip sync. Details: [#sync-multicam-and-drift](references/gotchas.md#sync-multicam-and-drift)
 - "Normalised" audio can still clip (check true peak), and ambience at -40 LUFS or below must never be raised to a speech target. Details: [#loudness-and-ambience](references/gotchas.md#loudness-and-ambience)
-- Captions burned before a crop/resize land off-frame; burned small then upscaled by `export.py` they come out soft — fit to the delivery size first. Details: [#captions-fonts-and-text-order](references/gotchas.md#captions-fonts-and-text-order)
+- Captions burned before a crop/resize land off-frame, and burned small then upscaled by `export.py` they come out soft. Details: [#captions-fonts-and-text-order](references/gotchas.md#captions-fonts-and-text-order)
 - Emoji need `--emoji-assets DIR` (a PNG per glyph) to render in colour; without it they come out monochrome and the run says so. Details: [#emoji](references/gotchas.md#emoji)
 - `graphics.py` renders Devanagari, Bengali, Tamil and Thai through libass automatically — drawtext cannot shape them.
 - Non-Latin text picks a font by script since 1.12; `doctor --json` `fonts.scripts` says which languages this machine renders; no font = failed job. Details: [#fonts-by-script](references/gotchas.md#fonts-by-script)
@@ -207,4 +208,3 @@ One line each, each enough to act on; open the linked `references/gotchas.md` se
 - `yuv420p` needs even dimensions and phone rotation tags are honoured, both automatically. Details: [#dimensions-and-rotation](references/gotchas.md#dimensions-and-rotation)
 - `scenes.py --highlights` ranks by loudness (or duration), never by meaning: check the sheet before treating picks as final. Details: [#highlights](references/gotchas.md#highlights)
 - Three hand-chained re-encodes should be one `render.py` project; re-encodes use x264 `medium`. Details: [#chaining-and-speed](references/gotchas.md#chaining-and-speed)
-- Windows drawtext crashes on some builds (#100): pass `--font-file` explicitly if one does. Details: `references/ci-platform-pitfalls.md`

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.16.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.17.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.16.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.16.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.16.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.16.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.16.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.17.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.17.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.17.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.17.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.17.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.16.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.16.0", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.17.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.17.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.16.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.17.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 |
@@ -212,7 +212,7 @@ gives you:
 |---|---|
 | `bit_exact` | probe, check, scenes, look |
 | `content_equivalent` (same media, bytes may differ between encoder builds) | every encoding tool, cut, sync, report |
-| `cached` | batch (content-hash cache, re-runs skip unchanged inputs) |
+| `cached` | batch (content-hash cache, re-runs skip unchanged inputs); render **when `--cache DIR` is given** — the hint stays `content_equivalent` because that is what render is without the flag, and the cache is opt-in |
 | `environment_dependent` | verify |
 
 ## `provides`
@@ -314,6 +314,12 @@ Names: `ffmpeg`, `ffprobe`, `encoder:<name>`, `filter:<name>`, `bsf:<name>`,
 to omit detection. Nothing from the environment other than those lists and the
 ffmpeg/ffprobe/python versions is printed; no environment variables, no paths.
 
+`external:whisper` is **optional** for two tools since 1.17: `caption.py`
+(`--transcribe`) and `silence.py` (`--filler --transcribe`). Neither requires
+it — both take a transcript the caller already has (`--srt`/`--words`), and
+both refuse with the same three install lines when asked to make one with no
+engine present. Whisper is never a dependency of this skill.
+
 `doctor` has three states per capability. `available` and `missing` come from a listing
 that was read; `unknown` means the listing that would prove the capability could not be
 read (`ffmpeg -filters` in a layout the parser does not recognise, or ffmpeg exiting
@@ -433,6 +439,18 @@ given a different type):
 | `auto_chapters` | `metadata.py --auto-chapters` | `{source, min_chapter, max_chapters, proposed, kept, titles, chapters, description_block, files}`. `titles` is always `"placeholder"`: the machine-readable form of "the skill did not name these". Each chapter carries its `evidence` (`start`, `silence`, `scene`, or `silence+scene` with the span, its length and the cut time) |
 | `audiogram` | `waveform.py` (every run) | `{style, background, image, position, vis_height, platform, captions, title, stages, verified}`. `background` is `"image"` or `"color"`; `verified` is true when the render probes at the asked-for frame size, frame rate and within 0.05 s of the source audio, and is `false` under `--dry-run`, where nothing was rendered to verify |
 
+Per-tool keys added in 1.17, all additive:
+
+| key | tool | what it holds |
+|---|---|---|
+| `fit_size`, `size_requested`, `size_used`, `size_floor`, `size_pct_height`, `shrunk`, `fit_scope`, `fit_exhausted` | `caption.py` | siblings inside the same `caption` block: which mode fitted the size (`auto`/`on`/`off`), the size asked for and the size used in ASS units, the floor (13 = 4.5 % of the frame height), that size as a percentage of the frame, how many cues the shrink rescued, `file` or `cue` scope, whether the floor was reached with cues still split, and `size_source` (`input`, or `platform-frame` when a plan was written before the input existed). `size_used` is `null` when there was no geometry to fit against at all |
+| `beats`, `beat_grid` | `scenes.py --beats` | the measured beat times, and `{supported_beats, tempo_bpm, interval, confidence, phase, onsets, supported, unsupported, method, step_s, range_bpm, usable}`. `supported_beats` is the subset of the regular grid that a measured onset marks — the only list a tool that moves a cut may snap to. `usable` is `confidence >= --min-confidence`; a low confidence is reported, not refused — `scenes.py` measures, it does not act |
+| `snap` | `cut.py --snap beats`, `render.py` | `{mode, tolerance, confidence, tempo_bpm, grid, grid_points, moved, snapped, unchanged, source}`. `grid` is `"supported"`: points are moved only onto grid points a measured onset marks, never onto the regular grid's continuation through a silent passage. `moved` has exactly one row per in/out point given (`from`, `to`, `delta`, `snapped`, `beat_index`) — a point is never added or dropped, and `to` is always either a measured beat or the caller's own value |
+| `filler`, `removed_seconds_total` | `silence.py --filler` | `{lang, source, engine, words, removed, removed_count, removed_seconds, removed_words, word_timings, list, warnings}`. The existing `removed_seconds` is unchanged in name and meaning — the seconds of *silence* removed, which is what it has always held — and `removed_seconds_total` is the additive sibling covering silence plus filler |
+| `jobs`, `jobs_requested`, `wall_seconds`, `item_seconds_total`, `timed_out` | `batch.py` | the parallelism actually applied and the number asked for, the batch's wall clock, the sum of the per-item times (so the speed-up can be quoted), and whether the shared timeout budget ran out. A timed-out item carries `"skipped": "timeout"` in its result row |
+| `cache` | `render.py --cache` | `{dir, ffmpeg, hits, misses, saved_seconds, entries}`, plus `would_hit` under `--dry-run`. The ffmpeg build banner, the skill version, the contract version, the forwarded flags (`--fast`, `--codec`, …) and the output's extension are all part of every key, so a cache is never reused across any of them — a `--fast` draft is never served to a run that did not ask for one |
+
+
 `check.py` also gains an informational `subtitles` row on **every** platform:
 `PASS` when every soft subtitle stream carries a language tag, `WARN` when one
 does not (or when there are none). Like `channels` and `chapters` it is never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.16.0",
+  "version": "1.17.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",

package/references/gotchas.md

@@ -122,6 +122,10 @@ printing one line — `font: /usr/share/fonts/.../wqy-zenhei.ttc (covers ko)`.
   `brew install --cask font-noto-sans-cjk font-noto-sans-arabic`, or point at a
   file with `--font-file` (`overlay.py`, `graphics.py`) / `--fonts-dir`
   (`caption.py`).
+- Windows drawtext crashes on some builds (#100) when it has to resolve a font by
+  family name: pass `--font-file` explicitly if one does. `default_font_file()`
+  already resolves a file for you on Windows, so this bites only a hand-built
+  drawtext call. More: `references/ci-platform-pitfalls.md`.
 - Han characters alone (no kana, no hangul) are read as Chinese. Japanese or
   Korean hanja text with no kana needs `--lang ja` / `--lang ko`
   (`caption.py --language` is the same flag), or `"lang"` in brand.json.

package/references/scripts.md

@@ -64,6 +64,7 @@ BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR" --
 ### cut.py — cut / join segments
 ```
 cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,...] [--accurate] [-o OUT]
+cut.py INPUT --start T --end T --snap beats [--snap-tolerance 0.12] [--snap-source FILE] [--min-confidence 0.5]
 ```
 Times accept `12.5`, `1:30`, `00:01:30.250`. Default is `-c copy` (snaps to
 keyframes, instant, lossless); if the snapped result deviates more than
@@ -74,6 +75,49 @@ the result was "lossless stream copy" or "re-encoded"; when the snap forced a
 re-encode, the result's `lossless_alternative` names the nearest keyframe
 `--start` that would stream-copy instead, so the trade can be offered.
 
+**`--snap beats` (1.17)** moves each in/out point to the nearest *measured*
+beat within `--snap-tolerance` seconds (default 0.12, about a quarter of a beat
+at 120 BPM). The grid comes from the input's own audio, or from
+`--snap-source` — either a `scenes.py --beats --json` document (no second
+decode) or a separate music file. The snap happens *before* the
+keyframe/tolerance decision, so lossless-vs-accurate is judged on where the cut
+actually lands.
+
+"Measured" is exact: the only points a cut may move onto are the
+`supported_beats` — the grid points a measured onset actually marks — never the
+full regular grid, which by construction runs on through a passage with no music
+in it. A cut asked for inside that passage stays where it was asked for, and
+`snap.grid` is `"supported"` with `snap.grid_points` saying how many there were.
+`--min-confidence` must be greater than 0: at 0 every grid is "reliable",
+including one measured from noise.
+
+The number of in/out points never changes: a point with no beat inside the
+tolerance is returned unchanged, and no point is ever invented. Three
+`kind: input` refusals, nothing written:
+
+- confidence below `--min-confidence` → *"no reliable beat grid in this audio
+  (confidence 0.21, needs 0.5): cutting to invented beats would move your in/out
+  points to times nothing in the audio supports. Re-run with `--snap none`, or
+  pass `--snap-source` from a music bed."*
+- no audio stream → names `--snap none`.
+- no in/out point at all (a whole-file copy) → there is nothing to snap, and
+  this tool never proposes cuts of its own.
+
+Result: `snap.mode`, `snap.tolerance`, `snap.confidence`, `snap.tempo_bpm`,
+`snap.moved` (one row per point, with `from`/`to`/`delta`/`snapped`),
+`snap.snapped`, `snap.unchanged`, `snap.grid`, `snap.grid_points`, and
+`snap.source` (`"measured"` or the path). In a `render.py` result, `snap.clips`
+carries one entry per snapped clip with `clip` naming its index, and the first
+entry's keys are repeated at the top level for a single-clip project. A clip
+served from `--cache` was snapped when it was first rendered, and says so
+(`source: "cache"`) rather than reporting `snap: null`. A `--snap-source`
+document that does
+not carry `beat_grid.supported_beats` (one written before 1.17) is refused
+rather than treated as if every grid point were supported, as is one whose
+`tempo_bpm` is null while it lists beats.
+`render.py` forwards a project's `"snap": {"to": "beats", ...}` (project-wide
+or per clip) to this flag and reports what came back.
+
 ### fit.py — target duration and/or aspect, rotate/flip
 ```
 fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
@@ -422,6 +466,9 @@ each shorter clip's last frame (with silence) out to the longest.
 ### silence.py — remove dead air / jump cuts
 ```
 silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [-o OUT]
+silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|es|de|fr|pt|it]
+           [--filler-words FILE] [--filler-extra W,W] [--filler-keep W,W] [--filler-pad 0.02]
+           [--transcribe] [--filler-list] [--max-cuts 400]
 ```
 Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
 gaps shorter than `--min-silence`, and re-encodes once with `select`/`aselect`
@@ -430,6 +477,60 @@ without rendering; `--edl` saves the kept ranges in `cut.py --segments` format
 so the user can edit the list by hand. Quiet rooms need `--threshold -40`
 to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
 
+**`--filler` (1.17)** removes filler words as well, through the same
+`keep_ranges()`/`aselect` graph with more, shorter ranges. It is **never**
+applied without measured word timings: pass `--words` (a whisper JSON carrying
+per-word `start`/`end`) or `--transcribe` (the same local engine `caption.py`
+uses, never required). There is no heuristic fallback — finding an "um" by
+looking for short quiet blips would cut real speech, so the tool refuses
+instead. `--filler-list` reports what would go and writes nothing.
+
+Built-in lists, one per language:
+
+| lang | words |
+|---|---|
+| en | um, uh, erm, hmm, mm, mhm, er, ah |
+| ja | えー, えーと, えっと, あの, あのー, その, そのー, まあ, なんか |
+| es | eh, este, esto, mmm |
+| de | äh, ähm, hm |
+| fr | euh, hein |
+| pt | é, hum |
+| it | ehm |
+
+**Discourse markers are not disfluencies.** `like`, `tipo` and `cioè` are
+deliberately *not* in the default lists: they are grammatical words in most
+sentences, and removing them cuts meaning rather than noise — a judgement about
+content, which this skill does not make. They are reachable with
+`--filler-extra like`, which says so in its own `--help`. Japanese `なんか` is
+in the `ja` list because leaving it out makes the flag useless for Japanese,
+and it is orthographically identical to the pronoun use — so every run that
+removes one warns, and `--filler-keep なんか` takes it back out. Matching is
+case-folded, punctuation-stripped and whole-token only: `umbrella` survives.
+
+Three refusals, all `kind: input`, all before any encode:
+
+- `--filler` with neither `--words` nor `--transcribe` → names both flags.
+- `--transcribe` with no engine on PATH → the same message `caption.py` gives,
+  with the three install lines.
+- `--transcribe` where the engine runs but its build produces no word-level
+  timings → names that engine, says some builds do not support word timestamps,
+  and points at `--words`. (`--transcribe` drives whichever engine is installed
+  with *its* word-timestamp option — whisper.cpp `--output-json-full`,
+  faster-whisper `word_timestamps=True`, openai-whisper `--word_timestamps
+  True` — because an SRT cannot answer this: a cue has a start and an end, a
+  word does not. `--words` is the tested path and the one to prefer.)
+- a transcript with segments but no word-level timings → says that cutting on
+  segment boundaries would remove whole sentences, and how to re-run whisper.
+
+Results: `filler.removed_count`, `filler.removed_seconds`, `filler.removed`
+(one entry per span), `filler.lang`, `filler.list`, `filler.word_timings` and
+`filler.warnings`. The existing `removed_seconds` keeps exactly the meaning it
+has always had — the seconds of **silence** this run removed, the figure the
+same run would report without `--filler` — and `removed_seconds_total` is the
+additive sibling covering everything that went. A filler word quiet enough to
+sit inside a detected silence is merged into it rather than counted twice, so
+the two figures can be equal.
+
 ### join.py — concatenate with transitions
 ```
 join.py CLIP1 CLIP2 [...] [--transition fade|dissolve|wipeleft|slideleft|fadeblack|fadewhite|circleopen|none]
@@ -447,6 +548,7 @@ output; the result says so with `dropped_non_av_streams: true`.
 ```
 render.py --init project.json                # starter file
 render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep]
+render.py project.json --cache DIR [--from STAGE]    # reuse identical stages from a previous run
 render.py plan.json                          # execute a plan written by <tool> --plan plan.json
 ```
 A plan is a single tool's dry run as an artifact: `cut.py in.mp4 --start 2 --end 8
@@ -479,6 +581,40 @@ 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.
 
+**`--cache DIR` (1.17)** reuses the artifact of a stage that already ran with
+exactly the same arguments and the same inputs. Opt-in only: **there is no
+default cache directory** — one appearing on someone's disk unasked would
+contradict this tool's "a plan leaves nothing behind" posture. The key is a
+sha1 over the stage name, the tool, its arguments (every existing path replaced
+by its content hash), the input hashes, the **forwarded** flags (`--fast`,
+`--overwrite`, `--timeout`, `--codec`), the output's extension, and **the ffmpeg
+build banner, the skill version and the contract version**. `--fast` matters as
+much as any of them: it rewrites every child's preset to `veryfast`, so without
+it in the key a `--cache --fast` draft would be served back to a later run that
+asked for the delivery. The banner rather than `major.minor` because two 7.1.x
+builds with different libx264 produce different bytes from the same command. Those last three are in the key deliberately: a
+different build simply *misses* rather than being asked to trust a file it did
+not write, and a stage whose implementation changed cannot serve back an
+artifact the old one produced. Each entry is `DIR/<key><ext>` plus a
+`DIR/<key>.json` sidecar (stage, versions, creation time, size, seconds). A hit
+hardlinks the artifact into the work directory, or copies it where the
+filesystem will not link — never moves it, since the cache has to outlive the
+run's own cleanup. Any mismatch is a silent miss.
+
+`stages_done` is unchanged: a cached stage is still a stage that happened.
+Nothing is written under `--dry-run`, which instead reports `cache.would_hit`.
+Result: `cache.dir`, `cache.ffmpeg`, `cache.hits`, `cache.misses`,
+`cache.saved_seconds`, `cache.entries`. `--from STAGE` starts at that stage and
+takes every earlier one from the cache; without `--cache`, or when an earlier
+stage is not there, it refuses (`kind: input`) rather than quietly re-encoding
+what it promised to skip. An unwritable cache directory is `kind: output`.
+
+`"snap": {"to": "beats", "tolerance": 0.12, "min_confidence": 0.5, "source":
+"music.mp3"}` at the project root (or inside one clip) forwards `--snap beats`
+to the clip cut for every clip that has `in`/`out`; the measured grid comes back
+in the render result's `snap`. A project without `"snap"` builds the command
+line 1.16 built.
+
 Stages: clips (cut, optional speed) → join (transition) → silence → fit →
 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
@@ -549,6 +685,7 @@ already has a picture.
 ### 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]
+scenes.py INPUT --beats [--beat-step 0.01] [--beat-range 60-200] [--min-confidence 0.5] [--json]
 ```
 Lists scenes with audio energy, the loudest moments, and (with
 `--highlights`) proposes N ranges that add up to `--target` seconds, biased to
@@ -560,6 +697,45 @@ Dissolves and very slow fades are not cuts and will be missed. Highlights are
 a proposal engine, not a judgement of content: tell the user what it picked
 and why (energy, scene length).
 
+**`--beats` (1.17)** measures the music's beat grid and reports it:
+
+```json
+"beats": [0.0, 0.5, 1.0, ...],            // 25 of them over a 12 s click track
+"beat_grid": {"tempo_bpm": 120.0, "interval": 0.5, "confidence": 0.997,
+              "supported_beats": [0.0, 0.5, 1.0, ...],   // the 24 an onset marks
+              "phase": 0.0, "onsets": 24, "supported": 24, "unsupported": 1,
+              "method": "rms-flux-autocorrelation", "step_s": 0.01,
+              "range_bpm": [60, 200], "usable": true}
+```
+
+Method: onset strength as the half-wave-rectified first difference of
+`log(envelope)`, peaks above `median + 1.5·MAD` over a ±1 s window with a 60 ms
+refractory gap, tempo from the autocorrelation of the onset signal inside
+`--beat-range` with its half and double checked, phase chosen to catch the most
+onset strength. `confidence` is half how far the winning lag stands above the
+other lags (in standard deviations) and half the fraction of onsets that land
+on the grid. With `--beats` the file is decoded once, at 22050 Hz, and the
+`supported + unsupported == len(beats)` always, and `supported_beats` is that
+supported subset — the list `cut.py --snap beats` moves onto.
+
+With `--beats` the file is decoded once, at 22050 Hz, and the 0.5 s scene
+envelope is derived from that same pass rather than from a second 8 kHz decode.
+One consequence worth knowing: `scenes.py X --json` and `scenes.py X --beats
+--json` report very slightly different `audio_rms`/`audio_peak` figures for the
+same file, because the two envelopes are built from PCM at different rates. The
+scene boundaries and their ranking are unaffected; only the fourth decimal of
+the level moves. `--beats` also holds ~2.75x the samples in memory, which is
+worth knowing on a feature-length input.
+
+**A beat grid is a measurement of the music's periodicity, not of where a cut
+belongs.** A low confidence means the audio has no steady pulse — speech,
+ambience, rubato — and the skill will not snap to a grid it cannot measure.
+`scenes.py` is the analysis tool, so it *reports* a weak measurement
+(`usable: false`) rather than refusing it; refusing belongs to the tools that
+would change a file on the strength of it (`cut.py --snap beats`). `--edl` with
+`--beats` is unchanged: beats are never written as an EDL, because a beat is
+not a cut. No audio stream is a `kind: input` refusal.
+
 ### check.py — pre-delivery compliance
 ```
 check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|facebook|broadcast|podcast|custom [--no-loudness] [--json]
@@ -582,13 +758,42 @@ construction, not by two lists agreeing.
 
 ### batch.py — same recipe over a folder, cached
 ```
-batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--json]
+batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--jobs N|auto] [--json]
 ```
 `batch.json` holds either `steps` (a list of script argv with `{in}`/`{out}`
 placeholders, chained) or `project` (a render project applied per file).
 Outputs land in `output_dir` with `suffix`; a content-hash cache skips files
 already done with the same recipe. Use `--dry-run` to preview the plan.
 
+**`--jobs N` (1.17)** processes N files at once (threads: the work is
+subprocess waiting). Capped at `min(N, cpu_count, 8)` — every item is itself an
+ffmpeg that already threads across cores, so beyond a few concurrent encodes
+the jobs contend and wall-clock stops improving while memory does not. A number
+above the cap is clamped with a note, not refused, and both `jobs` and
+`jobs_requested` are in the result. `--jobs auto` is `min(cpu_count, 4)`.
+
+- **One timeout budget for the whole batch**, not one per item: `--timeout` is
+  computed into a deadline once, no new item starts after it, and the run exits
+  124 `kind: timeout` with the items that never started marked
+  `"skipped": "timeout"`. That shared budget applies when a `--timeout` was
+  actually given, or when `--jobs > 1` asked for the batch to be treated as one
+  piece of work; the default sequential path with the default timeout is 1.16's
+  behaviour exactly, where a long folder was never cut off part-way.
+- **Determinism**: every item is written into its own slot in one list indexed
+  by position in the sorted file list — cached hits included, which is what keeps
+  the table in file order when the cache is only partially warm — and each item's
+  log lines are buffered and flushed in file order, so the per-item table and the
+  log read exactly as a serial run's whatever order the encodes finish in.
+- **A failed item is a row, not a dead run**: a worker that raises becomes
+  `ok: false` with its reason, and the summary and the table are still printed.
+  Ctrl-C cancels what has not started, keeps what finished, and exits 130
+  `kind: interrupted` with the partial table.
+- With `--jobs > 1` each item gets its own work subdirectory
+  `<workdir>/<index>-<stem>/`, because step file names are stem-derived and two
+  sources sharing a stem would otherwise write over each other. `--jobs 1` (the
+  default) keeps the flat layout and is 1.16's path exactly.
+- `--watch` composes: each pass is parallel, passes are sequential.
+
 ### caption.py --transcribe — optional local speech-to-text
 If `whisper-cli` (whisper.cpp), `faster-whisper` or `whisper` is installed,
 `caption.py input.mp4 --transcribe [--language ja] [--model base]` writes the
@@ -726,11 +931,62 @@ caption.py INPUT --srt FILE[:LANG] | --ass FILE | --text CUES.txt [--write-srt O
            [--audio-stream N] [--fps N] [--lang XX] [--offset TIME]
            [--max-lines N] [--min-duration S] [--wrap phrase|measured]
            [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
+           [--fit-size auto|on|off] [--min-size N] [--fit-size-scope file|cue]
            [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N]
            [--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
 ```
+**`--fit-size` (1.17): the size is fitted before a cue is split.** At the TikTok
+caption size (24 ASS units against the 288-line script grid) a line has about
+six em, so an ordinary sentence needs four lines — and `--max-lines 2` then cut
+it into consecutive cues, so half of it arrived late. That was the size, not the
+breaker. `--fit-size` walks the size down until every cue wraps within
+`--max-lines`, and only then lays the cues out.
+
+- `auto` (default) shrinks only a size the *skill* chose. An explicit `--size`,
+  or a `brand.json` `styles.caption.size`, is a statement about the look and is
+  never overridden.
+- `on` always fits, `--size` or not. **`off` is 1.16.1 exactly, byte for byte**
+  (a pinned ASS fixture asserts it).
+- `--min-size` is the floor, default `ass_units(0.045) = 13` — **4.5 % of the
+  frame height**, one floor for every destination (87 px of type on a 1920-tall
+  frame, above the ~3.5 % where mobile legibility and the platforms' own caption
+  UIs bottom out). Nothing per-platform is measured, so nothing is claimed.
+- `--fit-size-scope file` (default) uses one size for the whole file; `cue`
+  writes a per-cue `{\fsN}` override. A size that changes from cue to cue reads
+  as a mistake, so it is opt-in — it exists for the one outlier cue that would
+  otherwise shrink a ten-minute file. Each cue is laid out at the size it will
+  be **drawn** at: a cue drawn larger has a narrower line in em, so wrapping
+  everything to the file-wide budget and then drawing some cues large would put
+  lines off the side of the frame.
+
+The text is **never** touched: this skill does not rewrite, shorten or
+paraphrase a caption to make it fit. Below the floor the cue is split exactly as
+before and `fit_exhausted: true` says so, with `--min-size` named as the flag
+that would go smaller and `|` as the manual break. `--min-size` above `--size`
+is a `kind: input` refusal. `--mode mux` is unaffected: soft subtitles carry no
+size, so the SRT is the one 1.16 wrote.
+
+Results, alongside the existing caption stats:
+`fit_size`, `size_requested`, `size_used`, `size_floor`, `size_pct_height`,
+`shrunk`, `fit_scope`, `fit_exhausted`, and `size_source` (`input` or
+`platform-frame`).
+
+Under `--dry-run`/`--plan` on an input that does not exist yet there is no
+geometry to measure. With `--platform` the destination's own frame is used —
+that frame *is* what the real run will have, so the planned `FontSize` is the
+one the run will burn. Without a platform nothing can stand in for the frame
+and `size_used` is `null`, rather than presenting the requested size as a
+fitted one.
+
+| ASS size | px on 1920 | % frame h | em per line |
+|---|---|---|---|
+| 24 (default) | 160.0 | 8.3 % | 6.08 |
+| 19 | 126.7 | 6.6 % | 7.67 |
+| 16 | 106.7 | 5.6 % | 9.11 |
+| 13 (floor) | 86.7 | 4.5 % | 11.22 |
+
 Text cue format, one per line: `0:00-0:03 Hello`, `00:00:03.500 --> 00:00:06 Two | lines`,
 or `00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode` (`hh:mm:ss:ff`, frame count
 converted with `--fps`, or the input video's own fps when `--input` is given and `--fps` is
@@ -758,9 +1014,13 @@ frame width) at the chosen `--size`, measured per script — CJK and Thai count
 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,
 Arabic/Hebrew 0.6, Devanagari 0.7, and a combining mark nothing at all —
-breaking between characters for CJK/Thai and at spaces otherwise, but never
-between a character and the combining marks that belong to it (Thai tone marks
-and vowel signs, Devanagari matras, Arabic and Hebrew points). A cue that would need more than `--max-lines` (default 2) is split
+breaking between characters for CJK (a katakana word stays whole) and at spaces
+otherwise, but never between a character and the combining marks that belong
+to it (Devanagari matras, Arabic and Hebrew points). Thai (1.16.1) is never
+broken inside a run: it writes no space inside a phrase and the wrapper has no
+dictionary, so the break goes where you put a space or a `|`, and a run with
+none stays long on its own line — `caption.py` counts such lines as `overlong`
+and says so. A cue that would need more than `--max-lines` (default 2) is split
 into consecutive cues sharing its time; a cue shorter than `--min-duration`
 (default 1.0 s) is held longer, never past the next cue's start; `--offset
 TIME` shifts every cue (seconds, `mm:ss`, `hh:mm:ss.ms` or `hh:mm:ss:ff`, a