ffmpeg-skill 2.10.7 → 2.10.9

package/README.md

@@ -358,13 +358,15 @@ The server also advertises a `prompts` capability: five canned workflow recipes
 
 ```bash
 npx ffmpeg-skill doctor          # human-readable
-npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unknown / detection / errors / tools / gpu_encoders
+npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unknown / detection / errors / tools / gpu_encoders / ffmpeg_security
 ```
 
 `doctor` reads `ffmpeg -encoders`, `-filters` and `-bsfs` and resolves every capability the contract declares against this machine's build. Three states per capability: `available`, `missing`, `unknown`. Exit 0 when everything required is available, 1 when something required is missing, 2 when nothing is proven missing but a required capability is unknown. With detection on (the default), `contract --json` carries the same lists under `capabilities`. `doctor` also reports fonts: the default drawtext family, and `fonts.scripts` — one `available`/`missing`/`unknown` per writing system (ja, zh, ko, ar, he, hi, th, ru, el) with the file it would use — so "can this machine render Korean captions" is answered before the job, not after. `doctor --json`'s `tools` field folds that down to one answer per tool — `{"caption": {"usable": "no", "missing": ["filter:subtitles"], "fix": "..."}, ...}` — so "is `doctor` overall `ok`" and "can I run `caption.py` on this machine" are answered separately: a plain Homebrew `ffmpeg` is `ok` for tools that don't need `subtitles`/`drawtext`/`zscale`, while `caption`'s own `usable` is `"no"`.
 
 `doctor --json`'s `gpu_encoders` reports which GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`, `vaapi`, `amf`) this ffmpeg *build* was compiled with — read from `-encoders` alone, so it proves the capability shipped, not that the GPU/driver on this machine will actually accept a job (that needs a real encode, which `doctor`'s introspection never runs). It never affects `ok` or any tool's `usable`. The one GPU path a tool uses is Apple VideoToolbox, opt-in: `--hw` on every re-encoding tool (h264/hevc/prores on the GPU, AV1 stays on SVT-AV1), `FFMPEG_SKILL_HW=1` to make it this machine's default for everything except `export.py`'s delivery presets (those take `--hw` explicitly, or `render.py --hw` for a whole project). It runs only on Apple Silicon and never by default, except on a build with no `libx264`/`libx265` (an LGPL ffmpeg that has only `h264_videotoolbox`/`hevc_videotoolbox`): there it is the only encoder, so every re-encoding tool and `export.py`'s presets use it without `--hw`, the result says `hw.source: "auto"`, and `doctor` lists the missing x264/x265 under `covered_by` instead of calling the tools unusable (`--no-hw` still asks for the CPU). It falls back to the CPU encoder — reported in the result's `hw.fallback`/`hw.notes` — only when VideoToolbox itself refuses a job (any other ffmpeg failure is reported as it happened, not retried); every result names the `encoder` that actually ran (`batch.py`, which encodes nothing itself: each `results` row), and a GPU encode adds a `notes` line that its quality is not CRF-equivalent. Measured on an M4 Max, 2–7× faster than x264/x265 `medium`; at matched SSIM (`tests/bench_vt.py`) 1.1–2.9× the bytes on SDR and 1.9–3.5× on HDR, which is why it is a flag and not the default (`docs/design-decisions.md`). `doctor --json`'s `hw` says whether this machine can run it (`platform_ok`) and whether it is the default here (`default_on`).
 
+`doctor` also compares the FFmpeg version with a small, dated table of high-severity FFmpeg CVEs (`doctor --json`'s `ffmpeg_security`; source [ffmpeg.org/security.html](https://ffmpeg.org/security.html), checked 2026-10-22). ffmpeg-skill does not ship FFmpeg, so a decoder bug in the build you have stays yours until you upgrade it. When the version is older than the first upstream release on its branch that carries a fix (today: CVE-2026-8461, the MagicYUV decoder heap write, fixed in 8.0.3, 8.1.2 and 9.0), `doctor` prints one `warning:` line on stderr with the update command and lists it under `ffmpeg_security.warnings`. It is advice, never a failure: `ok`, each tool's `usable` and the exit code do not change. A distribution package (Ubuntu `8.0.1-3ubuntu2`, Debian `+deb13u1`) may carry the fix as a backport under the old version number, so the line says the build is older than the fix, not that it is vulnerable. A version it cannot read (a git snapshot such as `N-12345-g…`) gets no warning, and nothing is fetched: the table ships with the skill.
+
 ## Gotchas and best practices
 
 The short list for humans. The agent-facing version, with the reasoning, is the "Things that look right but are wrong" and "Gotchas" sections of [SKILL.md](SKILL.md).
@@ -395,9 +397,13 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 
 Each operation is a script whose flags are its argparse parser, and that parser is what `contract --json` and the MCP `inputSchema` are built from. CI fails the build when those drift from the scripts. A caller-supplied filter graph, `-vf` string, or other ffmpeg option is not an argument any script accepts. `doctor` reads `ffmpeg -filters` (and `-encoders`, `-bsfs`) and reports a filter a tool needs before a job runs into it. MCP does accept an `argv` array, and that array is the named script's own CLI flags, still bound to that script: the script's flags, never an ffmpeg command line and never a shell.
 
-### How does this differ from Remotion or HyperFrames? Can they be used together?
+### How does ffmpeg-skill compare with Remotion?
+
+ffmpeg-skill edits footage you already have, on this machine, with FFmpeg tools whose flags are a machine-readable contract (`contract --json`). Remotion renders a video from React components. They complement each other: this repository does not call Remotion, and a file Remotion writes is an ordinary input (`probe.py`, `cut.py`, `fit.py`, `export.py`, `check.py`). HyperFrames renders a video from HTML and is the same kind of neighbour: a file it writes is an ordinary input too.
+
+### Does it validate the filter graph before running?
 
-Remotion renders a video from React components. HyperFrames renders one from HTML. This repository does neither, and it does not call either of them. It edits a media file you already have, on the machine, with ffmpeg and ffprobe, then probes the file it wrote. A render from either tool is an ordinary input: `probe.py`, `cut.py`, `fit.py`, `export.py` and `check.py` take the file the same way they take any other clip.
+No. `--dry-run` prints the ffmpeg command a writing tool would run and does not start ffmpeg, so ffmpeg never parses that filter graph. ffprobe still runs when the tool probes an input that exists. Unless `--overwrite` is passed, an existing output is refused (`kind: input`) before ffmpeg. An output that is the same file as an input is refused either way. No media file is written, and `verified` is false; `--plan FILE` does write the plan JSON. A path that is not on disk yet is not measured: the probe is a stub (0×0, duration 0), so a number taken from it is not a measurement. The measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) still run their measurements; only the artifact is skipped, and `silence` with `--filler --transcribe` also runs the speech engine, which may download a model. `verify` accepts `--dry-run` and ignores it: its steps run. `--plan FILE` is that dry run written down — the planned argv, the command lines, and a fingerprint of each existing input (size, plus a sha256 of the first and last 8 MiB). `render.py` and `verify.py` refuse `--plan`. `render.py FILE` runs a plan only when those fingerprints still match, by running the tool again with the planned argv, not by executing the recorded ffmpeg lines; `--dry-run` on that run only prints them. `doctor` reports whether the filters, encoders and bitstream filters the contract names are in this build (`ffmpeg -filters`, `-encoders`, `-bsfs`) and which fonts are installed. A name in that listing is not a check of the graph this command would build, and a listed GPU encoder is not a successful encode.
 
 ### Can it remove burned-in subtitles or logos?
 
@@ -413,7 +419,7 @@ The encode path a tool will actually take is Apple VideoToolbox, for h264, hevc
 
 ## FFmpeg compatibility
 
-The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only); Python 3.10+ is recommended: 3.9 still works but is deprecated since 2.11.0 (CPython 3.9 is end of life), `doctor` and the `npx` installer warn on it, and 3.0 drops it. What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
 
 | FFmpeg | `-filters` row layout | Source |
 |---|---|---|
@@ -521,7 +527,7 @@ FFmpeg itself:
 ## Requirements
 
 - FFmpeg 5.0+. Always required: `libx264`, `aac`, and the `drawtext`, `subtitles` (libass), `loudnorm`, `xfade`, `acrossfade`, `scdet`, `silencedetect` and `tile` filters. Needed only by the flags that use them: `libx265`, `prores_ks`, `libzimg` / `zscale`, `libmp3lame`, `libopus`, `libvorbis`, the `ass` filter. `doctor` tells you which are present. The apt and gyan.dev builds carry all of them; some Homebrew bottles lack `libass` / `libfreetype` / `libzimg`, which `doctor` reports as missing.
-- Python 3.9+, standard library only
+- Python 3.10+ recommended, standard library only. 3.9 still works but is deprecated (end of life upstream; support ends in 3.0)
 - Node 16+ only for the `npx` installer
 
 `doctor`'s own introspection calls (`ffmpeg -filters`/`-encoders`/`-bsfs`/`-version`) time out after 10s and report `failed` rather than hanging forever — those are meant to be fast. Every tool's actual media-processing `ffmpeg` invocation (cut, fit, caption, ...) runs under `--timeout` (default 1800 s, `FFMPEG_SKILL_TIMEOUT`, `0` = none): past the limit the process is killed, its partial output removed, and the failure reported as `kind: timeout` (exit 124) — a legitimately long `--accurate` re-encode should raise the limit rather than run unbounded. `-nostdin` is always passed, so a hung ffmpeg process waiting on stdin cannot happen.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ffmpeg-skill
-description: 'Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files. Use this skill whenever the user mentions a video or audio file (mp4, mov, mkv, wav, m4a), footage, a clip, captions, subtitles, a reel or short, YouTube/Instagram/TikTok delivery, LUFS, sync, transcoding, ffmpeg, or asks to make something "60 seconds", "vertical", "louder", "captioned" — even when they do not say "edit". Python 3.9 standard library only, no cloud, no API keys.'
+description: 'Edit video and audio with local FFmpeg from natural-language requests: cut, trim, join, resize/reframe (9:16, 1:1), speed change, captions and subtitles (SRT/ASS, animated, karaoke), logos and text overlays, lower-thirds and titles, silence removal, multicam and external-mic sync, loudness normalisation, HDR/Dolby Vision to SDR, LUTs, background music with ducking, platform exports (YouTube, Reels, TikTok, X), compliance checks, scene detection and highlight reels, contact sheets to inspect results, and whole-edit project files. Use this skill whenever the user mentions a video or audio file (mp4, mov, mkv, wav, m4a), footage, a clip, captions, subtitles, a reel or short, YouTube/Instagram/TikTok delivery, LUFS, sync, transcoding, ffmpeg, or asks to make something "60 seconds", "vertical", "louder", "captioned" — even when they do not say "edit". Python 3.10+ standard library only (3.9 deprecated), no cloud, no API keys.'
 ---
 
 # ffmpeg-skill

package/bin/install.js

@@ -44,27 +44,54 @@ if (has('--help') || has('-h')) {
 // Windows Python installers commonly expose `python`/`py`, not `python3`. The Microsoft Store
 // app-execution alias is a real python3.exe that spawns (no ENOENT) and exits non-zero, so a
 // missing `error` is not proof an interpreter ran. Probe with a version check, then fall through.
-const PYTHON_PROBE = ['-c', 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'];
+// The probe also prints major.minor, so the installer can warn about a deprecated interpreter.
+const PYTHON_PROBE = ['-c', "import sys; sys.stdout.write('%d.%d' % sys.version_info[:2]); raise SystemExit(0 if sys.version_info >= (3, 9) else 1)"];
+
+// 2.11.0 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; `contract --json`'s
+// `deprecated`). The same line as scripts/_contract.py's PY39_DEPRECATION (a test keeps them equal).
+const PY39_DEPRECATION = 'warning: Python 3.9 is deprecated since ffmpeg-skill 2.11.0 (CPython 3.9 reached end of life in October 2025 and gets no security fixes); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.';
+
+function pythonDeprecation(version) {
+  return version === '3.9' ? PY39_DEPRECATION : null;
+}
 
 function pythonCandidates(platform) {
   return platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
 }
 
-function runWithPython(scriptArgs, platform, spawn) {
+// The first candidate that runs and is 3.9+: { cmd, version } (version "3.9", or null when the
+// probe printed nothing), or { missing: true, ... } when none is.
+function findPython(platform, spawn) {
   const candidates = pythonCandidates(platform);
   const run = spawn || spawnSync;
   let last = null;
   for (const cmd of candidates) {
-    const probe = run(cmd, PYTHON_PROBE, { stdio: 'ignore', timeout: 15000 });
+    const probe = run(cmd, PYTHON_PROBE, { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', timeout: 15000 });
     if (probe.error || probe.status !== 0) {
       last = probe;
       continue;
     }
-    return run(cmd, scriptArgs, { stdio: 'inherit' });
+    const out = typeof probe.stdout === 'string' ? probe.stdout.trim() : '';
+    return { cmd, version: /^\d+\.\d+$/.test(out) ? out : null };
   }
   return { missing: true, error: last && last.error, status: last && last.status, candidates };
 }
 
+function runWithPython(scriptArgs, platform, spawn) {
+  const py = findPython(platform, spawn);
+  if (py.missing) return py;
+  return (spawn || spawnSync)(py.cmd, scriptArgs, { stdio: 'inherit' });
+}
+
+// After an install: the one-line deprecation warning when the Python the skill will run on is 3.9.
+// `doctor` prints the same line itself (from Python), so it is not repeated for that subcommand.
+function warnDeprecatedPython(platform, spawn, warn) {
+  const py = findPython(platform, spawn);
+  const line = py.missing ? null : pythonDeprecation(py.version);
+  if (line) (warn || console.warn)(`\n  ${line}`);
+  return line;
+}
+
 function main() {
 // `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
 if (args[0] === 'contract' || args[0] === 'doctor') {
@@ -174,6 +201,7 @@ for (const t of targets) {
 
 if (!has('--uninstall')) {
   checkFfmpeg();
+  warnDeprecatedPython(process.platform, spawnSync);
   console.log('\nDone. Ask your agent things like "make this video 60 seconds and add captions".');
 }
 process.exit(failed ? 1 : 0);
@@ -183,4 +211,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { pythonCandidates, runWithPython };
+module.exports = { pythonCandidates, runWithPython, findPython, pythonDeprecation, warnDeprecatedPython, PY39_DEPRECATION };

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 (`2.10.7`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.9`) | 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`
@@ -81,8 +81,14 @@ on, the line says so.
 
 `contract --json` carries a top-level `deprecated` list, next to `contract_version`: one entry per
 thing the next major removes, `{"what", "since", "replacement", "removed_in", "where"}` with `where`
-naming the surface (`cli`, `json`, `mcp`, `behaviour`). It is empty in 2.0.0. `tests/test_contract.py`
-refuses a package.json major bump that still lists an entry that major should remove, or that
+naming the surface (`cli`, `json`, `mcp`, `behaviour`). It was empty in 2.0.0. Since 2.11.0 it lists one
+entry: **running on Python 3.9** (`where: behaviour`, `removed_in: 3.0.0`). CPython 3.9 reached end of life
+in October 2025 and gets no security fixes, but raising the floor is a break, so 2.x keeps running on 3.9
+(`requirements.python` stays `>=3.9`, and CI keeps testing it). It is deprecated, and Python 3.10+ is
+recommended: on 3.9, `doctor` and the `npx` installer print one stderr line,
+`warning: Python 3.9 is deprecated since ffmpeg-skill 2.11.0 (...); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.`
+Like every deprecation warning it is stderr only: `doctor --json`'s document has no key for it.
+`tests/test_contract.py` refuses a package.json major bump that still lists an entry that major should remove, or that
 comes before step 2's window has passed -- unless the waiver is written here, as 2.0.0's is.
 
 **2.0.0 waived the 90-day half of step 2.** Its deprecations date from 1.10.0 (2026-09-13), so
@@ -117,12 +123,12 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
 ```json
 {
   "contract_version": "1.0",
-  "deprecated": [],
+  "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.11.0", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.10.7", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.9", "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"},
+  "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.11.0, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
   "execution": {"shell": false, "arbitrary_executables": false, "network": false,
                 "model_downloads": {"when": "...", "in_process": {"faster-whisper": "..."},
                                     "child_process": {"parakeet-mlx": "...", "openai-whisper": "..."},
@@ -471,6 +477,30 @@ ffmpeg-full` does not put it on PATH and the lean build has no drawtext/subtitle
 else is substituted. `ffmpeg` and `ffprobe` (version strings) keep their meaning; the four keys are
 additive.
 
+`doctor`'s `ffmpeg_security` field compares the `ffmpeg` and `ffprobe` versions with a small table of
+high-severity FFmpeg CVEs and the first upstream release on each branch that carries the fix. The table is
+hand-maintained in `scripts/_contract.py` (`FFMPEG_ADVISORIES`), copied from
+<https://ffmpeg.org/security.html> and last checked on 2026-10-22; the document repeats both as `source`
+and `checked`. Nothing is fetched: the check is offline, like the rest of the skill. On that date it holds one row:
+
+| CVE | What | CVSS | First fixed upstream |
+|---|---|---|---|
+| CVE-2026-8461 ("PixelSmash") | MagicYUV decoder heap out-of-bounds write | 8.8 | 8.0.3 (8.0 branch), 8.1.2 (8.1), 9.0 (9.0); no 7.1.x, 7.0.x or 6.1.x release is listed with the fix |
+
+AISLE's CVE-2026-64830..64835 were not on security.html on that date, so they have no row yet.
+
+`{"source": "https://ffmpeg.org/security.html", "checked": "2026-10-22", "ffmpeg": {"version": "...", "status":
+"older_than_fix"|"not_older"|"unknown", "advisories": [{"cve", "name", "component", "kind", "cvss",
+"first_fix", "fix_on_branch", "branch"}]}, "ffprobe": {...}, "warnings": ["..."]}`. The leading upstream
+number is read from the version (`8.0.1-3ubuntu2` is 8.0.1). A version on a branch the table lists is
+compared with that branch's fixing release; a version on an older branch, which has no fixing release, with
+the oldest release that has it (`fix_on_branch: false`). A version with no release number (a git snapshot,
+`N-12345-g…`), or no binary, is `unknown` and never warned about. Each distinct version that is older gets one
+line in `warnings`, also printed to stderr (in plain and `--json` mode). The line says the build is older than
+the upstream fix and that a distribution package may have backported it without changing the version; it does
+not say the build is vulnerable, and it names an update command (apt for an Ubuntu/Debian version, else by
+platform). Like `gpu_encoders` and `fonts`, it never affects `ok`, any tool's `usable` or the exit code.
+
 `doctor`'s `gpu_encoders` field reports GPU-backed encoders (`nvenc`, `videotoolbox`, `qsv`,
 `vaapi`, `amf`) present in this ffmpeg *build*, read from `-encoders` alone — `{"status":
 "parsed"|"unparsed"|"failed"|"missing", "present": [...]}`. It proves the build shipped the

package/package.json

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

@@ -167,9 +167,19 @@ these had ever shown up before.
   `color_space=bt709` on the trixie/macOS/Windows jobs and the untagged case silently went untested
   there (#333's colour fixtures until 2.10.3). Relabel the frames `setparams=colorspace=unknown`
   before the encode, and assert the probe says unknown.
-- **The conda-forge 7.1.1 build deadlocks on `tpad` + `adelay`/`apad` (pad.py) and ignores
-  SIGTERM.** Debian's 7.1.5 in CI does not. Run pad tests against CI, not that build, and note
-  that the tools have no subprocess timeout to get an agent out of such a hang.
+- **FFmpeg 8.0.1 and conda-forge's 7.1.1 deadlock when one input feeds a `-vf` graph and an `-af` graph whose sound is
+  both delayed and padded** (`adelay` + `apad`, the shape pad.py used): no CPU, no progress, until
+  `--timeout`. First seen on conda-forge's 7.1.1 and filed as that build's quirk; Ubuntu 26.04's
+  8.0.1 (`ubuntu-latest`) has it too; Debian's 7.1.5 and 8.1.3 do not. pad.py puts both streams in
+  one `-filter_complex`, which runs on 5.1.1, 6.1.1, 7.0.2, 8.0.1 and 8.1.3. A tool that delays and
+  pads audio should do the same.
+- **FFmpeg 8.0 and 8.0.1's `aselect` passes every frame through** (its `activate` callback was lost
+  in the filter conversion; fixed in 8.0.2/8.1). Nothing fails: the picture is cut and the sound is
+  not. silence.py tags the kept frames with `ametadata=mode=add:...:enable='<expr>'` and keeps them with
+  `ametadata=mode=select`; do not use `aselect` for removal.
+- **FFmpeg 8.0, 8.0.1 and 8.1.0 draw the font's missing-glyph box at each line break of a multi-line
+  `drawtext`** (each line is shaped with its newline; fixed in 8.0.2/8.1.1). `ffmpeg_version()` cannot
+  tell 8.1.0 from 8.1.1; `drawtext_draws_newline_glyph()` reads the point release.
 - **Not a 7.1 issue, found while chasing it: `color --correct` desaturates a bt709-*tagged*
   source by ~8 % at identity settings on 6.1 and 7.1 alike** (113.6 → 103.9 saturation_avg):
   the RGB stages (exposure/colortemperature/colorbalance) make swscale go yuv→rgb with the

package/references/scripts.md

@@ -581,14 +581,15 @@ silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|es|d
            [--model MODEL] [--filler-list] [--max-cuts 400]
 ```
 Runs `silencedetect`, keeps `--margin` seconds of air around speech, drops
-gaps shorter than `--min-silence`, and re-encodes once with `select`/`aselect`
-(frame accurate). `--list` prints silences, kept ranges and seconds removed
+gaps shorter than `--min-silence`, and re-encodes once: `select` for the picture
+(frame accurate), the same ranges through `ametadata` for the sound (not `aselect`, which passes every frame
+through on FFmpeg 8.0 and 8.0.1). `--list` prints silences, kept ranges and seconds removed
 without rendering; `--edl` saves the kept ranges in `cut.py --segments` format
 so the user can edit the list by hand. Quiet rooms need `--threshold -40`
 to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed.
 
 **`--filler` (1.17)** removes filler words as well, through the same
-`keep_ranges()`/`aselect` graph with more, shorter ranges. It is **never**
+`keep_ranges()` graph with more, shorter ranges. It is **never**
 applied without measured word timings: pass `--words` (a whisper JSON carrying
 per-word `start`/`end`) or `--transcribe` (the same local engine `caption.py`
 uses, never required). There is no heuristic fallback — finding an "um" by
@@ -1128,6 +1129,10 @@ and that this machine can draw none of is `kind: input`, because that frame woul
 be blank. `--emoji none` strips the clusters from the drawn text, and a job whose
 emoji would fall to `mode: mono` is routed through libass (which has a font
 fallback chain) instead of drawtext (which does not, and would draw an empty box).
+A label that is drawn on more than one line (given with newlines, or wrapped to the
+frame) goes through libass the same way on FFmpeg 8.0, 8.0.1 and 8.1.0, whose drawtext
+draws the font's missing-glyph box at the end of every line but the last (fixed in
+8.0.2 and 8.1.1); `--text-render drawtext` keeps drawtext there and warns.
 
 Every drawn label goes to drawtext as `textfile=<path>:expansion=none`. The file
 is UTF-8, mode 0600, in a private per-run temp directory created with

package/scripts/_common/__init__.py

@@ -55,8 +55,8 @@ from _common.runner import (
     add_common, apply_common, _check_existing_output, refuse_existing_outputs, _check_no_overwrite_input, _check_output_path, child_args,
     child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, DEFAULT_TIMEOUT,
     _DRAWTEXT_PENDING, _DRAWTEXT_TMPDIR, _drawtext_tmpdir, dry_run_input_pending, _ENCODERS, _env_timeout,
-    ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, ffmpeg_exe, _FFMPEG_VERSION,
-    ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
+    ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, ffmpeg_exe, _FFMPEG_RELEASE, _FFMPEG_VERSION,
+    ffmpeg_release, ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,
     _odd_dimension_retry, _on_signal, _OutputLock, _pid_dead, place_output, PROBE_TIMEOUT, _progress_line,
     read_text_or_die, refuse_output_is_input, _remember_output, require_tool, run, run_analysis, _run_captured,
     run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, sibling_temp, _SIGNALS_INSTALLED, _stage_existing_output,
@@ -96,6 +96,7 @@ from _common.color import (
 )
 from _common.text import (
     ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align,
+    drawtext_draws_newline_glyph, is_multiline, NEWLINE_GLYPH_RELEASES,
     drawtext_shaping, drawtext_text_opts, emoji_asset_for, EMOJI_ASSET_HINT, emoji_clusters, emoji_codepoint_name,
     _EMOJI_COLOR_FAMILIES, _emoji_color_font, emoji_filter_chain, _emoji_name_candidates, EMOJI_RANGES,
     _EMOJI_REGIONAL, emoji_support, _EMOJI_SUPPORT_CACHE, _EMOJI_TAIL, escape_drawtext, _family_rank, FC_LANG,
@@ -145,7 +146,7 @@ class _Facade(_types.ModuleType):
     # own copy is the import-time binding and would read stale. Reads of these names go to the
     # defining module (audit 14, P1-1); every other name is a plain re-export of the same object.
     _LIVE = {
-        "_FFMPEG_VERSION": "runner", "_SIGNALS_INSTALLED": "runner",
+        "_FFMPEG_VERSION": "runner", "_FFMPEG_RELEASE": "runner", "_FFMPEG_RELEASE_READ": "runner", "_SIGNALS_INSTALLED": "runner",
         "_DRAWTEXT_TMPDIR": "runner", "_ENCODERS": "runner", "_CURRENT_CTX": "emit",
     }
 
@@ -189,14 +190,14 @@ __all__ = [
     "BEAT_REFRACTORY_S", "BEAT_WINDOW_S", "BEAT_SUPPORT_DIVISOR", "BEAT_ALIGN_DIVISOR",
     "BEAT_Z_FLOOR", "BEAT_Z_SPAN",
     "_onset_strength", "_pick_onsets", "_autocorrelation_peak", "_grid_score",
-    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align",
+    "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align", "drawtext_draws_newline_glyph", "is_multiline", "NEWLINE_GLYPH_RELEASES",
     "_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
     "dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
     "emoji_codepoint_name", "_EMOJI_COLOR_FAMILIES", "_emoji_color_font", "emoji_filter_chain",
     "_emoji_name_candidates", "EMOJI_RANGES", "_EMOJI_REGIONAL", "emoji_support", "_EMOJI_SUPPORT_CACHE",
     "_EMOJI_TAIL", "encoder_args", "_ENCODERS", "_env_timeout", "ERROR_CODE", "ERROR_RETRYABLE", "escape_drawtext",
     "escape_filter_path", "EVEN_SCALE", "_execute", "_fail", "_family_rank", "FC_LANG", "_fc_list_fonts",
-    "FC_UNKNOWN", "ffmpeg_base", "ffmpeg_encoders", "ffmpeg_exe", "_FFMPEG_VERSION", "ffmpeg_version", "fingerprint",
+    "FC_UNKNOWN", "ffmpeg_base", "ffmpeg_encoders", "ffmpeg_exe", "_FFMPEG_RELEASE", "_FFMPEG_VERSION", "ffmpeg_release", "ffmpeg_version", "fingerprint",
     "flush_drawtext_textfiles", "fold_bt709_matrix", "fmt_secs", "fmt_smpte_time", "fmt_srt_time", "font_covers_script",
     "font_family_for_script", "font_family_of_file", "FONT_FLAG_HINT", "font_for_script", "FONT_INSTALL_HINT",
     "fonts_dir_covers_script", "_fraction", "has_emoji", "info", "INSTALL_HINTS", "install_signal_handlers",

package/scripts/_common/drawtext.py

@@ -10,7 +10,7 @@ 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_exe, ffmpeg_version
+from _common.runner import STATE, _DRAWTEXT_PENDING, _drawtext_tmpdir, ffmpeg_exe, ffmpeg_release, ffmpeg_version
 
 
 def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
@@ -97,6 +97,26 @@ def escape_drawtext(text: str) -> str:
     )
 
 
+# FFmpeg 8.0 rewrote drawtext's line splitter to hand harfbuzz `p - start` bytes after GET_UTF8 had
+# already stepped past the line break, so every line but the last is shaped WITH its newline and
+# the font's .notdef box is drawn at its end (and counted in text_w). 8.0.2 and 8.1.1 measure the
+# length before the step; 8.0, 8.0.1 (Ubuntu 26.04) and 8.1 ship the bug.
+NEWLINE_GLYPH_RELEASES = frozenset({(8, 0, 0), (8, 0, 1), (8, 1, 0)})
+
+
+def drawtext_draws_newline_glyph() -> bool:
+    """Whether this build's drawtext draws a box at each line break of a multi-line text (see
+    NEWLINE_GLYPH_RELEASES). A git or vendor build without a release number is taken to be fixed:
+    the fix is on master, and a guess the other way would reroute every multi-line title."""
+    return ffmpeg_release() in NEWLINE_GLYPH_RELEASES
+
+
+def is_multiline(text: "Optional[str]") -> bool:
+    """`text` draws as more than one line (the normalisation drawtext_text_opts() applies)."""
+    cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n").rstrip("\n")
+    return "\n" in cleaned
+
+
 def drawtext_center_align() -> str:
     """`:text_align=C` for a centred drawtext, so each line of a multi-line label is centred on
     its own. The option arrived in FFmpeg 6.1 (5.x and 6.0 reject it); there the block is still

package/scripts/_common/runner.py

@@ -125,6 +125,30 @@ def ffmpeg_version() -> "Tuple[int, int]":
     return _FFMPEG_VERSION
 
 
+_FFMPEG_RELEASE: "Optional[Tuple[int, int, int]]" = None
+_FFMPEG_RELEASE_READ = False
+
+
+def ffmpeg_release() -> "Optional[Tuple[int, int, int]]":
+    """(major, minor, patch) of a tagged FFmpeg release on PATH ("8.0.1-3ubuntu2", "n8.1" ->
+    (8, 1, 0)), or None for a git/vendor build or an unreadable one. ffmpeg_version()'s
+    major.minor is the right test for an option spelling; this is for a bug that one point
+    release introduced and the next one fixed, which major.minor cannot tell apart. Read from
+    ffprobe for the same dry-run reason; cached per process."""
+    global _FFMPEG_RELEASE, _FFMPEG_RELEASE_READ
+    if not _FFMPEG_RELEASE_READ:
+        _FFMPEG_RELEASE_READ = True
+        try:
+            out = subprocess.run([ffmpeg_exe("ffprobe")[0] or "ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
+                                 timeout=PROBE_TIMEOUT).stdout
+            m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)(?:\.(\d+))?", out)
+            if m:
+                _FFMPEG_RELEASE = (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    return _FFMPEG_RELEASE
+
+
 def _homebrew_full_build(path: str, name: str) -> str:
     """On macOS, the keg-only `ffmpeg-full` binary that should replace `path`, or "".
 

package/scripts/_common/text.py

@@ -31,7 +31,8 @@ from _common.emoji import (
 )
 from _common.drawtext import (
     drawtext_boxborderw, SHAPING_SCRIPTS, BIDI_SCRIPTS, _SHAPING_BUILD_CACHE, drawtext_shaping, needs_shaping,
-    escape_drawtext, drawtext_text_opts, drawtext_center_align,
+    escape_drawtext, drawtext_text_opts, drawtext_center_align, NEWLINE_GLYPH_RELEASES,
+    drawtext_draws_newline_glyph, is_multiline,
 )
 from _common.wrap import (
     ADVANCE_EM, NO_SPACE_SCRIPTS, NO_BOUNDARY_SCRIPTS, LATIN_EM, LEADING_VOWELS, _is_mark, _char_em,

package/scripts/_contract.py

@@ -444,6 +444,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given"}}
     elif name == "look":
         extra = {"outputs": {"type": "array", "items": {"type": "string"}}}
+    elif name == "overlay":
+        extra = {"notes": {"type": "array", "items": {"type": "string"}, "description": "a multi-line --text on FFmpeg 8.0, 8.0.1 or 8.1.0, whose drawtext draws a box at each line break (fixed in 8.0.2 and 8.1.1)"}}
     elif name == "render":
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]},
                  "plan": {"type": "string", "description": "when the argument was a plan.json (written by <tool> --plan): its path"},
@@ -722,6 +724,126 @@ def _version_line(binary: str) -> Optional[str]:
     return m.group(1) if m else (first[0] if first else "unknown")
 
 
+# ----------------------------------------------------------------------------- FFmpeg security advisories
+# doctor's `ffmpeg_security`: a small, dated, hand-maintained table of high-severity FFmpeg CVEs and
+# the first upstream point release on each branch that carries the fix. ffmpeg-skill does not ship
+# FFmpeg, so a user stays exposed to a decoder bug until they upgrade; doctor says so. It reads the
+# table and the local `-version` line only -- no network call, ever (execution.network: false).
+#
+# Source: https://ffmpeg.org/security.html (each release section lists the CVEs it fixes), checked
+# on FFMPEG_ADVISORIES_CHECKED. A branch absent from `fixed_in` had no release listed with the fix
+# on that date. Only CVEs that page lists go in: AISLE's batch (CVE-2026-64830..64835) was not on it
+# on 2026-10-22, so it has no row yet -- add one, with its releases, when the page lists them.
+# When editing: update FFMPEG_ADVISORIES_CHECKED, docs/contract.md and the CHANGELOG together.
+FFMPEG_ADVISORY_SOURCE = "https://ffmpeg.org/security.html"
+FFMPEG_ADVISORIES_CHECKED = "2026-10-22"
+FFMPEG_ADVISORIES: List[Dict[str, Any]] = [
+    {"cve": "CVE-2026-8461", "name": "PixelSmash", "component": "MagicYUV decoder",
+     "kind": "heap out-of-bounds write", "cvss": 8.8,
+     # security.html lists the fix under 9.0, 8.1.2 and 8.0.3; no 7.1.x/7.0.x/6.1.x release carries it
+     "fixed_in": {"8.0": "8.0.3", "8.1": "8.1.2", "9.0": "9.0"}},
+]
+
+
+def _parse_ffmpeg_version(text: Optional[str]) -> Optional[tuple]:
+    """(major, minor, patch) from an `ffmpeg -version` token: `6.1.1`, `8.0`, `n7.1.2`, and distro
+    builds that append to the upstream number (`8.0.1-3ubuntu2`, `7.1.2-0+deb13u1`,
+    `8.1.2-full_build-www.gyan.dev`). None for anything else -- a git snapshot (`N-12345-g...`,
+    `2026-10-01-git-...`) has no release number to compare, and a guess would be a false alarm."""
+    if not text:
+        return None
+    m = re.match(r"n?(\d+)\.(\d+)(?:\.(\d+))?(?![\d.])", text.strip())
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
+
+
+def _vstr(v: tuple) -> str:
+    return ".".join(str(x) for x in (v if v[2] else v[:2]))
+
+
+def _advisory_hits(version: Optional[str]) -> Optional[List[Dict[str, Any]]]:
+    """The table's rows this version is older than (None: the version could not be parsed). A
+    version on a branch the table lists is compared with that branch's fixing release; one on an
+    older branch with no fixing release is compared with the oldest release that has the fix."""
+    v = _parse_ffmpeg_version(version)
+    if v is None:
+        return None
+    hits = []
+    branch = f"{v[0]}.{v[1]}"
+    for adv in FFMPEG_ADVISORIES:
+        fixes = {k: _parse_ffmpeg_version(f) for k, f in adv["fixed_in"].items()}
+        if branch in fixes:
+            first, on_branch = fixes[branch], True
+        else:
+            first, on_branch = min(fixes.values()), False
+        if v < first:
+            hits.append({"cve": adv["cve"], "name": adv["name"], "component": adv["component"], "kind": adv["kind"],
+                         "cvss": adv["cvss"], "first_fix": _vstr(first), "fix_on_branch": on_branch, "branch": branch})
+    return hits
+
+
+def _update_hint(version: str, source: Optional[str]) -> str:
+    """How to update the FFmpeg this version string came from, as one short phrase."""
+    low = version.lower()
+    if "ubuntu" in low or "+deb" in low or "debian" in low:
+        return "sudo apt update && sudo apt install --only-upgrade ffmpeg"
+    system = platform.system()
+    if system == "Darwin":
+        return "brew upgrade ffmpeg-full" if source == "homebrew-ffmpeg-full" else "brew upgrade ffmpeg, or the package manager it came from"
+    if system == "Windows":
+        return "winget upgrade Gyan.FFmpeg, or a newer build from https://ffmpeg.org/download.html"
+    if system == "Linux":
+        return "your distribution's package update, e.g. sudo apt install --only-upgrade ffmpeg or sudo dnf upgrade ffmpeg"
+    return "a newer build from https://ffmpeg.org/download.html"
+
+
+def _advisory_warning(binary: str, version: str, hits: List[Dict[str, Any]], source: Optional[str]) -> str:
+    """One stderr/`warnings` line. It never says the build IS vulnerable: a distro package
+    (Ubuntu `8.0.1-3ubuntu2`, Debian `+deb13u1`) backports fixes without changing the upstream
+    number, and only the upstream number is visible here."""
+    parts = []
+    for h in hits:
+        where = (f"first fixed on the {h['branch']} branch in {h['first_fix']}" if h["fix_on_branch"]
+                 else f"no {h['branch']} release is listed with the fix; the oldest that has it is {h['first_fix']}")
+        parts.append(f"{h['cve']} ({h['component']} {h['kind']}, CVSS {h['cvss']:g}; {where})")
+    return (f"warning: {binary} {version} is older than the first upstream FFmpeg release that fixes "
+            f"{'; '.join(parts)}. A distribution package may have backported the fix without changing the "
+            f"upstream version, so this is not proof the build is vulnerable: update it "
+            f"({_update_hint(version, source)}). Source: {FFMPEG_ADVISORY_SOURCE}, checked {FFMPEG_ADVISORIES_CHECKED}.")
+
+
+def ffmpeg_security(versions: Dict[str, Optional[str]], sources: Optional[Dict[str, Optional[str]]] = None) -> Dict[str, Any]:
+    """doctor's `ffmpeg_security`: per binary {version, status, advisories}, and `warnings`, one line
+    per distinct version that is older than a fix. `status`: `older_than_fix`, `not_older`, or
+    `unknown` (no binary, or a version this table cannot compare -- which produces no warning).
+    Informational like `fonts`/`gpu_encoders`: it never moves `ok`, a tool's `usable` or the exit code."""
+    sources = sources or {}
+    out: Dict[str, Any] = {"source": FFMPEG_ADVISORY_SOURCE, "checked": FFMPEG_ADVISORIES_CHECKED, "warnings": []}
+    warned = set()
+    for binary in ("ffmpeg", "ffprobe"):
+        version = versions.get(binary)
+        hits = _advisory_hits(version)
+        status = "unknown" if hits is None else ("older_than_fix" if hits else "not_older")
+        out[binary] = {"version": version, "status": status, "advisories": hits or []}
+        if hits and version not in warned:
+            warned.add(version)
+            out["warnings"].append(_advisory_warning(binary, str(version), hits, sources.get(binary)))
+    return out
+
+
+# 2.11.0 deprecates Python 3.9 (docs/contract.md "Deprecation policy"; DEPRECATED below). The same
+# line is printed by bin/install.js (PY39_DEPRECATION there; a test keeps the two equal).
+PY39_DEPRECATION = ("warning: Python 3.9 is deprecated since ffmpeg-skill 2.11.0 (CPython 3.9 reached end of life "
+                    "in October 2025 and gets no security fixes); it still works in 2.x and support ends in 3.0.0: use Python 3.10+.")
+
+
+def python_deprecation(version_info: Optional[tuple] = None) -> Optional[str]:
+    """The deprecation line for this interpreter, or None when it is not a deprecated one."""
+    vi = tuple(version_info if version_info is not None else sys.version_info)[:2]
+    return PY39_DEPRECATION if vi == (3, 9) else None
+
+
 def _exe_report() -> Dict[str, Any]:
     """`ffmpeg_path` / `ffmpeg_source` / `ffprobe_path` / `ffprobe_source`: which binary the tools run
     and why ("path": what PATH resolves; "homebrew-ffmpeg-full": macOS, a lean Homebrew ffmpeg on
@@ -973,12 +1095,16 @@ def doctor() -> Dict[str, Any]:
     notes = [f"filter:drawtext: {drawtext_probe['note']}"] if drawtext_probe and drawtext_probe.get("note") else []
     notes += [f"{cap}: not in this ffmpeg build; the tools that need it encode with {alt[8:]} (VideoToolbox) instead, so their output is "
               "not CRF-equivalent (the result's `encoder`/`hw` say so)" for cap, alt in sorted(covered.items())]
+    versions = {"ffmpeg": _version_line("ffmpeg"), "ffprobe": _version_line("ffprobe")}
+    exes = _exe_report()
     return {
         "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
-        "ffmpeg": _version_line("ffmpeg"),
-        "ffprobe": _version_line("ffprobe"),
-        **_exe_report(),
+        "ffmpeg": versions["ffmpeg"],
+        "ffprobe": versions["ffprobe"],
+        **exes,
+        # non-fatal: never part of `ok`, `usable` or the exit code
+        "ffmpeg_security": ffmpeg_security(versions, {b: exes.get(f"{b}_source") for b in versions}),
         "available": available,
         "missing": missing_required,
         "missing_optional": missing_optional,
@@ -1274,7 +1400,13 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
 # step 1 (this list, --help text and the CHANGELOG) in a minor, step 2 keeps it working, step 3
 # removes it in the major. `where` says which surface a caller sees it on. Empty at 2.0.0: all
 # five 1.10.0 deprecations were settled by it (REMOVED below).
-DEPRECATED: List[Dict[str, str]] = []
+DEPRECATED: List[Dict[str, str]] = [
+    # CPython 3.9 reached end of life in October 2025. Raising the floor is a break, so 2.x keeps
+    # running on it (CI still tests 3.9) and doctor / bin/install.js print PY39_DEPRECATION.
+    {"what": "running on Python 3.9 (the requirements.python floor)",
+     "since": "2.11.0", "removed_in": "3.0.0", "where": "behaviour",
+     "replacement": "Python 3.10 or later; on 3.9, doctor and the npx installer print a one-line warning"},
+]
 
 # What 2.0.0 removed or changed, with the version that deprecated each: the "Removed" half of the
 # policy's step 3, kept in the contract so a caller migrating from 1.x can diff it instead of reading
@@ -1465,7 +1597,20 @@ def mcp_tool(spec: Dict[str, Any]) -> Dict[str, Any]:
     descriptions verbatim (the same ~250 characters repeated 42 times in every tools/list dump);
     it now goes once into the server's `initialize` response (`instructions`) instead, so a tool's
     own description stays its own one-line sentence."""
-    return {"name": spec["name"], "description": spec["description"], "inputSchema": mcp_input_schema(spec)}
+    return {"name": spec["name"], "description": spec["description"], "inputSchema": mcp_input_schema(spec),
+            "annotations": mcp_annotations(spec)}
+
+
+def mcp_annotations(spec: Dict[str, Any]) -> Dict[str, Any]:
+    """MCP ToolAnnotations (spec 2025-06-18) derived from the ToolSpec flags. Hints only: clients
+    must not treat them as a security boundary. Every tool runs locally (no open world); none edits
+    its input in place; a tool that writes nothing is read-only."""
+    writes = bool(spec.get("produces_artifact")) or bool(spec.get("mutates_input"))
+    return {"title": spec["name"],
+            "readOnlyHint": not writes,
+            "destructiveHint": bool(spec.get("mutates_input")),
+            "idempotentHint": spec.get("idempotency_hint") in ("bit_exact", "content_equivalent", "cached"),
+            "openWorldHint": False}
 
 
 def mcp_tools(detect: bool = False) -> List[Dict[str, Any]]:
@@ -1499,7 +1644,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             },
             "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", "node": ">=16 (npx installer only)"},
+        "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.11.0, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
         "execution": {
             "shell": False,
             "arbitrary_executables": False,
@@ -1563,6 +1708,13 @@ def main() -> int:
     args = ap.parse_args()
     if args.command == "doctor":
         d = doctor()
+        # Advisories, never failures: on stderr in both modes, so `doctor --json`'s stdout stays one
+        # JSON document. The FFmpeg ones are also in the document (`ffmpeg_security.warnings`); the
+        # Python 3.9 deprecation is stderr-only, as every deprecation warning is (docs/contract.md
+        # "Deprecation policy" step 1), and machine-readable in `contract --json`'s `deprecated`.
+        for line in [python_deprecation()] + d["ffmpeg_security"]["warnings"]:
+            if line:
+                print(line, file=sys.stderr)
         if args.json:
             print(json.dumps(d, indent=2, sort_keys=True))
         else:

package/scripts/graphics.py

@@ -39,7 +39,7 @@ from _common import (aac_args, add_common, brand_caption_style, script_font_for_
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
                      EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
-                     SAFE_WIDTH_FRACTION)
+                     SAFE_WIDTH_FRACTION, drawtext_draws_newline_glyph, is_multiline, _DRAWTEXT_PENDING)
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 
 # where the template's text chain goes in a filter_complex it builds (graphics.main fills it in)
@@ -63,7 +63,9 @@ def font_opts(brand: dict, font: Optional[str], font_file: Optional[str], script
     return f"font='{escape_drawtext(font or brand.get('font', 'DejaVu Sans'))}'"
 
 
-def main() -> int:
+def main(force_route: Optional[str] = None) -> int:
+    """`force_route` is the second pass of an auto run whose drawtext labels came out multi-line on a
+    build that draws a box at every line break (see the check after the templates)."""
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_gfx.<ext>)")
@@ -104,7 +106,8 @@ def main() -> int:
     ap.add_argument("--text-render", choices=["auto", "ass", "drawtext"], default="auto",
                     help="which renderer draws the template's text: 'auto' (default) uses libass for "
                          "scripts drawtext cannot shape (Devanagari, Bengali, Tamil, Thai, Lao ...) and for "
-                         "emoji overlays, and drawtext for everything else -- Latin/CJK/Arabic frames are "
+                         "emoji overlays, and for multi-line text on FFmpeg 8.0, 8.0.1 and 8.1.0 (their drawtext draws "
+                         "a box at each line break), and drawtext for everything else -- Latin/CJK/Arabic frames are "
                          "pixel-identical to 1.14 (the drawtext command itself changed: the label is "
                          "passed as textfile=, not text=); 'ass' always uses libass; 'drawtext' forces the old renderer and is "
                          "refused for a script it cannot shape")
@@ -244,6 +247,8 @@ def main() -> int:
             kind="input")
     route = "ass" if (args.text_render == "ass" or
                       (args.text_render == "auto" and (shaping or emoji_mode == "png"))) else "drawtext"
+    if force_route:
+        route = force_route
     # drawtext loads exactly ONE font file and has no fallback chain, so "whatever glyph the text
     # font has" for an emoji is an empty box on DejaVu Sans and on every script font: reporting
     # mode "mono" from the drawtext route is a claim the frame does not keep. libass DOES have a
@@ -550,6 +555,20 @@ def main() -> int:
                      outline=float(max(2, fs // 40)), outline_color=bg, start=ks, end=ke,
                      scale_t=(0, seg * 500, 115))
 
+    # FFmpeg 8.0, 8.0.1 and 8.1 draw the font's missing-glyph box at the end of every line but the
+    # last of a multi-line drawtext (and widen text_w by it). Every template lays out the same
+    # elements for libass, so an auto run whose labels came out multi-line -- given that way or
+    # wrapped to the frame above -- is laid out again on that route; a pinned drawtext run says so.
+    if route == "drawtext" and drawtext_draws_newline_glyph() and any(is_multiline(t) for t in _DRAWTEXT_PENDING.values()):
+        if args.text_render == "auto" and not force_route:
+            info("multi-line text: this ffmpeg's drawtext draws a box at each line break "
+                 "(FFmpeg 8.0-8.0.1 and 8.1.0; fixed in 8.0.2/8.1.1), so it is rendered through libass")
+            _DRAWTEXT_PENDING.clear()
+            return main(force_route="ass")
+        info("warning: this ffmpeg's drawtext draws a box at each line break of a multi-line label "
+             "(FFmpeg 8.0-8.0.1 and 8.1.0; fixed in 8.0.2/8.1.1): drop --text-render drawtext to render it "
+             "through libass, or upgrade FFmpeg")
+
     output = args.output or default_output(args.input, "gfx")
     ass_path = None
     emoji_result = None

package/scripts/overlay.py

@@ -25,7 +25,7 @@ import sys
 from typing import List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
-from _common import STATE, script_font_for_text, drawtext_text_opts, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, matrix_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, script_font_for_text, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, matrix_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
 
 # Per-edge margins: a platform's UI does not cover the same fraction of every edge (TikTok's
 # like column is 14 % of the width, its description block 22 % of the height), so a position
@@ -144,6 +144,7 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    notes: List[str] = []
 
     brand = load_brand(args.brand)
     if args.logo:
@@ -334,6 +335,12 @@ def main() -> int:
         x, y = position_exprs(args.position, args.margin, text_mode=True, margins=safe_margins)
         # 1.15: the text goes in a FILE with expansion off, so `'` and `%` survive verbatim
         # (they used to be dropped by escape_drawtext) and no character can reach the graph parser.
+        if is_multiline(args.text) and drawtext_draws_newline_glyph():
+            # overlay has no libass route to send it to (graphics.py's --text-render auto does)
+            notes.append("this ffmpeg's drawtext (FFmpeg 8.0, 8.0.1 and 8.1.0; fixed in 8.0.2 and 8.1.1) draws "
+                         "the font's missing-glyph box at the end of every line but the last of a multi-line "
+                         "--text: draw multi-line text with graphics.py or caption.py, or upgrade FFmpeg")
+            info("warning: " + notes[-1])
         opts = [drawtext_text_opts(args.text), f"fontsize={args.font_size}", f"x={x}", f"y={y}",
                 f"borderw={args.border}", f"bordercolor={args.border_color}"]
         if args.font_file:
@@ -360,7 +367,7 @@ def main() -> int:
     if not STATE.dry_run:
         result = probe(output, role="output")
         info(f"wrote {output} ({fmt_secs(result['duration'])})")
-    emit(output, dropped_non_av_streams=dropped_streams)
+    emit(output, dropped_non_av_streams=dropped_streams, **({"notes": notes} if notes else {}))
     return 0
 
 

package/scripts/pad.py

@@ -16,7 +16,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, drawn_chain, emit, EVEN_SCALE, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs, run
 
 
 def main() -> int:
@@ -50,10 +50,18 @@ def main() -> int:
     # a --color with chroma lands in the BT.709 the output is tagged with (tpad's own YUV is BT.601
     # before FFmpeg 7.1, and for an untagged picture after it); black is the same under every matrix
     vf = drawn_chain(tpad + args.color, meta, [args.color], tpad + "black")
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    cmd = ffmpeg_base() + ["-i", args.input]
     if has_audio:
+        # One -filter_complex, not a -vf and an -af: the ffmpeg scheduler of Ubuntu 26.04's 8.0.1 and
+        # conda-forge's 7.1.1 (not Debian's 7.1.5 or 8.1) deadlocks with no CPU use when one demuxer feeds two simple
+        # graphs and the audio one both delays its input and pads the tail. One graph reading both
+        # streams runs on 5.1-8.1 alike. run() only adds an even scale to a -vf, so add it here.
+        v = meta["video"]
+        even = EVEN_SCALE + "," if (v.get("width") or 0) % 2 or (v.get("height") or 0) % 2 else ""
         af = f"adelay={int(args.start * 1000)}:all=1,apad=pad_dur={args.end:.3f}"
-        cmd += ["-map", "0:a:0?", "-af", af]
+        cmd += ["-filter_complex", f"[0:v:0]{even}{vf}[v];[0:a:0]{af}[a]", "-map", "[v]", "-map", "[a]"]
+    else:
+        cmd += ["-vf", vf, "-map", "0:v:0"]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta)
     if has_audio:

package/scripts/silence.py

@@ -3,7 +3,7 @@
 
 Detects quiet stretches with ffmpeg's silencedetect, keeps a margin on each
 side so words are not clipped, drops gaps shorter than --min-silence, and
-writes a frame-accurate re-encode in one pass (select/aselect filters).
+writes a frame-accurate re-encode in one pass (select, and ametadata for the sound).
 
 Examples:
   python3 silence.py talk.mp4                                 # -35 dB, gaps >= 0.6 s, 0.15 s margin
@@ -312,7 +312,7 @@ def main() -> int:
         silences = detect(args.input, args.threshold, args.min_silence)
     filler_info, filler_ranges = resolve_filler(args, meta) if args.filler else (None, [])
     # One sorted, merged removal list through the graph the tool already has: filler removal IS
-    # time-range removal, so it reuses keep_ranges() and the same aselect/concat chain.
+    # time-range removal, so it reuses keep_ranges() and the same select chain.
     removals = merge_spans(list(silences) + list(filler_ranges))
     keeps = keep_ranges(removals, duration, args.margin, args.min_keep)
     kept = sum(e - s for s, e in keeps)
@@ -403,7 +403,13 @@ def main() -> int:
     output = args.output or default_output(args.input, "tight")
     expr = "+".join(f"between(t,{s:.3f},{e:.3f})" for s, e in keeps)
     vf = f"select='{expr}',setpts=N/FRAME_RATE/TB"
-    af = f"aselect='{expr}',asetpts=N/SR/TB"
+    # Not `aselect='{expr}'`: FFmpeg 8.0 and 8.0.1 (Ubuntu 26.04's apt build) ship an aselect that
+    # passes every frame through (its activate callback was lost when the filter was converted;
+    # fixed in 8.0.2/8.1), which cut the picture and left the sound whole. Tagging the frames the
+    # expression keeps (timeline `enable`, the same per-frame t) and selecting the tagged ones keeps
+    # exactly the frames aselect keeps, on every release, in a command no longer than before.
+    af = (f"ametadata=mode=add:key=ffskill_keep:value=1:enable='{expr}',"
+          "ametadata=mode=select:key=ffskill_keep,asetpts=N/SR/TB")
     cmd = ffmpeg_base() + ["-i", args.input]
     audio_only = is_audio_output(output) or not meta.get("video")
     if audio_only: