ffmpeg-skill 1.23.0 → 1.24.1

package/README.md

@@ -345,6 +345,8 @@ On Windows, `python3` is only on PATH if Python was installed from the Microsoft
 
 `FFMPEG_SKILL_MCP_LEAN=1` in the server's environment drops `json` and `progress` from every `inputSchema`: they are transport flags the server sets itself, not tool arguments, and 2.0 drops them unconditionally. It is opt-in, independent of `FFMPEG_SKILL_MCP_FULL`, and the default `tools/list` stays byte-identical (aside from the core-12 filter) to the CLI surface the contract promises.
 
+The server also advertises a `prompts` capability: five canned workflow recipes an agent can ask for by name instead of composing the individual tool calls itself — `reel`, `podcast`, `multicam`, `delivery_check`, `hdr`. `prompts/list` returns each one's name, description and arguments; `prompts/get {name, arguments}` fills the matching template and returns one text message naming the actual command lines to run and what to check afterward. These are recipes, not new tool calls — every command line a prompt names is one `tools/call` (or the CLI) can already run.
+
 ### Capability detection
 
 ```bash

package/SKILL.md

@@ -62,93 +62,93 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 
 | User says | Do |
 |-----------|----|
-| "what's in this file", "how long is it" | `probe.py input.mp4` |
 | "cut from 1:20 to 2:05", "trim the first 10 s" | `cut.py input.mp4 --start 1:20 --end 2:05` |
 | "keep only these parts", "remove the middle" | `cut.py input.mp4 --segments 0-1:00,1:30-2:00` |
 | "make it exactly 60 seconds" | `fit.py input.mp4 --duration 60` (speed) or `--method trim` |
+| "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`) |
+| "cut out the pauses", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` |
+| "cut the ums and uhs", "remove the filler words" | `silence.py input.mp4 --filler --words words.json` (measured word timings; `--transcribe` makes them) |
+| "don't cut inside a sentence, just the real pauses" | `silence.py input.mp4 --speech-aware` — a breath under `--min-silence` inside a sentence is kept, only sentence-boundary pauses cut; composes with `--filler` into one list |
+| "a 60 s highlight from this hour" | `scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt` → `cut.py --segments` |
+| "cut on the beat", "edit it to the music" | `scenes.py track.mp4 --beats --json > beats.json`, then `cut.py input.mp4 --segments ... --snap beats --snap-source beats.json` (`--snap-source` carries the measured grid over) |
+| "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` |
+| "hold on this frame", "freeze the last frame" | `freeze.py clip.mp4 --hold 2` |
+| "smooth slow motion", "half speed but fluid" | `fit.py input.mp4 --duration 2x --smooth interpolate` (slow) or `--smooth blend` |
+| "reverse this clip" | `reverse.py input.mp4` |
+| "loop this clip to fill 30 seconds" | `loop.py bg_loop.mp4 --duration 30` |
 | "make it vertical / 9:16 / square" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`; `--pad-fill blur` for blurred bars) |
 | "resize to a height/width" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) |
 | "crop to this exact box" (known x/y/w/h) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` |
-| "are there black bars on this?" | `cropdetect.py input.mp4` |
+| "blurred background instead of black bars" | `fit.py input.mp4 --aspect 9:16 --fit blur` (whole picture kept, borders a blurred, darkened copy) |
+| "rotate 90 degrees", "mirror it" | `fit.py input.mp4 --rotate 90` / `fit.py input.mp4 --flip h` |
+| "the horizon is tilted" (known degrees) | `straighten.py tilted.mp4 --degrees -2.5` |
+| "flat view out of this 360 video" (known yaw/pitch/fov) | `sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70` |
 | "this old footage is interlaced" | `deinterlace.py input.mp4` |
 | "it's grainy/noisy, clean it up" | `denoise.py input.mp4 --strength medium` |
 | "blur/pixelate this face/plate" (known box) | `redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate` |
-| "flat view out of this 360 video" (known yaw/pitch/fov) | `sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70` |
-| "the horizon is tilted" (known degrees) | `straighten.py tilted.mp4 --degrees -2.5` |
-| "turn this image into a clip", "title card" | `insert.py title.png --duration 3` |
-| "slow zoom on a photo", "Ken Burns" | `insert.py photo.jpg --duration 6 --zoom in --pan right --width 1920 --height 1080` |
-| "rotate 90 degrees", "mirror it" | `fit.py input.mp4 --rotate 90` / `fit.py input.mp4 --flip h` |
-| "reverse this clip" | `reverse.py input.mp4` |
 | "stabilize this shaky footage" | `stabilize.py input.mp4` |
-| "make a blank/colour background clip" | `background.py -o bg.mp4 --duration 3 --width 1920 --height 1080 --color 0x101010` |
-| "turn these numbered frames into a video" | `sequence.py --dir frames --pattern "frame_%04d.png" --fps 24` |
-| "waveform/spectrum video for this track" | `waveform.py podcast.wav -o waveform.mp4` |
-| "hold on this frame", "freeze the last frame" | `freeze.py clip.mp4 --hold 2` |
-| "add black at the start" | `pad.py clip.mp4 --start 1.5` |
-| "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"`). `--auto-chapters` proposes them from measured pauses/scene cuts, titled `Chapter N`, renameable |
-| "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` |
+| "are there black bars on this?" | `cropdetect.py input.mp4` |
+| "iPhone Dolby Vision clip looks wrong" | `color.py clip.mov --to-sdr` or `--strip-dovi` (keep HDR, drop the DV layer) |
+| "the colours look washed out / iPhone HDR" | `color.py input.mov --to-sdr` (probe shows `hdr: true`) |
+| "apply this LUT", "convert the S-Log footage" | `color.py input.mp4 --lut grade.cube [--lut-strength 0.7]` |
+| "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (stream copy; re-encodes only if the copy can't carry it — see `reencoded`) |
+| "brighten it / punch up contrast / fix white balance" | `color.py input.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05` |
 | "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", "don't chop the sentence" | `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). Keep the template's `--max-lines` (2 on a vertical) and let the size drop; raising it to dodge a shrink stacks two words per line. A word still wider than the column at the floor is sliced at the edge (hyphen preferred), never rewritten, automatic; `broken_inside_word` in the JSON counts it |
+| "transcribe it and caption it" | `caption.py input.mp4 --transcribe --animate pop --karaoke` (needs a local whisper; else `--text`) |
+| "TikTok-style captions with the words popping" | `caption.py input.mp4 --text cues.txt --animate pop --karaoke` |
 | "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 colour, nothing is fetched |
+| "a lower third with my name", "countdown intro", "progress bar" | `graphics.py input.mp4 --template lower-third --name "..." --title "..." --start 2 --end 8` |
+| "a sticker", "a hook card for the first 3 s", "meme text" | `graphics.py input.mp4 --template sticker --text "NEW" --platform tiktok` / `--template hook --title "..." --duration 3` / `--template meme --top "..." --bottom "..."` |
+| "use our brand fonts/colours/logo" | `--brand brand.json` on caption/overlay/graphics, or `"brand"` in project.json |
 | "sync the lav mic", "line up two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second`; a third+ recorder is another positional (`sync.py ref.mp4 mic.wav cam2.mp4`), one offsets JSON |
 | "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`) |
+| "clean up the audio", "remove the hiss" | `audio.py input.mp4 --voice` (speech; `--voice light\|medium\|strong`) or `--denoise` |
+| "add background music under the talking" | `audio.py input.mp4 --music bed.mp3 --duck --fade-out 3` (`--effects sfx.wav` adds a third bed, never ducked; project levels: `audio.stems`) |
+| "make the music duck harder / come back faster" | add `--duck-amount 18 --duck-threshold -30 --duck-release 250` (`--duck-attack` too) |
+| "the mix sounds narrow", "wider stereo" | `audio.py band.wav --stereo-widen 0.5` (needs a real stereo source; 5.1 needs `--downmix`) |
+| "convert the 5.1 to stereo" | `audio.py input.mov --downmix` |
+| "swap in the narration track" | `audio.py input.mp4 --replace narration.wav` |
+| "pull the audio out", "give me the sound as WAV" | `audio.py input.mp4 -o input.wav` (an audio extension drops the picture; `--audio-stream 1` picks a track) |
+| "compress the voice", "limit the peaks", "gate the room noise" | `audio.py input.mp4 --compress --comp-threshold -20 --comp-ratio 4` / `--limit --limit-ceiling -1` / `--gate --gate-threshold -45` |
+| "the audio drifts out of sync over the hour" | `sync.py camera.mp4 recorder.wav --fix-drift --replace-audio` |
+| "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 colour, nothing is fetched |
 | "make this a TikTok / Reel / Short / YouTube / X / LinkedIn / podcast" | `render.py --template tiktok\|reels\|shorts\|youtube-shorts\|youtube\|x\|linkedin\|facebook\|podcast input.mp4 [--cues cues.txt] [--title "..."]` — frame, captions, loudness, export and check in one command (`--list-templates`, `--write-project` to edit first) |
 | "post it everywhere", "one edit for every platform" | `render.py --template all input.mp4 --cues cues.txt` (or a comma list) → one file per destination plus `<name>_pack.md` (`report.py --pack` renders the HTML) |
 | "export for YouTube / Reels / X", "a ProRes master" | `export.py input.mp4 --preset youtube\|reels\|tiktok\|shorts\|linkedin\|facebook\|x\|prores\|h265` (`--normalize` hits the loudness spec in the same call; `youtube-hdr` keeps HDR, `youtube-av1` writes AV1) |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
 | "a small proxy / cheap preview file" | `proxy.py input.mp4 [--width 640 --no-audio]` — not a delivery preset (that is `export.py`) |
-| "cut out the pauses", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` |
-| "cut the ums and uhs", "remove the filler words" | `silence.py input.mp4 --filler --words words.json` (measured word timings; `--transcribe` makes them) |
-| "don't cut inside a sentence, just the real pauses" | `silence.py input.mp4 --speech-aware` — a breath under `--min-silence` inside a sentence is kept, only sentence-boundary pauses cut; composes with `--filler` into one list |
-| "stitch these clips", "add a crossfade" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
-| "show me what it looks like", "are the captions readable" | `look.py output.mp4 --tiles 3x2`, then view the PNG |
-| "what would you run?", "don't render yet" | any script with `--dry-run` |
-| "a 60 s highlight from this hour" | `scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt` → `cut.py --segments` |
-| "cut on the beat", "edit it to the music" | `scenes.py track.mp4 --beats --json > beats.json`, then `cut.py input.mp4 --segments ... --snap beats --snap-source beats.json` (`--snap-source` carries the measured grid over) |
-| "which shots are static vs moving", "volume peaks per second", "is this speech or music" | `scenes.py input.mp4 --shots` (static/pan/motion per shot, measured flow) / `--audio-peaks` (dBFS list) / `--speech` (a speech-vs-music ratio, not a classification) — combine, or alone |
-| "where does the subject move, so I can crop it myself" | `cropdetect.py input.mp4 --motion-centre` — motion centroid per second, report-only; the calling agent picks the crop |
 | "is this OK to upload?" | `check.py final.mp4 --platform reels` |
 | "a podcast episode with chapters" | `loudness.py ep.wav -I -16 --tp -1.5` → `metadata.py ep.m4a --chapters chapters.txt` → `check.py ep.m4a --platform podcast` (chapters and channels rows) |
+| "send me a summary of what you did" | `report.py --before raw.mov --after final.mp4 --platform youtube -o report.html` |
+| "turn this image into a clip", "title card" | `insert.py title.png --duration 3` |
+| "slow zoom on a photo", "Ken Burns" | `insert.py photo.jpg --duration 6 --zoom in --pan right --width 1920 --height 1080` |
+| "make a blank/colour background clip" | `background.py -o bg.mp4 --duration 3 --width 1920 --height 1080 --color 0x101010` |
+| "turn these numbered frames into a video" | `sequence.py --dir frames --pattern "frame_%04d.png" --fps 24` |
+| "waveform/spectrum video for this track" | `waveform.py podcast.wav -o waveform.mp4` |
+| "add black at the start" | `pad.py clip.mp4 --start 1.5` |
+| "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"`). `--auto-chapters` proposes them from measured pauses/scene cuts, titled `Chapter N`, renameable |
+| "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` |
+| "stitch these clips", "add a crossfade" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
 | "several changes to the same edit", 3+ steps | `render.py --init project.json`, edit, `render.py project.json` |
 | "I changed one stage, don't redo the rest" | `render.py project.json --cache DIR` — identical stages come from the cache (`--from STAGE` starts there) |
-| "a lower third with my name", "countdown intro", "progress bar" | `graphics.py input.mp4 --template lower-third --name "..." --title "..." --start 2 --end 8` |
-| "a sticker", "a hook card for the first 3 s", "meme text" | `graphics.py input.mp4 --template sticker --text "NEW" --platform tiktok` / `--template hook --title "..." --duration 3` / `--template meme --top "..." --bottom "..."` |
-| "blurred background instead of black bars" | `fit.py input.mp4 --aspect 9:16 --fit blur` (whole picture kept, borders a blurred, darkened copy) |
-| "use our brand fonts/colours/logo" | `--brand brand.json` on caption/overlay/graphics, or `"brand"` in project.json |
-| "send me a summary of what you did" | `report.py --before raw.mov --after final.mp4 --platform youtube -o report.html` |
 | "do this to every file in the folder", "use all the cores" | `batch.py FOLDER --recipe batch.json --jobs auto` (steps or a render project; cached) |
-| "transcribe it and caption it" | `caption.py input.mp4 --transcribe --animate pop --karaoke` (needs a local whisper; else `--text`) |
 | "three cameras, cut between them" | `multicam.py camA.mp4 camB.mp4 camC.mp4 --switch "0-20:0,20-40:1,40-60:2"` (manual) or `--switch energy` (auto-cuts to the loudest camera, `--min-shot`, `--edl`) |
-| "iPhone Dolby Vision clip looks wrong" | `color.py clip.mov --to-sdr` or `--strip-dovi` (keep HDR, drop the DV layer) |
+| "what's in this file", "how long is it" | `probe.py input.mp4` |
+| "show me what it looks like", "are the captions readable" | `look.py output.mp4 --tiles 3x2`, then view the PNG |
+| "what would you run?", "don't render yet" | any script with `--dry-run` |
+| "which shots are static vs moving", "volume peaks per second", "is this speech or music" | `scenes.py input.mp4 --shots` (static/pan/motion per shot, measured flow) / `--audio-peaks` (dBFS list) / `--speech` (a speech-vs-music ratio, not a classification) — combine, or alone |
+| "where does the subject move, so I can crop it myself" | `cropdetect.py input.mp4 --motion-centre` — motion centroid per second, report-only; the calling agent picks the crop |
 | "does it look like Log / S-Log?" | `probe.py clip.mp4 --analyze` (`looks_like_log`) then `color.py --lut` |
 | "test the tool on my real files" | `verify.py ~/Footage --report verify.md` |
 | "show me progress", "quick preview first" | any encoding script with `--progress` and/or `--fast` |
-| "the colours look washed out / iPhone HDR" | `color.py input.mov --to-sdr` (probe shows `hdr: true`) |
-| "apply this LUT", "convert the S-Log footage" | `color.py input.mp4 --lut grade.cube [--lut-strength 0.7]` |
-| "the colours are tagged wrong" | `color.py input.mp4 --retag bt709` (stream copy; re-encodes only if the copy can't carry it — see `reencoded`) |
-| "brighten it / punch up contrast / fix white balance" | `color.py input.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05` |
-| "clean up the audio", "remove the hiss" | `audio.py input.mp4 --voice` (speech; `--voice light\|medium\|strong`) or `--denoise` |
-| "add background music under the talking" | `audio.py input.mp4 --music bed.mp3 --duck --fade-out 3` (`--effects sfx.wav` adds a third bed, never ducked; project levels: `audio.stems`) |
-| "make the music duck harder / come back faster" | add `--duck-amount 18 --duck-threshold -30 --duck-release 250` (`--duck-attack` too) |
-| "the mix sounds narrow", "wider stereo" | `audio.py band.wav --stereo-widen 0.5` (needs a real stereo source; 5.1 needs `--downmix`) |
-| "convert the 5.1 to stereo" | `audio.py input.mov --downmix` |
-| "swap in the narration track" | `audio.py input.mp4 --replace narration.wav` |
-| "pull the audio out", "give me the sound as WAV" | `audio.py input.mp4 -o input.wav` (an audio extension drops the picture; `--audio-stream 1` picks a track) |
-| "compress the voice", "limit the peaks", "gate the room noise" | `audio.py input.mp4 --compress --comp-threshold -20 --comp-ratio 4` / `--limit --limit-ceiling -1` / `--gate --gate-threshold -45` |
-| "the audio drifts out of sync over the hour" | `sync.py camera.mp4 recorder.wav --fix-drift --replace-audio` |
-| "smooth slow motion", "half speed but fluid" | `fit.py input.mp4 --duration 2x --smooth interpolate` (slow) or `--smooth blend` |
-| "TikTok-style captions with the words popping" | `caption.py input.mp4 --text cues.txt --animate pop --karaoke` |
 | "it's a phone video with variable frame rate" | nothing extra: re-encodes conform VFR to constant fps; `fit.py --fps 30` picks the rate |
 
 ## Audio-only files

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.23.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.24.1`) | 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.23.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.23.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.23.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.23.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.23.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.24.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.24.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.24.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.24.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.24.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 |
 
 ## Skill
 
 ```json
 {
   "contract_version": "1.0",
-  "deprecated": [{"what": "...", "since": "1.23.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.23.0", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.24.1", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.24.1", "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"},
@@ -120,7 +120,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | Field | Meaning |
 |---|---|
 | `id`, `name`, `version`, `executable` | `ffmpeg-skill/cut`, `cut`, skill version, `scripts/cut.py` |
-| `examples[]` | `{prompts[], command}` (1.23.0): SKILL.md's own "User says" / "Do" table rows for this tool, machine-readable — `prompts` is the row's phrasing(s), `command` the row's `Do` text with the markdown backticks stripped. Every tool has at least one; parsed from SKILL.md at read time, so it never drifts from the table a person reads |
+| `examples[]` | `{prompts[], command}` (1.24.1): SKILL.md's own "User says" / "Do" table rows for this tool, machine-readable — `prompts` is the row's phrasing(s), `command` the row's `Do` text with the markdown backticks stripped. Every tool has at least one; parsed from SKILL.md at read time, so it never drifts from the table a person reads |
 | `role` | `analysis`, `analysis_and_execution`, `execution` or `verification` (see below) |
 | `capabilities.required` | ffmpeg components the tool always needs |
 | `capabilities.optional[]` | `{capability, when}`: needed only for that flag or input |
@@ -129,7 +129,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.23.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.24.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 |
 | `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 |
@@ -435,7 +435,7 @@ 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. `broken_inside_word` (1.23.0) counts atoms hard-sliced at the live column's edge because they did not fit alone even at the size floor — never a rewrite, the sliced pieces are the exact original characters. `overlong` is now residual: it fires only when even a single character is wider than the column |
+| `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. `broken_inside_word` (1.24.1) counts atoms hard-sliced at the live column's edge because they did not fit alone even at the size floor — never a rewrite, the sliced pieces are the exact original characters. `overlong` is now residual: it fires only when even a single character is wider than the column |
 | `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 |
@@ -451,7 +451,7 @@ Per-tool keys added in 1.17, all additive:
 | `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 |
 
-Per-tool keys added in 1.23.0, all additive:
+Per-tool keys added in 1.24.1, all additive:
 
 | key | tool | what it holds |
 |---|---|---|
@@ -459,7 +459,7 @@ Per-tool keys added in 1.23.0, all additive:
 | `text_unchanged` | `caption.py` | a sibling inside the `caption` block, **burn mode only** (`--mode mux` never touches the text and omits the key): `true` when the drawn text equals the cues that were handed in — nothing transcribed, no cue dropped, no cue **split** across two consecutive cues and no glyph stripped (`--emoji none`). Wrapping, line breaks and timing do not count: the words are the same. This tool never rewrites, shortens or translates a cue, so the key is a statement of what happened, not a judgement of the text |
 
 
-Per-tool keys added in 1.23.0, all additive:
+Per-tool keys added in 1.24.1, all additive:
 
 | key | tool | what it holds |
 |---|---|---|
@@ -593,7 +593,21 @@ most often across the corpus in `evals/agent_prompts*.json`. Every tool -- inclu
 -- is still callable by name through `tools/call` regardless of what `tools/list` advertised; the
 contract (`ffmpeg-skill contract --json`) still describes all 42 unconditionally. Set
 `FFMPEG_SKILL_MCP_FULL=1` (anything but "" or `0`) in the server's environment to make `tools/list`
-return all 42, as every version before 1.23.0 did.
+return all 42, as every version before 1.24.1 did.
+
+### `prompts` capability: five workflow recipes
+
+Roadmap 1.20.0 "agent ergonomics": the server advertises `capabilities.prompts` in `initialize`
+and answers `prompts/list` / `prompts/get` with five canned workflows an agent can ask for by
+name instead of composing the individual tool calls itself: `reel`, `podcast`, `multicam`,
+`delivery_check`, `hdr`. `prompts/list` returns each one's `name`, `description` and `arguments`
+(from `_contract.MCP_PROMPTS`); `prompts/get {name, arguments}` fills the matching template and
+returns one user-role text message naming the actual command lines to run and what to check
+afterward -- the same facts SKILL.md's own request table states, addressed by workflow instead of
+by request phrasing. A missing required argument is a JSON-RPC error (`prompts/get` never guesses
+a path or a platform); an unknown prompt name is a JSON-RPC error too, distinct from "method not
+found" since `prompts/get` itself is a real method. These are recipes, not new tool calls: every
+command line a prompt names is one `tools/call` (or the CLI) can already run.
 
 ## Consuming the contract from an agent
 

package/mcp/server.py

@@ -150,13 +150,24 @@ def handle(req: Dict[str, Any]) -> Dict[str, Any]:
         # 1.20.0: the structured-arguments note used to be appended to every one of the 42 tool
         # descriptions verbatim; it's server-wide, not per-tool, so it now lives here once instead
         # -- `tools/list` descriptions stay each tool's own one-line sentence.
-        return {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}},
+        return {"protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {}, "prompts": {}},
                 "serverInfo": {"name": "ffmpeg-skill", "version": version()},
                 "instructions": _contract.MCP_STRUCTURED_NOTE}
     if method == "tools/list":
         return {"tools": tool_list()}
     if method == "tools/call":
         return call_tool(params.get("name", ""), params.get("arguments") or {})
+    if method == "prompts/list":
+        # roadmap 1.20.0: the five workflow recipes (reel, podcast, multicam, delivery_check, hdr)
+        return {"prompts": _contract.mcp_prompt_list()}
+    if method == "prompts/get":
+        try:
+            return _contract.mcp_prompt_get(params.get("name", ""), params.get("arguments") or {})
+        except KeyError as exc:
+            # not "method not found" (-32601, handle()'s own KeyError below): the *method*
+            # prompts/get exists, only this prompt *name* doesn't -- a caller mistake, same as
+            # call_tool()'s "unknown tool" text, not a transport-level error.
+            raise ValueError(f"unknown prompt: {exc}") from exc
     if method == "ping":
         return {}
     raise KeyError(method)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.23.0",
+  "version": "1.24.1",
   "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/scripts/_contract.py

@@ -1128,6 +1128,92 @@ MCP_STRUCTURED_NOTE = ("Structured arguments: keys are the input_schema property
                        "are passed by name, output -> -o. Or argv: the raw CLI list (non-canonical; all other keys are then ignored). "
                        "Media paths must be absolute.")
 
+# roadmap 1.20.0 "agent ergonomics": a `prompts` capability with the five workflows an agent asks
+# for most often (per the SKILL.md request table these are built from -- see skill_examples()'s
+# own source, not a separate hand-picked list). Each `template` is filled with `{name}` -> the
+# matching argument's value; a missing optional argument's `{name}` is dropped along with the
+# surrounding text named in `optional` (so "no chapters file" doesn't leave a dangling clause).
+# The five are recipes, not new tool calls -- every command line named is one this skill already
+# runs; `prompts/get` hands back the same facts SKILL.md's own table states, just addressed by
+# workflow instead of by request phrasing.
+MCP_PROMPTS: List[Dict[str, Any]] = [
+    {
+        "name": "reel", "description": "Turn a clip into a captioned vertical delivery (TikTok/Reels/Shorts) and verify it.",
+        "arguments": [{"name": "input", "description": "path to the source video", "required": True},
+                      {"name": "platform", "description": "tiktok | reels | shorts | youtube-shorts (default reels)", "required": False, "default": "reels"},
+                      {"name": "cues", "description": "path to a captions cue file, if the clip needs captions", "required": False}],
+        "optional": {"cues": " with cues from {cues}"},
+        "template": ("Turn {input} into a {platform} deliverable: run `render.py --template {platform} {input}`{cues}, "
+                     "which handles frame, captions, loudness and export in one command. Then verify with "
+                     "`check.py <output> --platform {platform}` before calling it done -- format rows (codec, pixel "
+                     "format, size, true peak, colour tags, VFR) are safe to fix; judgement rows (duration, aspect, "
+                     "fps, loudness) change content, so fix them only when the request implies the answer, otherwise "
+                     "state the choice and its cost. Mention WARNs; do not chase them."),
+    },
+    {
+        "name": "podcast", "description": "Turn an audio recording into a loudness-normalised podcast episode with chapters.",
+        "arguments": [{"name": "input", "description": "path to the source audio", "required": True},
+                      {"name": "chapters", "description": "path to a chapters timing file", "required": False}],
+        "optional": {"chapters": " with chapters from `metadata.py <output> --chapters {chapters}`"},
+        "template": ("Turn {input} into a podcast episode: normalise loudness with `loudness.py {input} -I -16 --tp -1.5`"
+                     "{chapters}, then verify with `check.py <output> --platform podcast` (its chapters and channels rows)."),
+    },
+    {
+        "name": "multicam", "description": "Cut between several camera angles of the same scene.",
+        "arguments": [{"name": "inputs", "description": "the camera files, space-separated", "required": True}],
+        "optional": {},
+        "template": ("Cut between the cameras in {inputs}: `multicam.py {inputs} --switch energy` auto-cuts to the "
+                     "loudest camera at each moment (`--min-shot` sets the shortest allowed shot); a manual spec "
+                     "looks like `--switch \"0-20:0,20-40:1,40-60:2\"`. Check the reported sync confidence per camera "
+                     "-- under 0.3 (or a large offset) is suspect and needs a manual look; these align audio, never lip sync."),
+    },
+    {
+        "name": "delivery_check", "description": "Verify a finished file is ready to upload to a platform.",
+        "arguments": [{"name": "input", "description": "path to the file to check", "required": True},
+                      {"name": "platform", "description": "youtube | reels | tiktok | shorts | x | linkedin | facebook | podcast", "required": True}],
+        "optional": {},
+        "template": ("Verify {input} is ready for {platform}: run `check.py {input} --platform {platform}`. Format "
+                     "rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix automatically. "
+                     "Judgement rows (duration, aspect, fps, loudness) change content -- fix only when the request "
+                     "implies the answer, otherwise state the choice and its cost. Mention WARNs; do not chase them."),
+    },
+    {
+        "name": "hdr", "description": "Bring an HDR or Dolby Vision clip down to SDR (or strip only the DV layer).",
+        "arguments": [{"name": "input", "description": "path to the HDR/Dolby Vision source", "required": True},
+                      {"name": "strip_dovi", "description": "true to keep HDR and drop only the Dolby Vision layer, instead of converting to SDR", "required": False}],
+        "optional": {},
+        "template": ("Bring {input} from HDR/Dolby Vision down to SDR: `color.py {input} --to-sdr` (or `--strip-dovi` "
+                     "to keep HDR and only drop the Dolby Vision layer, when strip_dovi is asked for). A flat, washed-out "
+                     "look after a re-encode usually means HDR metadata was lost upstream; `probe` shows `hdr: true` "
+                     "for BT.2020 primaries or a PQ/HLG transfer, and `hdr_signal: true` only for a real PQ/HLG/DV transfer."),
+    },
+]
+
+
+def mcp_prompt_list() -> List[Dict[str, Any]]:
+    """`prompts/list`: name, description and arguments for each of MCP_PROMPTS -- everything but
+    the template, which `prompts/get` fills."""
+    return [{"name": p["name"], "description": p["description"], "arguments": p["arguments"]} for p in MCP_PROMPTS]
+
+
+def mcp_prompt_get(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    """`prompts/get`: the filled template as a single user-role text message. Raises KeyError for
+    an unknown prompt name (mirrors call_tool's own unknown-tool handling) and ValueError naming
+    the missing argument when a required one is absent -- both are caller mistakes, not server
+    failures, so the transport turns them into a JSON-RPC error rather than a crash."""
+    by_name = {p["name"]: p for p in MCP_PROMPTS}
+    if name not in by_name:
+        raise KeyError(name)
+    prompt = by_name[name]
+    missing = [a["name"] for a in prompt["arguments"] if a["required"] and not (arguments or {}).get(a["name"])]
+    if missing:
+        raise ValueError(f"prompt {name!r} needs {', '.join(missing)}")
+    fields: Dict[str, str] = {a["name"]: str((arguments or {}).get(a["name"]) or a.get("default", "")) for a in prompt["arguments"]}
+    for opt_name, clause in prompt["optional"].items():
+        fields[opt_name] = clause.format(**fields) if fields.get(opt_name) else ""
+    text = prompt["template"].format(**fields)
+    return {"description": prompt["description"], "messages": [{"role": "user", "content": {"type": "text", "text": text}}]}
+
 
 def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:
     """Translate a ToolSpec.input_schema into the JSON Schema an MCP tools/list entry carries.

package/scripts/caption.py

@@ -25,6 +25,7 @@ Text-to-SRT input format (one cue per line, blank lines ignored):
 Examples:
   python3 caption.py input.mp4 --srt subs.srt
   python3 caption.py input.mp4 --text cues.txt --animate pop --karaoke        # word-by-word highlight, TikTok style
+  python3 caption.py input.mp4 --text cues.txt --karaoke --karaoke-style word # active word scaled + emboldened, past/upcoming colours
   python3 caption.py input.mp4 --srt subs.srt --font "Noto Sans CJK JP" --size 28 --position top
   python3 caption.py --text cues.txt --write-srt cues.srt          # only produce the SRT
   python3 caption.py input.mp4 --text cues.txt                     # generate + burn in one go
@@ -464,9 +465,18 @@ def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[
 
     --size is in ASS points against a 288-line script (what libass's force_style uses), so the
     rendered pixel size is size * play_h / 288.
+
+    --karaoke-style word scales its active word up by --karaoke-scale and freezes the line break
+    (WrapStyle: 2 in write_ass) so libass can never re-wrap around that scale-up. The budget here
+    is narrowed by the same factor so the longest wrapped line -- computed at the UNscaled width --
+    still fits once its active word is drawn --karaoke-scale%% larger; without this, a line that
+    exactly filled the safe width would overflow it the moment its emphasised word appears.
     """
-    return line_em_for_size(args.size, play_w, play_h,
-                            safe_fraction=safe_width_fraction(args, play_w))
+    em = line_em_for_size(args.size, play_w, play_h,
+                          safe_fraction=safe_width_fraction(args, play_w))
+    if em is not None and getattr(args, "karaoke", False) and getattr(args, "karaoke_style", "sweep") == "word":
+        em = em / max(1.0, getattr(args, "karaoke_scale", 112) / 100.0)
+    return em
 
 
 def parse_ass_dialogue(path: str) -> str:
@@ -526,6 +536,23 @@ def word_durations_from_timings(words: List[Tuple[float, float, str]], start: fl
     return out
 
 
+def _karaoke_word_durations(args, video: Optional[str], start: float, end: float, n_words: int) -> List[int]:
+    """Centiseconds per word for one cue, shared by --karaoke-style sweep and word.
+
+    Real word timings from the transcript beat both the energy estimate and the even split --
+    they are what the speaker actually did, not a proxy for it.
+    """
+    dur_cs = max(1, int(round((end - start) * 100)))
+    durs = word_durations_from_timings(getattr(args, "_word_timings", None) or [], start, end, n_words)
+    if durs is None:
+        if getattr(args, "karaoke_timing", "even") == "energy" and video:
+            durs = word_durations_from_audio(video, start, end, n_words, getattr(args, "audio_stream", 0))
+        else:
+            per = max(1, dur_cs // max(1, n_words))
+            durs = [per] * n_words
+    return durs
+
+
 def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int, play_h: int, video: str = None) -> None:
     """Write a styled ASS file with optional animation and word-by-word highlight."""
     def t(sec: float) -> str:
@@ -544,8 +571,20 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
     secondary = ass_color(args.color)
     outline = ass_color(args.outline_color)
     back = ass_color(args.outline_color, 0x80)
+    word_style = args.karaoke and getattr(args, "karaoke_style", "sweep") == "word"
+    word_past = ass_color(args.color)
+    word_active = ass_color(args.highlight_color)
+    word_upcoming = ass_color(args.upcoming_color)
+    word_bord = f"{args.outline * scale * (max(1.0, args.karaoke_scale) / 100.0):.2f}"
+    word_scale = int(round(args.karaoke_scale))
+    # --karaoke-style word emits one Dialogue per word carrying the WHOLE cue with explicit \N
+    # breaks (the layout's own fixed line list -- see max_line_em's docstring). WrapStyle: 2 tells
+    # libass to honour only those explicit breaks and never re-wrap: with WrapStyle: 0 (the sweep
+    # default, unchanged), scaling the active word up would re-flow the line and it would visibly
+    # jump every time the highlight advances (the trap the issue this implements is filed against).
     header = [
-        "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}", "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
+        "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}",
+        f"WrapStyle: {2 if word_style else 0}", "ScaledBorderAndShadow: yes", "",
         "[V4+ Styles]",
         "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
         f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin_l},{margin_r},{margin},1",
@@ -579,20 +618,66 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         own = own_sizes[cue_index] if cue_index < len(own_sizes) else None
         if own and own != args.size:
             fx += "{\\fs%d}" % int(round(own * scale))
+        if args.karaoke and word_style:
+            # One Dialogue event per WORD, each carrying the whole cue -- \k/\kf can only
+            # interpolate colour, so scaling/emboldening the active word (and a third "upcoming"
+            # colour) needs a real per-word override block instead. The line list is `body`'s own
+            # \N split, already frozen by layout_cues (this function never re-wraps it), so every
+            # event uses the identical break -- WrapStyle: 2 above stops libass re-wrapping around
+            # the active word's larger \fscx/\fscy, which is the jump the issue is filed against.
+            line_words = [[w for w in seg.split(" ") if w] for seg in body.split("\\N")]
+            flat = [w for lw in line_words for w in lw]
+            real_idx = [i for i, w in enumerate(flat) if w.strip(EMOJI_SENTINEL)]
+            if not real_idx:
+                # nothing to highlight (an all-emoji or empty cue) -- one plain event, same as
+                # today's karaoke-off rendering, rather than zero Dialogue lines for this cue
+                out_body = body
+                if EMOJI_SENTINEL in out_body:
+                    out_body = out_body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
+                lines.append(f"Dialogue: 0,{t(start)},{t(end)},Default,,0,0,0,,{fx}{out_body}")
+                continue
+            n_words = len(real_idx)
+            durs = _karaoke_word_durations(args, video, start, end, n_words)
+            starts_cs, acc = [], 0
+            for d in durs:
+                starts_cs.append(acc)
+                acc += d
+            for j in range(n_words):
+                w_start = start + starts_cs[j] / 100.0
+                w_end = start + (starts_cs[j] + durs[j]) / 100.0
+                # colour/scale each real word by its rank against the active one (j); an
+                # emoji-placeholder token is never active and just keeps its plain text
+                styled, flat_pos = [], 0
+                for lw in line_words:
+                    styled_line = []
+                    for w in lw:
+                        if not w.strip(EMOJI_SENTINEL):
+                            styled_line.append(w)
+                        else:
+                            rank = real_idx.index(flat_pos)
+                            if rank < j:
+                                styled_line.append(f"{{\\c{word_past}}}{w}")
+                            elif rank == j:
+                                styled_line.append(
+                                    f"{{\\c{word_active}\\fscx{word_scale}\\fscy{word_scale}\\bord{word_bord}}}{w}{{\\r}}")
+                            else:
+                                styled_line.append(f"{{\\c{word_upcoming}}}{w}")
+                        flat_pos += 1
+                    styled.append(" ".join(styled_line))
+                out_body = "\\N".join(styled)
+                if EMOJI_SENTINEL in out_body:
+                    out_body = out_body.replace(EMOJI_SENTINEL, emoji_placeholder(getattr(args, "_emoji_box_px", size)))
+                # the size/fit override (\fsN) belongs on every event; the entrance animation
+                # (\fad/\move/pop) only on the cue's FIRST word event -- replaying it on every
+                # later word would re-fade/re-pop the whole cue each time the highlight advances
+                event_fx = fx if j == 0 else (fx[fx.index("{\\fs"):] if "{\\fs" in fx else "")
+                lines.append(f"Dialogue: 0,{t(w_start)},{t(w_end)},Default,,0,0,0,,{event_fx}{out_body}")
+            continue
         if args.karaoke:
             # split each line into words and give every word an equal share of the cue (\k is in centiseconds)
-            dur_cs = max(1, int(round((end - start) * 100)))
             segments = body.split("\\N")
             words = [w for seg in segments for w in seg.split(" ") if w and w.strip(EMOJI_SENTINEL)]
-            # real word timings from the transcript beat both the energy estimate and the even
-            # split -- they are what the speaker actually did, not a proxy for it
-            durs = word_durations_from_timings(getattr(args, "_word_timings", None) or [], start, end, len(words))
-            if durs is None:
-                if getattr(args, "karaoke_timing", "even") == "energy" and video:
-                    durs = word_durations_from_audio(video, start, end, len(words), getattr(args, "audio_stream", 0))
-                else:
-                    per = max(1, dur_cs // max(1, len(words)))
-                    durs = [per] * len(words)
+            durs = _karaoke_word_durations(args, video, start, end, len(words))
             it = iter(durs)
             out_segments = []
             for seg in segments:
@@ -840,7 +925,16 @@ def main() -> int:
     anim = ap.add_argument_group("animation (generates ASS; needs --text or --srt input)")
     anim.add_argument("--animate", choices=["none", "fade", "pop", "slide"], default=None, help="per-cue entrance animation (default none, or brand caption.animate)")
     anim.add_argument("--karaoke", action="store_true", help="word-by-word highlight (fills from --color to --highlight-color across each cue)")
-    anim.add_argument("--highlight-color", default=None, help="karaoke fill colour RRGGBB (default FFD200 or brand primary)")
+    anim.add_argument("--karaoke-style", choices=["sweep", "word"], default="sweep",
+                      help="'sweep' (default): today's \\kf colour fill, one Dialogue event per cue -- unchanged. "
+                           "'word': one Dialogue event per word, the active word scaled by --karaoke-scale and "
+                           "emboldened, past words in --color, upcoming words in --upcoming-color -- \\k/\\kf can only "
+                           "interpolate colour, so this is the only way to also scale/embolden the active word")
+    anim.add_argument("--highlight-color", default=None, help="karaoke fill/active-word colour RRGGBB (default FFD200 or brand primary)")
+    anim.add_argument("--upcoming-color", default=None,
+                      help="--karaoke-style word: colour RRGGBB for words not yet spoken (default B4B4B4)")
+    anim.add_argument("--karaoke-scale", type=float, default=112.0,
+                      help="--karaoke-style word: the active word's size as a percentage of the caption size (default 112)")
     anim.add_argument("--karaoke-timing", choices=["even", "energy"], default="energy",
                       help="how words are timed inside a cue: 'energy' follows the speech loudness in the audio (default), 'even' splits time equally")
     anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
@@ -886,6 +980,9 @@ def main() -> int:
     # to be applied anyway and then refused as "animation is burn only" -- ignore it there
     args.animate = args.animate or (bcap.get("animate", "none") if args.brand and args.mode != "mux" else "none")
     args.highlight_color = color_hex(args.highlight_color or bc.get("primary", "FFD200"))
+    args.upcoming_color = color_hex(args.upcoming_color or bc.get("upcoming", "B4B4B4"))
+    if args.karaoke_scale <= 0:
+        die("--karaoke-scale must be positive")
     if args.brand and bcap.get("bold") and not args.bold:
         args.bold = True
     if args.brand and bcap.get("karaoke") and not args.karaoke:

package/scripts/loudness.py

@@ -105,6 +105,8 @@ def main() -> int:
             cmd += ["-vn"] + audio_codec_for(output, bitrate)
         else:
             cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
+            if ext in (".mp4", ".mov", ".m4v"):
+                cmd += ["-movflags", "+faststart"]
             dropped_streams = run_keeping_subtitles(cmd, output)
             return
         cmd.append(output)