ffmpeg-skill 1.17.3 → 1.18.0

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.17.3`) | any release |
+| `skill.version` | the npm / package.json version (`1.18.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.17.3 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
-| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.17.3 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
-| `json` and `progress` in the MCP `inputSchema` | 1.17.3 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
-| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.17.3 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
-| Overwriting an existing output with only a warning | 1.17.3 | `--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.18.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.18.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.18.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.18.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.18.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.17.3", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.17.3", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.18.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.18.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.17.3): 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.18.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 |
@@ -450,7 +450,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.17.3, all additive:
+Per-tool keys added in 1.18.0, all additive:
 
 | key | tool | what it holds |
 |---|---|---|
@@ -458,6 +458,18 @@ Per-tool keys added in 1.17.3, 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.18.0, all additive:
+
+| key | tool | what it holds |
+|---|---|---|
+| `shots` | `scenes.py --shots` | `[{start, end, label, flow_magnitude}]` per detected scene, `label` one of `static`/`pan`/`motion` from a lightweight block-matching optical-flow proxy (frames decoded at 4 fps, 48x27, no external dependency). A shot too short to sample two frames is `static` with `flow_magnitude: 0` |
+| `audio_peaks_db` | `scenes.py --audio-peaks` | `[{time, level}]`, measured dBFS loudness peaks. A **new** key: the pre-existing `audio_peaks` (always reported, unrelated unitless RMS figures used for `--highlights` scoring) keeps its 1.0 meaning unchanged |
+| `speech` | `scenes.py --speech` | `[{time, speech_music_ratio}]`, a per-second zero-crossing-rate ratio against the file's own median — a measured proxy, not a speech/music classification |
+| `motion_centre` | `cropdetect.py --motion-centre` | `[{time, x, y, x_frac, y_frac, motion}]` per second, sampled over the same windows as the crop-bar detection. `x`/`y` are source pixels, `x_frac`/`y_frac` a 0..1 fraction of `source_width`/`source_height`; a window with no measured motion reports `x`/`y`/`x_frac`/`y_frac: null`. Report only — this tool never picks a reframe |
+| `speech_aware`, `speech_aware.breaths` | `silence.py --speech-aware` | `{min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}`. `breaths` are the sub-`--min-silence` gaps kept because they sit inside a sentence; the removal list (`silences`, `keep`, `removed_seconds`) already reflects the speech-aware classification. Composes with `--filler` through the same `keep_ranges()`/`merge_spans()` pipeline, so `--speech-aware --filler` produces one removal list |
+| `sources` | `sync.py` | `[{path, offset_s, confidence, drift_ppm}]`, one entry per SOURCE. Present for every run, including the original single-SOURCE shape (where it mirrors the top-level `second`/`offset_seconds`/`confidence` additively). With 2+ SOURCEs it is the *only* per-source shape: there is no top-level `second`/`offset_seconds` because there is no single pair to put there |
+| `switch_mode`, `min_shot` | `multicam.py --switch energy` | `"energy"` and the `--min-shot` value used (default 1.5s), alongside the existing `cuts` (`[[start, end, camera], ...]`) which already carries the camera index for `--edl`'s companion cut list |
+
 `check.py` also gains an informational `subtitles` row on **every** platform:
 `PASS` when every soft subtitle stream carries a language tag, `WARN` when one
 does not (or when there are none). Like `channels` and `chapters` it is never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.17.3",
+  "version": "1.18.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/ci-platform-pitfalls.md

@@ -128,7 +128,7 @@ these had ever shown up before.
   are still spelled exactly that way: `_common` is a package since the refactor release after
   1.15.0, and its `__init__.py` re-exports every name the single module defined, so
   `_common.drawtext_boxborderw()`, `_common.ffmpeg_version()` and `_common.bt709_tag_args()`
-  below resolve through the facade unchanged. The definitions are in `_common/text.py`,
+  below resolve through the facade unchanged. The definitions are in `_common/drawtext.py`,
   `_common/runner.py` and `_common/color.py` respectively.
 - **`showwaves` keeps emitting frames after the audio ends, `-shortest` notwithstanding.** A
   12 s source came out 14.08 s on 5.1.1. `waveform.py` now also passes `-t <source duration>`.

package/references/scripts.md

@@ -161,7 +161,7 @@ rounded, if they aren't.
 
 ### cropdetect.py — measure black bars, report the crop rectangle
 ```
-cropdetect.py INPUT [--seconds N] [--samples N] [--limit F] [--round N]
+cropdetect.py INPUT [--seconds N] [--samples N] [--limit F] [--round N] [--motion-centre]
 ```
 Measurement only -- writes no file. Samples `--samples` windows spread
 across the file (default 5, totalling `--seconds` 10s of footage) and
@@ -174,6 +174,14 @@ removing detected bars is wanted -- genuine letterboxed content (a
 scope-ratio film in a 16:9 frame) "detects" the same way as accidental
 bars; look at the frame before cropping it away.
 
+`--motion-centre` (1.18) reports the motion centroid once per second, sampled
+across the same windows: `motion_centre: [{time, x, y, x_frac, y_frac, motion}]`,
+`x`/`y` in source pixels and `x_frac`/`y_frac` as a 0..1 fraction of
+`source_width`/`source_height`. A frame with no measured motion in a window
+reports `x`/`y`/`x_frac`/`y_frac: null` and `motion: 0`. Report only, like the
+crop rectangle above -- this hands the calling agent numbers to reframe a 9:16
+crop with; it never picks the subject or the crop box itself.
+
 ### deinterlace.py — deinterlace interlaced footage
 ```
 deinterlace.py INPUT [--mode frame|field] [--parity auto|tff|bff] [--only-interlaced] [-o OUT]
@@ -465,7 +473,7 @@ each shorter clip's last frame (with silence) out to the longest.
 
 ### silence.py — remove dead air / jump cuts
 ```
-silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [-o OUT]
+silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [--speech-aware] [-o OUT]
 silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|es|de|fr|pt|it]
            [--filler-words FILE] [--filler-extra W,W] [--filler-keep W,W] [--filler-pad 0.02]
            [--transcribe] [--filler-list] [--max-cuts 400]
@@ -531,6 +539,17 @@ additive sibling covering everything that went. A filler word quiet enough to
 sit inside a detected silence is merged into it rather than counted twice, so
 the two figures can be equal.
 
+**`--speech-aware` (1.18)** keeps breaths shorter than `--min-silence` when
+they sit inside a sentence, and only cuts at sentence-boundary pauses
+(`--min-silence` or longer). It re-runs silence detection at a much shorter
+floor to measure the short gaps at all, then classifies each one: shorter than
+`--min-silence` is an in-sentence breath (kept, listed in
+`speech_aware.breaths`); `--min-silence` or longer is a sentence boundary (cut,
+same as the plain flag). It composes with `--filler` through the same
+`keep_ranges()`/`merge_spans()` pipeline the filler-inside-a-silence fix
+already uses, so `--speech-aware --filler` produces one removal list. `--edl`
+writes the resulting cut list exactly as it does today.
+
 ### join.py — concatenate with transitions
 ```
 join.py CLIP1 CLIP2 [...] [--transition fade|dissolve|wipeleft|slideleft|fadeblack|fadewhite|circleopen|none]
@@ -701,6 +720,7 @@ already has a picture.
 ```
 scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
 scenes.py INPUT --beats [--beat-step 0.01] [--beat-range 60-200] [--min-confidence 0.5] [--json]
+scenes.py INPUT [--shots] [--audio-peaks] [--speech] [--json]
 ```
 Lists scenes with audio energy, the loudest moments, and (with
 `--highlights`) proposes N ranges that add up to `--target` seconds, biased to
@@ -751,6 +771,29 @@ would change a file on the strength of it (`cut.py --snap beats`). `--edl` with
 `--beats` is unchanged: beats are never written as an EDL, because a beat is
 not a cut. No audio stream is a `kind: input` refusal.
 
+**`--shots`, `--audio-peaks`, `--speech` (1.18)** are three independent
+measurements that combine with each other and with `--beats`/`--highlights`:
+
+- `--shots` labels each already-detected scene `static`/`pan`/`motion` by a
+  lightweight block-matching optical-flow proxy (frames decoded at 4 fps,
+  48x27, no external dependency), reporting `shots: [{start, end, label,
+  flow_magnitude}]`. A shot too short to sample two frames is `static` with
+  `flow_magnitude: 0` — there is nothing to measure motion between. A proxy,
+  the same spirit as `--rank-by`: it reports what a coarse block match saw,
+  not what is interesting about the shot.
+- `--audio-peaks` reports loudness peaks as measured dBFS: `audio_peaks_db:
+  [{time, level}]`. This is a new key, kept separate from the pre-existing
+  (always-on) `audio_peaks` list, whose entries are an unrelated unitless RMS
+  figure used for `--highlights` scoring — a different unit needed a
+  different key so `audio_peaks`'s meaning does not change underneath a
+  caller reading it since 1.0.
+- `--speech` reports a per-second zero-crossing-rate ratio,
+  `speech: [{time, speech_music_ratio}]` — speech's rapid consonant
+  transients raise the zero-crossing rate; sustained tones (music, room
+  tone) cross zero at a steadier rate. `1.0` means "typical for this file's
+  own median," not an absolute threshold. This is a measured number, not a
+  speech/music classification — nothing here decides which stretch is which.
+
 ### check.py — pre-delivery compliance
 ```
 check.py INPUT --platform youtube|shorts|reels|tiktok|x|linkedin|facebook|broadcast|podcast|custom [--no-loudness] [--json]
@@ -905,7 +948,8 @@ hand the path to the user together with the numbers.
 
 ### multicam.py — align several cameras and switch between them
 ```
-multicam.py REF CAM2 [CAM3 ...] [--switch "START-END:CAM,..."] | [--auto N] [--audio IDX] [--fix-drift]
+multicam.py REF CAM2 [CAM3 ...] [--switch "START-END:CAM,..."|energy [--min-shot 1.5]] | [--auto N]
+            [--audio IDX] [--fix-drift] [--edl cuts.txt]
             [--offsets-only] [--width W --height H --fps N] [-o OUT]
 ```
 All inputs are aligned to the first one by audio (same engine as `sync.py`,
@@ -915,6 +959,23 @@ simply alternates every N seconds. Audio comes from the reference unless
 `--audio` picks another input, e.g. an external recorder that has no video.
 `--offsets-only` reports offsets and confidence without rendering.
 
+**`--switch energy` (1.18)** auto-switches to whichever camera (of those with
+a video stream) measures the loudest audio at each 0.25 s window on the
+reference timeline, then folds any run shorter than `--min-shot` (default
+1.5 s) into its neighbour so the cut never lingers on a shot too short to
+read. A measured loudest-camera pick, the same spirit as `scenes.py
+--rank-by audio`: a proxy for who is talking, not a judgement — a loud crowd
+or a hot mic wins over a quiet subject exactly like the scene ranking does.
+`--edl` (1.18, any switch mode) writes the resulting cut list as `cut.py
+--segments`-format `START-END` lines; the camera index for each cut is
+already in the JSON `cuts` field (`[[start, end, camera], ...]`), which is
+what `--edl` leaves out on purpose — one file for an NLE's cut list, one
+field for the camera it came from. The multicam timeline needs no dedicated
+project format: each cut is a `render.py` clip (`{"src": ..., "in": ...,
+"out": ...}` on that camera's own timeline, shifted by its measured offset),
+so a switch list can be re-rendered with different `--min-shot` values by
+editing `project.json`'s `clips`, not by inventing a second timeline schema.
+
 ### verify.py — real-footage verification kit
 ```
 verify.py FILES_OR_FOLDERS [--quick] [--report verify.md] [--out DIR --keep] [--seconds 6] [--json]
@@ -1185,18 +1246,18 @@ draws whatever glyph the text font has; `--emoji none` strips them).
 
 ### sync.py — offset detection, alignment, drift correction
 ```
-sync.py REFERENCE SECOND [--json] [--max-offset 30] [--analyze-seconds 120] [--fix-drift [--drift-window 60]]
-        [--replace-audio | --trim-second] [-o OUT]
+sync.py REFERENCE SOURCE [SOURCE ...] [--json] [--max-offset 30] [--analyze-seconds 120]
+        [--fix-drift [--drift-window 60]] [--replace-audio | --trim-second] [-o OUT]
 ```
 Cross-correlates loudness envelopes: coarse FFT search (20 ms), then a direct
 1 ms refinement (pure Python, a 2-minute window takes ~1-3 s). Positive offset
-= the second recording started later. `--replace-audio` writes the reference
-video with the second file's audio aligned (video stream copied); the output
-keeps the reference's full length -- a shorter or head-trimmed second file is
+= the source recording started later. `--replace-audio` writes the reference
+video with the source file's audio aligned (video stream copied); the output
+keeps the reference's full length -- a shorter or head-trimmed source file is
 padded with silence, never allowed to cut the picture.
-`--trim-second` writes the second file shifted to the reference timeline.
+`--trim-second` writes the source file shifted to the reference timeline.
 `--fix-drift` measures the offset again near the end of the overlap, reports
-the clock difference in ppm, and resamples the second file so a 60-minute
+the clock difference in ppm, and resamples the source file so a 60-minute
 take stays in sync (typical consumer devices drift 20-500 ppm = up to 1.8 s/h).
 Use it whenever the recording is longer than ~10 minutes. Check `confidence`
 (0–1, normalised correlation with a runner-up penalty); below 0.3 the match is
@@ -1206,6 +1267,20 @@ window 95 %, misses flagged below 0.3. Keep `--analyze-seconds` at least 4×
 `--max-offset` (default 120 s vs 30 s): lags with under 35 % overlap are
 ignored, so an offset larger than ~60 % of the window cannot be found.
 
+**One reference, 1+ SOURCE (1.18).** With exactly one SOURCE the CLI keeps its
+original shape byte for byte -- `second`, `offset_seconds`, `confidence`,
+`meaning`, `drift` at the top level, `--replace-audio`/`--trim-second`
+available -- with the same measurement additively mirrored under a new
+`sources: [{path, offset_s, confidence, drift_ppm}]` list. With 2+ SOURCEs the
+result is one offsets JSON, `{reference, sources: [...]}`, and no flat
+`second`/`offset_seconds` (there is no single pair to put there);
+`--replace-audio`/`--trim-second` refuse with `kind: input`, since each writes
+one synced output and there is more than one source to choose from. This is
+the same offset/drift measurement `multicam.py` already loops over per camera
+internally (it imports `sync.measure_offset`); `sync.py`'s own N-source CLI
+now exposes that loop directly, for aligning cameras without cutting between
+them.
+
 ### color.py — HDR to SDR, LUTs, colour tags, Dolby Vision
 ```
 color.py INPUT --to-sdr [--tonemap hable|mobius|reinhard|bt2390] [--peak 1000] [--desat 0] [-o OUT]

package/scripts/_common/__init__.py

@@ -7,8 +7,9 @@ error reporting, and provides a compact media probe used by every script.
 Since the refactor release after 1.15.0 the helpers live in one module per responsibility --
 runner (process execution and timeouts), probe (ffprobe and the measured facts), decision (the
 pure copy-vs-re-encode and capability choices), emit (result documents, die(), info()), color
-(colour tags and the HDR paths) and text (fonts, scripts, emoji, drawtext) -- and this file is a
-facade that re-exports every name they define. `import _common` and `from _common import x` mean
+(colour tags and the HDR paths) and, since the refactor after 1.17.3, fonts, emoji, drawtext and wrap
+(text.py is a re-export shim over those four) -- and this file is a facade that re-exports every name
+they define. `import _common` and `from _common import x` mean
 exactly what they meant when this was one 3072-line module; nothing else about the package is
 part of the contract.
 """
@@ -67,12 +68,13 @@ from _common.emit import (
 )
 from _common.probe import (
     analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, detect_scenes, detect_silences, fingerprint,
-    _fraction, keyframes_near, SCORE_RE, SIL_RE,
+    _fraction, keyframes_near, SCORE_RE, SIL_RE, decode_gray_frames,
     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,
+    frame_flow, label_shot_flow, MOTION_GRID, MOTION_SEARCH, MOTION_STATIC_PX, MOTION_PAN_SPREAD,
     filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOURSE_MARKERS, FILLER_MAX_WORD,
     FILLER_MIN_GAP, FILLER_PAD, normalise_filler_token,
     beat_grid, snap_points, BEAT_MIN_CONFIDENCE, BEAT_ONSET_K, BEAT_OCTAVE_MARGIN,
@@ -112,7 +114,7 @@ from _common.text import (
     SHAPING_SCRIPTS, text_width_em, _VS15, _VS16, WINDOWS_FONTS, _ZWJ
 )
 
-from _common import asr, color, decision, runner, text  # noqa: F401,E402
+from _common import asr, color, decision, drawtext, emoji, fonts, runner, text, wrap  # noqa: F401,E402
 
 # `_common.emit` and `_common.probe` are the FUNCTIONS, as they have always been -- the
 # from-imports above rebound the package attribute the submodule import had set. The two modules
@@ -123,7 +125,7 @@ from _common import asr, color, decision, runner, text  # noqa: F401,E402
 _emit_module = sys.modules["_common.emit"]
 _probe_module = sys.modules["_common.probe"]
 
-_MODULES = (runner, _emit_module, _probe_module, decision, color, text, asr)
+_MODULES = (runner, _emit_module, _probe_module, decision, color, text, fonts, emoji, drawtext, wrap, asr)
 
 
 class _Facade(_types.ModuleType):
@@ -204,6 +206,7 @@ __all__ = [
     "place_output", "_plan_at_exit", "_plan_inputs", "_PLAN_STRIP", "PLAN_VERSION", "PREFERRED_FAMILIES",
     "print_json", "probe", "PROBE_TIMEOUT", "_progress_line", "read_text_or_die", "refuse_output_is_input",
     "_remember_output", "require_tool", "resolve_emoji_assets", "_result_v2", "rms_envelope", "run", "run_analysis",
+    "decode_gray_frames", "frame_flow", "label_shot_flow", "MOTION_GRID", "MOTION_SEARCH", "MOTION_STATIC_PX", "MOTION_PAN_SPREAD",
     "_run_captured", "run_keeping_subtitles", "run_tool", "_run_with_progress", "_SCRIPT_FONT_CACHE",
     "_script_font_entry", "script_font_for_text", "script_font_status", "_script_font_uncached", "_SCRIPT_RANGES",
     "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote",

package/scripts/_common/decision.py

@@ -864,3 +864,89 @@ def filler_spans(words, wordlist, *, pad: float = FILLER_PAD, min_gap: float = F
         m["start"] = round(m["start"], 4)
         m["end"] = round(m["end"], 4)
     return merged
+
+
+# --- 1.18.0: lightweight block-matching motion estimate (scenes.py --shots, cropdetect.py
+# --motion-centre) ---------------------------------------------------------------------------
+
+MOTION_GRID = 4          # NxN anchor blocks per frame
+MOTION_SEARCH = 3         # +/- pixels searched per block, at the decoded (low) resolution
+MOTION_STATIC_PX = 0.35   # average per-frame displacement below this, at decode resolution, is "static"
+MOTION_PAN_SPREAD = 0.6   # block-to-block direction agreement above this (0..1) reads as a pan
+
+
+def _block_match(prev: bytes, cur: bytes, w: int, h: int, cx: int, cy: int, half: int, search: int) -> "Tuple[float, float]":
+    """(dx, dy) that best aligns a `half*2` square centred at (cx, cy) in `prev` to `cur`,
+    searched over +/- `search` px by sum-of-absolute-differences. Coordinates and the returned
+    offset are in decoded-frame pixels (a handful of pixels a side at 1.18.0's sample size)."""
+    x0, y0 = max(half, min(w - half - 1, cx)), max(half, min(h - half - 1, cy))
+    ref = [prev[(y0 + dy) * w + (x0 + dx)] for dy in range(-half, half + 1) for dx in range(-half, half + 1)]
+
+    def sad_at(xx: int, yy: int) -> "Optional[int]":
+        if xx - half < 0 or xx + half >= w or yy - half < 0 or yy + half >= h:
+            return None
+        sad = 0
+        for dy in range(-half, half + 1):
+            row = (yy + dy) * w
+            for dx in range(-half, half + 1):
+                sad += abs(ref[(dy + half) * (2 * half + 1) + (dx + half)] - cur[row + xx + dx])
+        return sad
+
+    # Zero shift is the tie-break candidate, not the search order's first cell: on a textureless
+    # block (a flat colour, sky, an out-of-focus background) every offset scores the same SAD, and
+    # without an explicit tie towards "no motion" the scan used to report the search window's
+    # first corner as the measured displacement -- a still frame with nothing to match against
+    # read as steady motion in one direction, every time.
+    best_sad, best = sad_at(x0, y0), (0.0, 0.0)
+    if best_sad is None:
+        best_sad = float("inf")
+    for sy in range(-search, search + 1):
+        for sx in range(-search, search + 1):
+            if sx == 0 and sy == 0:
+                continue
+            sad = sad_at(x0 + sx, y0 + sy)
+            if sad is not None and sad < best_sad:
+                best_sad, best = sad, (float(sx), float(sy))
+    return best
+
+
+def frame_flow(prev: bytes, cur: bytes, w: int, h: int, *, grid: int = MOTION_GRID,
+               search: int = MOTION_SEARCH) -> "Dict[str, Any]":
+    """One measurement between two consecutive decoded grayscale frames: the mean block
+    displacement vector, its magnitude, and how consistently the blocks agree on direction
+    (0 = every block moved a different way, 1 = every block agrees -- a pan or dolly moves the
+    whole frame one way, on-screen motion inside a mostly-static frame does not)."""
+    half = max(1, min(w, h) // (grid * 3))
+    vecs: "List[Tuple[float, float]]" = []
+    for gy in range(grid):
+        for gx in range(grid):
+            cx = int((gx + 0.5) * w / grid)
+            cy = int((gy + 0.5) * h / grid)
+            vecs.append(_block_match(prev, cur, w, h, cx, cy, half, search))
+    mdx = sum(v[0] for v in vecs) / len(vecs)
+    mdy = sum(v[1] for v in vecs) / len(vecs)
+    magnitude = math.hypot(mdx, mdy)
+    mean_len = sum(math.hypot(*v) for v in vecs) / len(vecs)
+    agreement = (magnitude / mean_len) if mean_len > 1e-6 else 1.0  # 1.0 = every block agrees
+    return {"dx": mdx, "dy": mdy, "magnitude": magnitude, "agreement": min(1.0, agreement)}
+
+
+def label_shot_flow(flows: "Sequence[Dict[str, Any]]") -> "Dict[str, Any]":
+    """{label, flow_magnitude} for one shot from its per-frame-pair flow measurements.
+
+    static: mean displacement below MOTION_STATIC_PX. pan: above it, and blocks agree on
+    direction (a camera move shifts the whole frame). motion: above it, blocks disagree (motion
+    inside an otherwise still frame -- handheld jitter, or a subject moving across a static
+    background). This is a measured proxy, the same spirit as scenes.py --rank-by: it reports
+    what a coarse block match saw, not what is interesting about the shot."""
+    if not flows:
+        return {"label": "static", "flow_magnitude": 0.0}
+    magnitude = sum(f["magnitude"] for f in flows) / len(flows)
+    agreement = sum(f["agreement"] for f in flows) / len(flows)
+    if magnitude < MOTION_STATIC_PX:
+        label = "static"
+    elif agreement >= MOTION_PAN_SPREAD:
+        label = "pan"
+    else:
+        label = "motion"
+    return {"label": label, "flow_magnitude": round(magnitude, 3)}

package/scripts/_common/drawtext.py

@@ -0,0 +1,125 @@
+"""drawtext: the option builders (textfile= route, boxborderw form per ffmpeg version), the
+font-name escape and the shaping-library probe that decides drawtext vs libass per script.
+Split out of _common.text in the refactor after 1.17.3; every body is byte-identical.
+"""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from typing import Dict, Optional
+from _common.decision import escape_filter_path
+from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_version
+
+
+def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
+    """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)
+    arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"
+    (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""
+    if ffmpeg_version() >= (6, 1):
+        return f"{vertical}|{horizontal}"
+    return str(max(vertical, horizontal))
+
+
+# --------------------------------------------------------------------------- shaping (1.15)
+# Scripts whose correct rendering needs harfbuzz-class reordering and re-clustering (Indic matras,
+# Thai/Lao mark stacking). drawtext does NOT use harfbuzz even in an --enable-libharfbuzz build, so
+# these come out wrong through drawtext on every build and must go through libass. Arabic and
+# Hebrew are NOT here: drawtext's text_shaping uses fribidi, which does bidi and Arabic joining
+# correctly -- they only join this set on a build compiled without fribidi.
+SHAPING_SCRIPTS = frozenset({"hi", "bn", "ta", "te", "kn", "ml", "gu", "pa", "si", "th", "lo", "km", "my"})
+
+
+BIDI_SCRIPTS = frozenset({"ar", "he"})
+
+
+_SHAPING_BUILD_CACHE: "Dict[str, bool]" = {}
+
+
+def drawtext_shaping() -> "Dict[str, bool]":
+    """Which shaping libraries THIS ffmpeg was built with, from -buildconf (falling back to the
+    `configuration:` line of -version). Cached per process."""
+    if _SHAPING_BUILD_CACHE:
+        return dict(_SHAPING_BUILD_CACHE)
+    text = ""
+    exe = shutil.which("ffmpeg")
+    if exe:
+        for flag in ("-buildconf", "-version"):
+            try:
+                proc = subprocess.run([exe, "-hide_banner", flag], stdout=subprocess.PIPE,
+                                      stderr=subprocess.STDOUT, text=True, encoding="utf-8", errors="replace", timeout=10)
+            except (subprocess.TimeoutExpired, OSError):
+                break
+            if proc.returncode == 0 and proc.stdout.strip():
+                text = proc.stdout
+                break
+    _SHAPING_BUILD_CACHE.update({"fribidi": "--enable-libfribidi" in text,
+                                 "harfbuzz": "--enable-libharfbuzz" in text})
+    return dict(_SHAPING_BUILD_CACHE)
+
+
+def needs_shaping(script: str) -> bool:
+    """Whether drawtext would render `script` wrongly on this build."""
+    if script in SHAPING_SCRIPTS:
+        return True
+    return script in BIDI_SCRIPTS and not drawtext_shaping()["fribidi"]
+
+
+def escape_drawtext(text: str) -> str:
+    """Escape a FONT NAME for a single-quoted drawtext option value (`font='<this>'`).
+
+    Since 1.15 this is no longer the route for drawn TEXT -- use drawtext_text_opts(), which puts
+    the text in a file and keeps `\'` and `%` verbatim. It remains the escape for the font-name
+    fallback, where the value is a family name that never legitimately contains a quote or a
+    percent sign.
+
+    Every ffmpeg filter-graph special character (`\\ : % , [ ] ;`) needs a backslash escape
+    regardless of the surrounding quotes -- the graph parser still splits on an unescaped `,`/`;`
+    or ends an option list on an unescaped `:`/`[`/`]` even while "inside" a quoted value. The
+    quote character itself has no reliable backslash escape at all: `\\'` and the POSIX shell
+    close-insert-reopen trick both parse fine in a simple `-vf` chain but silently corrupt a
+    `-filter_complex` chain that uses explicit `[label]` pads (confirmed by rendering the result:
+    trailing option names leak into the picture as literal text). `%` has the same problem as far
+    as drawtext's own expansion scanner is concerned. Both are therefore dropped here rather than
+    escaped -- which is exactly why drawn text no longer comes through this function.
+    """
+    text = re.sub(r"[\x00-\x1f\x7f]", "", text)
+    return (
+        text.replace("'", "")
+        .replace("%", "")
+        .replace("\\", "\\\\")
+        .replace(":", "\\:")
+        .replace(",", "\\,")
+        .replace("[", "\\[")
+        .replace("]", "\\]")
+        .replace(";", "\\;")
+    )
+
+
+def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
+    """`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
+    every character on every build shape this repo uses.
+
+    The filter-graph parser never sees the text at all: only the PATH is parsed, and
+    escape_filter_path() already handles that. `expansion=none` switches off drawtext's own
+    `%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
+    and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
+    `]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
+    done"` losing both characters. Control characters are still stripped: a one-line burnt-in
+    label has no use for them.
+
+    The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
+    removed when the process ends. It is *registered* here and written by run() only if the
+    command about to run actually names it, so --dry-run and the ASS route write nothing; a
+    printed plan therefore names a path that no longer exists once the run is over, which is the
+    same promise every other temp file in this skill makes.
+    """
+    cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
+    import hashlib
+    name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
+    if tmpdir is None:
+        tmpdir = _drawtext_tmpdir(create=not STATE.dry_run)
+    path = os.path.join(tmpdir, name)
+    _DRAWTEXT_PENDING[path] = cleaned
+    return f"textfile={escape_filter_path(path)}:expansion=none"