ffmpeg-skill 1.15.1 → 1.16.0

package/README.md

@@ -213,13 +213,13 @@ These are the rules the skill file gives the agent and the code enforces.
 | `reverse.py` | Reverse playback (video and, unless `--no-audio`, audio) |
 | `stabilize.py` | Two-pass motion stabilisation (`vidstabdetect`/`vidstabtransform`) |
 | `sequence.py` | Numbered (`frame_%04d.png`) or glob-matched still images into a video |
-| `waveform.py` | Render an audio track as a waveform or spectrum visualization video (`showwaves`/`showspectrum`) — for audio-only inputs with no picture worth showing |
+| `waveform.py` | Render an audio track as a waveform or spectrum visualization video (`showwaves`/`showspectrum`) — for audio-only inputs with no picture worth showing; `--image` puts the visualisation over a still plate (an audiogram), with `--platform`, `--title` and burnt-in captions |
 | `freeze.py` | Hold a frame for N seconds (`--at`, `--hold`, `--mode insert/extend`) — an end-card hold or a comedic beat |
 | `pad.py` | Add black/silent padding at the start and/or end of the timeline (`--start`, `--end`) — distinct from `fit.py --fit pad`'s per-frame letterbox bars |
 | `speedramp.py` | Step through different constant speeds across a clip via `--segment START-END:FACTOR` (repeatable) — distinct from `fit.py`'s single whole-clip speed factor |
 | `loop.py` | Repeat a clip `--times` N or to a target `--duration` — for background loops and filling a fixed slot length |
 | `broll.py` | Cut away to a B-roll clip over the A-roll for a window (`--insert B --at T --duration D`, repeatable) and come back; A's length and audio untouched by default |
-| `metadata.py` | Write container chapter markers from a `TIME TITLE` text file and title/artist/comment tags, every stream copied bit for bit |
+| `metadata.py` | Write container chapter markers from a `TIME TITLE` text file and title/artist/comment tags, every stream copied bit for bit; `--auto-chapters` proposes the markers from measured pauses and scene cuts and names them `Chapter N` for you to rename |
 | `grid.py` | Composite `--cols`x`--rows` clips into one grid, each cell letterboxed and labelled with its filename by default (`--label none` to skip) |
 
 **Audio**
@@ -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 by measured width with `--max-lines`/`--min-duration`/`--offset`; 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; 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) |
@@ -361,6 +361,8 @@ 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.
+- **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.
 - **Non-Latin text picks a font by script (1.12).** Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari, Thai, Cyrillic and Greek cues, titles and overlays resolve a font file that covers them automatically, and a machine with no such font fails the job (`kind: input`) instead of rendering boxes. `doctor --json`'s `fonts.scripts` says which languages this machine can render; `--lang ja|ko` disambiguates Han-only text; an explicit `--font`/`--font-file` is always kept.

package/SKILL.md

@@ -7,13 +7,13 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. This file is enough to do a job: the table below routes the request and `--help` on the one script you are about to run is the cheapest full flag list. The reference files cost as much to read as this file does, so open one only when it answers a question you actually have: `references/scripts.md` (every flag of all 42 scripts), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end).
 
-Shared flags, on every script: `--dry-run`; `--json` (output path, a probe of the output, the commands run); `--json-brief` (that document trimmed to status/output/verified, a compact `summary` and the command count — prefer it on every writing step); `--fast` (preview quality); `--progress`; `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (consent to replace an existing output — warned today, refused from 2.0); `--plan FILE` (the dry run as a plan document `render.py FILE` executes later, refusing if an input changed). Every re-encoding tool also takes `--codec h264|hevc|av1|prores` and `--quality N` (CRF scale, replaces the deprecated `--crf`): unset, SDR is x264 and HDR is x265 Main10; `prores` needs an explicit `-o NAME.mov`, `h264` refuses an HDR source (`color.py --to-sdr` first).
+Shared flags, on every script: `--dry-run`; `--json` (output path, a probe of the output, the commands run); `--json-brief` (the same trimmed to status/output/verified plus a `summary` — prefer it on writing steps); `--fast` (preview quality); `--progress`; `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (step 7); `--plan FILE` (the dry run as a plan `render.py FILE` runs later, refusing if an input changed). Every re-encoding tool also takes `--codec h264|hevc|av1|prores` and `--quality N` (CRF scale, replaces the deprecated `--crf`): unset, SDR is x264 and HDR is x265 Main10; `prores` needs an explicit `-o NAME.mov`, `h264` refuses an HDR source (`color.py --to-sdr` first).
 
-Writing tools run nothing under `--dry-run`; `probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness` and `stabilize` may still run ffmpeg/ffprobe to measure — they just don't write their artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` ignores the flag. Per-tool: `contract --json`'s `dry_run` field.
+Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) may still run ffmpeg/ffprobe — they just don't write their artifact, nor side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per-tool: `contract --json`'s `dry_run` field.
 
 ## Workflow (always follow this order)
 
-0. **Environment, only on failure.** Never start a job with `doctor`: a broken machine fails on its own with `kind: missing_tool` or an ffmpeg error naming the filter/encoder (`No such filter: 'subtitles'`). Run `python3 <skill-dir>/scripts/_contract.py doctor` (also `npx ffmpeg-skill doctor`; there is no doctor.py) after such a failure, or when the user asks what the machine can do: read `ok` and the tool's `usable`, and report the missing capability (usually `libass`, `zscale` or an encoder) rather than rediscovering it at runtime. `contract --json`'s tool schema is for a *planning* agent choosing a tool from an abstract goal, not for this workflow.
+0. **Environment, only on failure.** Never start a job with `doctor`: a broken machine fails on its own with `kind: missing_tool` or an ffmpeg error naming the filter/encoder (`No such filter: 'subtitles'`). Run `python3 <skill-dir>/scripts/_contract.py doctor` (also `npx ffmpeg-skill doctor`) after such a failure, or when the user asks what the machine can do: read `ok` and the tool's `usable`, and report the missing capability (usually `libass`, `zscale` or an encoder) rather than rediscovering it at runtime. `contract --json`'s tool schema is for a *planning* agent choosing a tool from an abstract goal, not for this workflow.
 1. **Probe what you must plan from.** Run `probe.py` on each input you plan the edit from — duration, fps, resolution, codecs, channels, `variable_frame_rate_suspected` — and whenever the user asks about a file. No separate probe before every edit: every writing tool's `--json` already carries its input and a probe of the output. Plan from real numbers, never assumptions.
 2. **Prefer lossless.** If the request can be met without re-encoding (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode. `cut.py` and `loudness.py` stream-copy video by default; `--accurate` on `cut.py` only for frame-exact cuts.
 3. **Plan with `--dry-run --json`, then execute.** Trust `--json`, not a dry run's summary line, for any number in the plan (dimensions there can be a placeholder — `docs/contract.md`). Use it before long encodes and to report exact facts. `--fast` is preview quality (x264 veryfast), `--progress` prints percent/ETA on stderr. Never point `-o` at a file you did not create in this job unless the user asked for it to be replaced; pass `--overwrite` only then.
@@ -57,7 +57,7 @@ If a request needs an FFmpeg feature none of the 42 scripts expose, say so and n
 
 This table and `doctor --json`'s `tools` list are the source of truth for what exists: name only a script you have seen in one of them (there is no `doctor.py`, no `trim.py`, no `subtitle.py`).
 
-Timestamp flags — `--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`, and the times in cue and chapter files — take seconds, `mm:ss(.fff)`, `hh:mm:ss(.fff)` or four-part SMPTE `hh:mm:ss:ff`, with `@fps` naming the rate (`00:01:02:15@29.97`); flags that are a length rather than a point in time (`--min-silence`, `--margin`, `--min-keep`, `--fade`) are plain seconds. Use the timecode forms when the user pastes an NLE cue sheet, so nothing is converted by hand.
+Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`, and the times in cue and chapter files) take seconds, `mm:ss(.fff)`, `hh:mm:ss(.fff)` or SMPTE `hh:mm:ss:ff` with `@fps` (`00:01:02:15@29.97`) — paste an NLE cue sheet as it is; length flags (`--min-silence`, `--margin`, `--fade`) are plain seconds.
 
 | User says | Do |
 |-----------|----|
@@ -87,16 +87,17 @@ Timestamp flags — `--start`, `--end`, `--at`, `--from`, `--duration`, `--offse
 | "speed up here, slow-mo there" (known segments) | `speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0` |
 | "loop this clip to fill 30 seconds" | `loop.py bg_loop.mp4 --duration 30` |
 | "cut to the product shot 0:12-0:16", "B-roll over this bit" | `broll.py talk.mp4 --insert product.mp4 --at 12 --end 16` (repeat `--insert/--at`; `--audio b\|mix`) |
-| "add chapters", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (`TIME TITLE` per line; streams copied; a `render.py` project spells it `"chapters"`) |
+| "add chapters", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (`TIME TITLE` per line; streams copied; a `render.py` project spells it `"chapters"`). `--auto-chapters` proposes them from measured pauses/scene cuts, titled `Chapter N` for you to rename |
 | "set the title / artist / comment" | `metadata.py episode.mp4 --title "Episode 12" --artist "Studio"` |
 | "put these videos in a 4x2 grid" | `grid.py t1.mp4 ... t8.mp4 --cols 4 --rows 2` |
 | "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` |
+| "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 |
 | "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` |
 | "remove the green screen" | `overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00` |
+| "turn this podcast into a video", "audiogram" | `render.py --template audiogram ep.m4a --image cover.png` — waveform over a still or colour plate; give an image or a colour, nothing is fetched |
 | "sync the lav mic", "line up two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second` |
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` podcast, `-I -23` broadcast; `--lra N` for the range) |
 | "cut this and make it HEVC / AV1 / ProRes" (output codec named) | `cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc` (`--codec`/`--quality` on any re-encoding tool; ProRes needs `-o NAME.mov`) |
@@ -149,7 +150,7 @@ Audio is a first-class input: `probe.py`, `cut.py`, `silence.py`, `loudness.py`,
 
 ## Report format
 
-Reply in the language the request itself is written in — the user's own sentences, not a language the request talks about (a request for subtitles in another language is still answered in the language it was written in) and not the language of a tool's error text or file names. Keep the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English: they read like log fields across languages. Everything around them — the sentences, any question, any explanation of a judgement call — is in the user's language. Never default to English because the tool names are English, and never drift because the job was short or the report is a failure: a one-line "file does not exist" is in the request's language too. A mid-conversation switch follows the user's latest message. English `Done:`/`Steps:` sentences with one word of the user's language in `Notes:` is an English report — the descriptions are in the user's language even when the values are technical.
+Reply in the language the request itself is written in — the user's own sentences, not a language the request talks about (a request for subtitles in another language is still answered in the language it was written in). Keep the field labels (`Done:`, `Steps:`, `Check:`, `Look:`, `Notes:`) in English: they read like log fields across languages. The *lines* they head are not: `Done:`, `Steps:` and `Check:` carry the user's language just as `Look:` and `Notes:` do — a Spanish prompt answered with English `Done:`/`Steps:` sentences is an English report. Everything around them — the sentences, any question, any explanation of a judgement call — is in the user's language. Never default to English because the tool names are English, and never drift because the job was short or the report is a failure: a one-line "file does not exist" is in the request's language too. A mid-conversation switch follows the user's latest message.
 
 Finish every job with this shape (numbers from `--json` or `probe.py`/`check.py`, not memory):
 

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.15.1`) | any release |
+| `skill.version` | the npm / package.json version (`1.16.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.15.1 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
-| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.15.1 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
-| `json` and `progress` in the MCP `inputSchema` | 1.15.1 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
-| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.15.1 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
-| Overwriting an existing output with only a warning | 1.15.1 | `--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.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 |
 
 ## Skill
 
 ```json
 {
   "contract_version": "1.0",
-  "deprecated": [{"what": "...", "since": "1.15.1", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.15.1", "execution_mode": "local", "kind": "execution",
+  "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",
             "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.15.1): 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.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 |
 | `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 |
@@ -423,6 +423,21 @@ including `input_lra`) and `targets` (the requested lufs / tp / lra).
 `check.py --platform podcast` adds two informational rows to `checks`,
 `channels` and `chapters`.
 
+Per-tool keys added in 1.16, all additive (no 1.15 key is removed, renamed or
+given a different type):
+
+| key | tool | what it holds |
+|---|---|---|
+| `caption` | `caption.py` | the cue-layout counts the run only printed before (`shifted`, `wrapped`, `rebalanced`, `split`, `extended`, `dropped`) plus `wrap` (`"phrase"` or `"measured"`) and `phrase_breaks`, the number of cues a phrase rule broke somewhere the 1.15 width rule would not |
+| `tracks`, `subtitle_tracks` | `caption.py --mode mux` | one entry per subtitle stream in the output — `{index, file, language, title, codec, default, cues, kept_from_input}`; a stream the input already carried has `file: null` and `kept_from_input: true`. `subtitle_tracks` is the total. Every field describes the file as written, not as asked for: an MPEG-4 output reports `title: null` (the muxer stores none) and `default: true` on its first track (the muxer always enables it), each with a `notes` line |
+| `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 |
+
+`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
+counted in `failed` — no platform refuses a delivery over it.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.15.1",
+  "version": "1.16.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/scripts.md

@@ -256,7 +256,11 @@ frame is refused here, not discovered from an opaque ffmpeg error).
 ### waveform.py — audio waveform/spectrum visualization video
 ```
 waveform.py INPUT [--style waveform|spectrum] [--width W] [--height H] [--fps N]
-                   [--color C] [--background C] [--waveform-mode M] [--split-channels] [-o OUT]
+                   [--color C] [--background C] [--waveform-mode M] [--split-channels]
+                   [--image PATH] [--image-fit cover|contain|blur]
+                   [--position bottom|centre|top|strip] [--vis-height FRAC] [--opacity 0..1]
+                   [--platform NAME] [--srt FILE | --text FILE] [--title TEXT] [--brand brand.json]
+                   [-o OUT]
 ```
 Renders the input's audio as a video: `--style waveform` (default, FFmpeg's
 `showwaves`) draws amplitude over time; `--style spectrum` (`showspectrum`)
@@ -265,6 +269,29 @@ mixes at the cost of being less immediately readable. The output always
 carries the audio it visualizes. For an audio-only input (no video stream
 needed) or any file with an audio track worth visualizing.
 
+**Audiogram (1.16).** `--image PATH` puts a local still behind the
+visualisation, which is what turns a podcast episode into something postable.
+`--image-fit cover` (default) scales to cover and centre-crops; `contain` pads
+with `--background`; `blur` uses fit.py's blurred-pad plate. `--position`
+places the band (`strip`, the default, is a band of `--vis-height` -- a
+fraction of the frame, default 0.35 -- along the bottom, the podcast
+convention); `--opacity` fades the visualisation over the plate. `--platform`
+takes the frame size and fps from the delivery table and refuses a destination
+with no frame (`podcast`) -- the still is fed at that rate, so the plate cannot
+quietly decide the output's frame rate, and the run verifies the rate it
+announced along with the frame size and the duration. `--image` must be a file
+ffmpeg can actually decode: one that is not is refused (`kind: input`) before
+any encode starts. `--title` draws one label through graphics.py's
+sticker template and `--srt`/`--text` burns captions by running caption.py
+afterwards -- both as second processes, so neither of those code paths is
+re-implemented here. `--image` must be a readable local file: a URL is refused
+(`kind: input`), nothing is fetched, and the skill never invents cover art --
+give an image or a colour. Without any of these flags the command line is
+byte-identical to 1.15's. Every run's result carries an `audiogram` object (style,
+background, image, position, vis_height, platform, captions, title, stages,
+verified). `render.py --template audiogram` is the one-call form; it is
+deliberately not part of `--template all`.
+
 ### freeze.py — hold a frame for N seconds
 ```
 freeze.py INPUT --hold T [--at T] [--mode insert|extend] [-o OUT]
@@ -338,7 +365,10 @@ output; the result says so with `dropped_non_av_streams: true`.
 
 ### metadata.py — chapter markers and container tags, streams copied
 ```
-metadata.py INPUT [--chapters chapters.txt | --clear-chapters]
+metadata.py INPUT [--chapters chapters.txt | --clear-chapters | --auto-chapters]
+                  [--min-chapter S] [--max-chapters N] [--from silence|scenes|both]
+                  [--silence-threshold dB] [--silence-min S] [--scene-threshold N]
+                  [--chapters-out FILE] [--description-out FILE]
                   [--title T] [--artist A] [--album A] [--comment C] [--date D] [--genre G] [-o OUT]
 ```
 `chapters.txt` holds one chapter per line, `TIME TITLE` (cut.py's time syntax:
@@ -352,6 +382,27 @@ silently dropping them. Tags alone are written to any container that has them.
 `--clear-chapters` removes existing markers; an empty tag value (`--comment ""`)
 clears that tag.
 
+**Proposed chapters (1.16).** `--auto-chapters` measures the file's own
+structure instead of reading a file: silencedetect for the pauses (`--from
+silence`), scdet for the scene cuts (`--from scenes`), both by default. A
+chapter starts where speech resumes; a scene cut within 1 s of one is the same
+event and merges to `silence+scene` evidence, which `--max-chapters` never
+drops before a single-evidence marker. `--min-chapter` (default 60, a
+long-form default) is the shortest chapter, and nothing is proposed within it
+of the end of the file. **Two detectors mean two full decodes of the input**
+(`notes` says so); `--from silence` is the cheap path. Every title is
+`Chapter N` and the result says `"titles": "placeholder"`: the skill proposes
+where a chapter starts, it cannot know what is in one -- naming them is the
+caller's job, and asking this skill to do it is a refusal.
+`--chapters-out FILE` writes the proposal in this tool's own `--chapters`
+format, so the titles can be edited and fed straight back;
+`--description-out FILE` writes the YouTube block (`00:00 Chapter 1` per
+line, rounded down to the second). The output is still `-c copy`. An input
+with no video degrades to `--from silence` with a note; an explicit `--from
+scenes` on it is refused, as is `--from silence` on an input with no audio.
+The result gains `auto_chapters` (source, min_chapter, proposed, kept,
+titles, chapters with their evidence, description_block, files).
+
 ### grid.py — composite clips into a grid
 ```
 grid.py CLIP1 CLIP2 [...] --cols N --rows N [--cell-width W] [--cell-height H]
@@ -440,13 +491,13 @@ 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]
+          [--brand brand.json] [--chapters chapters.txt] [--image cover.png] [--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
+`$CUES`/`$SRT`, `$LOGO`, `$TITLE`, `$BRAND`, `$CHAPTERS` and `$IMAGE` 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
@@ -479,6 +530,7 @@ hand-built step:
 | `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 |
+| `audiogram` | 1920x1080 (16:9), or `--platform` / `--image` | 43200 s | -14 LUFS / -1 dBTP | 0.05 | 0.05 | 0.05 | 0.05 |
 
 `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,
@@ -487,6 +539,13 @@ linkedin, facebook` (not the audio template, not the `youtube-shorts` alias) int
 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`.
 
+`audiogram` (1.16) is the one-call form of the podcast-to-video job: an `audiogram` stage runs
+**first** (it makes the picture the rest of the chain works on, through `waveform.py --image`),
+then captions, loudness, export and check. It needs `--image` (a local file) or a `background`
+colour in the project — this skill fetches nothing and invents no cover art — and it is
+deliberately **not** part of `--template all`, whose destinations all assume a source that
+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]
@@ -551,9 +610,13 @@ graphics.py INPUT --template lower-third|title|chapter|progress|countdown|bug|st
             [--name] [--title] [--subtitle] [--text] [--top] [--bottom] [--duration 3]
             [--from N] [--start S] [--end E] [--position CORNER] [--margin PX] [--platform NAME]
             [--brand brand.json] [--primary RRGGBB] [--scale 1.0] [--lang XX]
-            [--text-render auto|ass|drawtext] [--write-ass OUT.ass]
+            [--wrap phrase|measured] [--text-render auto|ass|drawtext] [--write-ass OUT.ass]
             [--emoji auto|color|png|mono|none] [--emoji-assets DIR] [--emoji-scale 1.0] [--emoji-max 60] [-o OUT]
 ```
+Since 1.16 a label too wide for the frame is broken into lines by the same phrase-aware wrap
+caption.py uses (`--wrap phrase|measured`; see caption.py above) instead of running off the edge —
+the hook card, the meme lines and the sticker chip. A label that already fits is untouched.
+
 Drawn with drawbox/drawtext/overlay — no PNG assets needed. Sizes scale with
 the frame's short side; colours, font and safe margin come from `--brand`.
 Lower-third slides in over 0.4 s and out over 0.3 s; title/chapter/bug fade.
@@ -658,9 +721,10 @@ rather than about the file.
 
 ### caption.py — subtitles (static, animated, karaoke)
 ```
-caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
-           [--mode burn|mux] [--audio-stream N] [--fps N] [--lang XX] [--offset TIME]
-           [--max-lines N] [--min-duration S]
+caption.py INPUT --srt FILE[:LANG] | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
+           [--mode burn|mux] [--srt FILE:LANG ...] [--track-title T ...] [--default-track LANG]
+           [--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]
            [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N]
            [--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass]
@@ -708,6 +772,55 @@ comes from, but nothing is written until the real run. `--min-duration` and
 `--offset` also work with `--write-srt` alone; `--max-lines` does not, because
 wrapping needs the input video's real frame size.
 
+Phrase-aware breaking (1.16), `--wrap phrase` (default) — four rules over the
+break positions that already fit, so a line is never widened and the line count
+never changes: **R1** never inside a word, and a hyphenated token may break only
+after its hyphen (never after a non-breaking `‑`, nor a leading/trailing
+one); **R2** no line that is a lone digit, one or two punctuation characters, or
+a single kana, checked at every boundary rather than only the last; **R3** for
+Japanese and Chinese, a break is preferred after `。、！？」』）` and (Japanese
+only) after a particle — a particle attaches to the word before it, so kinsoku
+forbids opening a line with one — discouraged between a kanji stem and its
+okurigana, and forbidden before a small kana, `ー` or a closing bracket; **R4**
+for en/es/pt/fr/de/it, an article or preposition is kept with the phrase it
+governs: the break before it is preferred and the break after it penalised (a
+frozen table, matched case-folded; `--lang`, else the script detector, picks the
+set, and with no language the union of the six is used). `--wrap measured` is 1.15's
+width-only wrap exactly, kept so an older split can be reproduced. The result's
+`caption` object carries the layout counts plus `wrap` and `phrase_breaks`.
+graphics.py takes the same flag for the labels that can hold more than one line
+(the hook card, the meme lines, the sticker chip). The breaker never rewrites,
+shortens or translates the text: a cue that cannot fit `--max-lines` is split
+into consecutive cues, as it always was.
+
+Several languages in one file (1.16): `--srt` is repeatable and each file may
+carry a `:lang` suffix — `--mode mux --srt en.srt:en --srt ja.srt:ja --srt
+es.srt:es -o ep.mkv` writes one deliverable with three language-tagged,
+toggleable streams and copies the video and audio bit for bit. The suffix splits
+on the last colon, and only when the tail is a BCP-47-shaped code *and* the whole
+token is not itself a file on disk, so `C:\subs\en.srt` and a file named
+`a:b.srt` are never mangled; a single `--srt` with no suffix still takes
+`--language`. `--track-title` names a track (repeated in `--srt` order;
+otherwise a frozen display-name table, and a code the table does not know gets
+the code itself — never a guessed or translated name), `--default-track LANG`
+marks one for auto-selection. Every other new track is explicitly marked *not*
+default, because ffmpeg otherwise flags the first one itself -- so with no
+`--default-track` a Matroska file really does leave every track off. Two tracks with the same code, a
+code that is not BCP-47-shaped, a `--default-track` no track carries, and more
+than one `--srt` with `--mode burn` are all refused. **Container note:** `.mp4`
+and `.mov` accept several `mov_text` tracks but many players show only the
+first, and MPEG-4 stores an ISO-639-2 code — a two-letter one is silently
+dropped, so this tool converts it (`en` → `eng`); Matroska keeps the code you
+give. Past two tracks in an MPEG-4 container the result carries a note
+recommending `.mkv`. Two further MPEG-4 limits are reported rather than papered
+over: it has no per-track title the muxer writes back (so `tracks[].title` is
+`null` there, with a note) and it always enables its first subtitle track
+whatever disposition is asked for (so that track is reported `default: true`,
+again with a note). `.mkv` has neither limit. The result gains `tracks` and `subtitle_tracks`; check.py
+prints an informational `subtitles` row (WARN for an untagged stream, never
+counted in `failed`). The skill never translates and never generates a second
+language.
+
 Fonts by script (1.12): with no `--font` and no font named in your brand file, the
 script of the cue text (Japanese, Chinese, Korean, Arabic, Hebrew, Devanagari,
 Thai, Cyrillic, Greek) picks a font file that covers it, logged as `font: <file>

package/scripts/_common/__init__.py

@@ -66,11 +66,13 @@ from _common.emit import (
     PLAN_VERSION, print_json, _result_v2, _set_current_ctx, _V2_HANDLED, write_plan
 )
 from _common.probe import (
-    analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, fingerprint, _fraction, keyframes_near,
+    analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, detect_scenes, detect_silences, fingerprint,
+    _fraction, keyframes_near, SCORE_RE, SIL_RE,
     measured_level_dbfs, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output
 )
 from _common.decision import (
     aac_args, add_pad_fill_args, audio_codec_for, AUDIO_CODECS, brand_caption_style, BRAND_DEFAULTS,
+    description_block, _evidence_rank, fmt_chapter_time, propose_chapters,
     brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,
     fmt_secs, fmt_smpte_time, fmt_srt_time, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,
     signed_time_arg, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw
@@ -87,6 +89,13 @@ from _common.text import (
     font_for_script, FONT_INSTALL_HINT, fonts_dir_covers_script, has_emoji, _is_emoji_base, _is_emoji_char,
     _is_mark, _KEYCAP, _KEYCAP_BASES, LANGUAGE_NAMES, LATIN_EM, LEADING_VOWELS, _libass_color_probe, needs_shaping,
     NO_SPACE_SCRIPTS, PREFERRED_FAMILIES, resolve_emoji_assets, _SCRIPT_FONT_CACHE, _script_font_entry,
+    _atoms, best_break, _bare_word, break_penalty, _break_spaced, _cut_penalty, _fix_orphans, _fix_weak_lines,
+    _function_words, FUNCTION_WORDS, _HYPHENS, _is_hiragana, _is_ideograph, _is_kana, _is_weak_line,
+    JA_NO_LINE_END, JA_NO_LINE_START, JA_PARTICLE_WORDS, JA_PARTICLES, JA_SENTENCE_END, _join, ORPHAN_MIN_EM,
+    PENALTY_FORBIDDEN, PENALTY_FUNCTION_WORD, PENALTY_FUNCTION_WORD_START, PENALTY_IDEOGRAPHS,
+    PENALTY_NEUTRAL, PENALTY_OKURIGANA,
+    PENALTY_PARTICLE, PENALTY_SENTENCE_END, _rebalance, _rebalance_phrase, SAFE_WIDTH_FRACTION, _split_hyphens,
+    _particle_ends, _particle_starts, wrap_text, wrap_variants, WRAP_MODES,
     script_font_for_text, script_font_status, _script_font_uncached, _SCRIPT_RANGES, SCRIPTS, _SHAPING_BUILD_CACHE,
     SHAPING_SCRIPTS, text_width_em, _VS15, _VS16, WINDOWS_FONTS, _ZWJ
 )
@@ -153,12 +162,12 @@ sys.modules[__name__].__class__ = _Facade
 __all__ = [
     "Any", "Dict", "Fraction", "List", "Optional", "Path", "Sequence", "Tuple", "argparse", "json", "math", "os",
     "platform", "re", "shutil", "subprocess", "sys", "unicodedata",
-    "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "apply_common", "_aspect_string",
+    "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "apply_common", "detect_scenes", "detect_silences", "SCORE_RE", "SIL_RE", "_aspect_string",
     "audio_codec_for", "AUDIO_CODECS", "BIDI_SCRIPTS", "_bit_depth", "brand_caption_style", "BRAND_DEFAULTS",
     "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_tag_args", "cfr_args", "_char_em",
     "char_script", "_check_existing_output", "_check_no_overwrite_input", "_check_output_path", "child_args",
     "child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
-    "concat_list_line", "Context", "_CRF_DEFAULT", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono",
+    "concat_list_line", "Context", "_CRF_DEFAULT", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",
     "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw",
     "_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
     "dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
@@ -183,5 +192,13 @@ __all__ = [
     "_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em",
     "time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "_V2_HANDLED", "validate_color", "verify_output",
     "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",
-    "_x264_raw", "_ZWJ"
+    "_x264_raw", "_ZWJ",
+    "_atoms", "best_break", "_bare_word", "break_penalty", "_break_spaced", "_cut_penalty", "_fix_orphans",
+    "_fix_weak_lines", "_function_words", "FUNCTION_WORDS", "_HYPHENS", "_is_hiragana", "_is_ideograph",
+    "_is_kana", "_is_weak_line", "JA_NO_LINE_END", "JA_NO_LINE_START", "JA_PARTICLE_WORDS", "JA_PARTICLES",
+    "PENALTY_FUNCTION_WORD_START",
+    "JA_SENTENCE_END", "_join", "ORPHAN_MIN_EM", "PENALTY_FORBIDDEN", "PENALTY_FUNCTION_WORD",
+    "PENALTY_IDEOGRAPHS", "PENALTY_NEUTRAL", "PENALTY_OKURIGANA", "PENALTY_PARTICLE", "PENALTY_SENTENCE_END",
+    "_rebalance", "_rebalance_phrase", "SAFE_WIDTH_FRACTION", "_split_hyphens", "_particle_ends",
+    "_particle_starts", "wrap_text", "wrap_variants", "WRAP_MODES"
 ]

package/scripts/_common/decision.py

@@ -10,7 +10,7 @@ import json
 import os
 import argparse
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Sequence
 from _common.color import bt709_tag_args, _sdr_bt709
 from _common.emit import die
 from _common.runner import CODECS, STATE, ffmpeg_encoders
@@ -413,3 +413,108 @@ def brand_caption_style(brand: Dict[str, Any]) -> Dict[str, Any]:
         style["color"] = style.pop("colour")
     style.pop("colour", None)
     return style
+
+
+# ------------------------------------------------------------------- chapter proposal (1.16)
+
+def fmt_chapter_time(t: float) -> str:
+    """The YouTube description convention: `00:00`, `03:12`, `1:02:03` past the hour, always
+    rounded DOWN to the second so the timestamp never lands after the moment it names."""
+    total = max(0, int(t))
+    h, rem = divmod(total, 3600)
+    m, sec = divmod(rem, 60)
+    if h:
+        return f"{h}:{m:02d}:{sec:02d}"
+    return f"{m:02d}:{sec:02d}"
+
+
+def _evidence_rank(ev: Dict[str, Any]) -> tuple:
+    """How strong a candidate is, for the drop order: both detectors beat a silence, a silence
+    beats a scene cut, and within a kind the longer pause / higher score wins."""
+    kind = ev.get("kind")
+    tier = {"start": 3, "silence+scene": 2, "silence": 1, "scene": 0}.get(kind, 0)
+    within = float(ev.get("silence_length") or ev.get("score") or 0.0)
+    return (tier, within)
+
+
+def propose_chapters(duration: float, silences: "Sequence", scene_cuts: "Sequence", *,
+                     min_chapter: float = 60.0, max_chapters: int = 0,
+                     source: str = "both") -> "List[Dict[str, Any]]":
+    """Chapter markers proposed from measured structure. Pure: the detectors' outputs go in,
+    a list of `{"at", "title", "evidence"}` comes out, and nothing is decoded here.
+
+    A chapter starts where speech RESUMES, so a silence contributes its `end`, not its midpoint.
+    A scene cut within 1 s of such a point is the same event seen twice and is merged into one
+    candidate with `kind: "silence+scene"`, which the `--max-chapters` cap never drops before a
+    single-evidence one. Candidates closer than `min_chapter` to the one already kept are dropped,
+    stronger evidence winning; so is anything inside `min_chapter` of the end of the file.
+
+    Every title is `Chapter N`. The function never looks at, and never invents, content: naming a
+    chapter needs knowing what is said in it, which is the calling agent's job, not this skill's.
+    """
+    duration = float(duration or 0.0)
+    min_chapter = max(0.0, float(min_chapter))
+    candidates: "List[Dict[str, Any]]" = []
+    if source in ("silence", "both"):
+        for span in silences or []:
+            start, end = float(span[0]), span[1]
+            if end is None or end == float("inf"):
+                continue
+            end = float(end)
+            candidates.append({"at": end, "evidence": {
+                "kind": "silence", "silence": [round(start, 3), round(end, 3)],
+                "silence_length": round(end - start, 3)}})
+    if source in ("scenes", "both"):
+        for cut in scene_cuts or []:
+            cut = float(cut)
+            if cut <= 0.0:
+                continue     # scenes.py always reports 0.0 as the first cut; that is the start
+            candidates.append({"at": cut, "evidence": {"kind": "scene", "scene_at": round(cut, 3)}})
+
+    # merge a scene cut that stands within 1 s of a silence end: one event, two witnesses
+    candidates.sort(key=lambda c: c["at"])
+    merged: "List[Dict[str, Any]]" = []
+    for cand in candidates:
+        prior = merged[-1] if merged else None
+        if prior and abs(cand["at"] - prior["at"]) <= 1.0 and \
+                {prior["evidence"]["kind"], cand["evidence"]["kind"]} == {"silence", "scene"}:
+            ev = dict(prior["evidence"])
+            ev.update(cand["evidence"])
+            ev["kind"] = "silence+scene"
+            silence_first = prior["evidence"]["kind"] == "silence"
+            prior["at"] = prior["at"] if silence_first else cand["at"]
+            prior["evidence"] = ev
+            continue
+        merged.append(dict(cand))
+
+    kept: "List[Dict[str, Any]]" = [{"at": 0.0, "evidence": {"kind": "start"}}]
+    for cand in merged:
+        if duration and cand["at"] >= duration - min_chapter:
+            continue
+        last = kept[-1]
+        if cand["at"] - last["at"] < min_chapter:
+            # too close to the marker already kept: keep whichever the evidence supports better,
+            # never replacing the 0.0 start
+            if last["evidence"]["kind"] != "start" and \
+                    _evidence_rank(cand["evidence"]) > _evidence_rank(last["evidence"]) and \
+                    (len(kept) < 2 or cand["at"] - kept[-2]["at"] >= min_chapter):
+                kept[-1] = dict(cand)
+            continue
+        kept.append(dict(cand))
+
+    if max_chapters and len(kept) > max_chapters:
+        # drop the weakest evidence first, never index 0, then put the survivors back in order
+        order = sorted(range(1, len(kept)),
+                       key=lambda i: (_evidence_rank(kept[i]["evidence"]), -kept[i]["at"]))
+        drop = set(order[:len(kept) - max_chapters])
+        kept = [c for i, c in enumerate(kept) if i not in drop]
+
+    for n, chapter in enumerate(kept, start=1):
+        chapter["at"] = round(chapter["at"], 3)
+        chapter["title"] = f"Chapter {n}"
+    return kept
+
+
+def description_block(chapters: "Sequence") -> str:
+    """The YouTube description form of a chapter list: `00:00 Chapter 1` per line."""
+    return "\n".join(f"{fmt_chapter_time(c['at'])} {c['title']}" for c in chapters)