Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

fix: FFmpeg 8.0.1 (Ubuntu 26.04) failures; doctor CVE advisory; deprecate Python 3.9 (#346)

Shogo Kajiyama0581f341467e
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7351736..d6d8f66 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,8 @@ jobs:
include:
- os: ubuntu-latest
python: "3.13"
- runs-on: ${{ matrix.os }}
+ # ubuntu-latest is Ubuntu 26.04, which has no Python 3.9 build; keep 3.9 on the newest image that does
+ runs-on: ${{ matrix.python == '3.9' && startsWith(matrix.os, 'ubuntu') && 'ubuntu-24.04' || matrix.os }}
name: test (${{ matrix.os }}, py${{ matrix.python }})
steps:
- uses: actions/checkout@v7
@@ -120,7 +121,7 @@ jobs:
# contract and end-to-end suites pass. The tarball is pinned by version, not "release".
test-ffmpeg-5:
name: test (ubuntu-latest, py3.9, ffmpeg 5.1.1 static)
- runs-on: ubuntu-latest
+ runs-on: ubuntu-24.04 # no Python 3.9 build for Ubuntu 26.04 (ubuntu-latest)
steps:
- uses: actions/checkout@v7
with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 416b88b..61932b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,22 @@
## Unreleased
-(nothing yet)
+### Added
+
+- **`doctor` warns when the FFmpeg it runs is older than the upstream fix for a known high-severity CVE.** ffmpeg-skill does not ship FFmpeg, so a decoder bug in the installed build stays until the user upgrades it. `doctor --json` has a new `ffmpeg_security` field (`source`, `checked`, per-binary `version`/`status`/`advisories`, `warnings`), and each older version gets one `warning:` line on stderr. The table is small, dated and hand-maintained from https://ffmpeg.org/security.html (checked 2026-10-22). It holds CVE-2026-8461 ("PixelSmash", MagicYUV decoder heap out-of-bounds write, CVSS 8.8), fixed in 8.0.3, 8.1.2 and 9.0. A version on an older branch with no fixed release (7.1, 6.1, ...) is compared with 8.0.3. The line never says the build is vulnerable: an Ubuntu (`8.0.1-3ubuntu2`) or Debian (`+deb13u1`) package may carry the fix as a backport under the old number, and the line says so and names the update command. An unparseable version (a git snapshot) gets no warning. It is advice only: `ok`, every tool's `usable` and the exit code are unchanged, and nothing is fetched. AISLE's CVE-2026-64830..64835 are not on security.html yet and have no row.
+
+### Deprecated
+
+- **Python 3.9** (since 2.11.0, removed in 3.0.0). CPython 3.9 reached end of life in October 2025 and gets no security fixes. It still works throughout 2.x: the floor stays `>=3.9` and CI keeps testing it. On 3.9, `doctor` and the `npx` installer print one stderr line naming the replacement, Python 3.10+. `contract --json`'s `deprecated` list has the entry, and `requirements.python` says 3.10+ is recommended.
+
+### Fixed
+
+Three failures on Ubuntu 26.04 (`ubuntu-latest` since 2026-10-21), whose apt FFmpeg is 8.0.1. Each is an FFmpeg bug in specific releases; the tools now behave the same on 5.1.1, 6.1.1, 7.0.2, 8.0.1 and 8.1.3, the builds they were run on.
+
+- **`pad.py` no longer hangs on a clip with sound.** FFmpeg 8.0.1 (and conda-forge's 7.1.1, though not Debian's 7.1.5) deadlocks with no CPU use when one input feeds a `-vf` graph and an `-af` graph whose sound both starts late (`adelay`) and is padded at the end (`apad`). 8.1.3 does not. The job sat until `--timeout` (1800 s), with `--end 0` too. This is the conda-forge 7.1.1 hang `references/ci-platform-pitfalls.md` recorded as one build's quirk. Both streams now go through one `-filter_complex`. An odd-sized source gets its even scale in that graph, because `run()`'s retry adds one only to a `-vf`.
+- **`silence.py` cuts the sound as well as the picture.** FFmpeg 8.0 and 8.0.1 ship an `aselect` that passes every frame through: its `activate` callback was lost when the filter was converted, and 8.0.2 and 8.1 restore it. On those builds a 12 s talk came out with 6.75 s of picture and 12 s of sound (the container reported 12.01 s), and `--filler` removed nothing. The sound is now cut by tagging the frames the same `between()` expression keeps (`ametadata=mode=add` with a timeline `enable`) and keeping the tagged ones (`ametadata=mode=select`). That keeps exactly the frames `aselect` kept on every other release, in a command no longer than before.
+- **Multi-line titles and lower-thirds have no box at the line break.** FFmpeg 8.0, 8.0.1 and 8.1.0 pass each line of a multi-line `drawtext` to HarfBuzz with its newline, so the font's missing-glyph box is drawn at the end of every line but the last and counted in `text_w`. 8.0.2 and 8.1.1 fix it. On those releases `graphics.py --text-render auto` renders a label that is drawn on more than one line through libass (`text_renderer: "ass"`), whether the newline was given or added by the wrap. A pinned `--text-render drawtext` keeps drawtext and warns. `overlay.py --text`, which has no libass route, warns and adds a `notes` line. The release is read with a new `ffmpeg_release()`, because `ffmpeg_version()`'s major.minor cannot tell 8.1.0 from 8.1.1.
+- ci: the Python 3.9 jobs run on `ubuntu-24.04`, since Ubuntu 26.04 has no Python 3.9 build.
## 2.10.8
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0c8cfb6..f9bc618 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -47,7 +47,8 @@ npm run release-check # packaging + installer + MCP + doctor + full suite
python3 scripts/_contract.py doctor # what this machine can actually run
```
-Python 3.9+ standard library only — no new runtime dependencies. Every script
+Python 3.9+ standard library only — no new runtime dependencies. 3.9 is deprecated since 2.11.0 and
+still runs in CI until 3.0 drops it, so code must keep working on it until then. Every script
must keep working with nothing beyond `ffmpeg`/`ffprobe` on `PATH`.
## Tests
diff --git a/README.md b/README.md
index 158367d..0413ae8 100644
--- a/README.md
+++ b/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).
@@ -417,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 |
|---|---|---|
@@ -525,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.
diff --git a/SKILL.md b/SKILL.md
index db24de6..eef25a7 100644
--- a/SKILL.md
+++ b/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
diff --git a/bin/install.js b/bin/install.js
index 81a3de7..96c9aef 100755
--- a/bin/install.js
+++ b/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 };
diff --git a/docs/contract.md b/docs/contract.md
index 50fa334..2bbb678 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -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.8", "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
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 9513cc5..9138b5b 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -1650,3 +1650,54 @@ not a new file format this tool would have to maintain.
pending intermediate and a plan for it is no plan. A missing `image` is unchanged: a dry run
still plans it and a real run fails in the overlays stage. Code: `render.main()`. Test:
`test_render_video_overlay_refusals_and_dry_run_plan`.
+
+## Unreleased — FFmpeg 8.0.1 (Ubuntu 26.04)
+
+- **`pad.py` builds one `-filter_complex` for a clip with sound, not a `-vf` and an `-af`.** On
+ 8.0.1 and conda-forge's 7.1.1 (not Debian's 7.1.5 or 8.1.3), one demuxer feeding two simple
+ graphs deadlocks when the audio one both delays and pads (`adelay` + `apad`); one graph reading
+ both streams runs on 5.1.1, 6.1.1, 7.0.2, 8.0.1 and 8.1.3. A command
+ compared with 2.10.8's differs by design. Code: `pad.main()`. Test:
+ `test_pad_with_sound_is_one_filter_graph`.
+- **`silence.py` selects the sound with two `ametadata` filters, not `aselect`.** 8.0 and 8.0.1's
+ `aselect` passes every frame. The first `ametadata` tags a frame when the same `between()`
+ expression (as a timeline `enable`, so the same per-frame `t`) is true and the second keeps the
+ tagged frames, which is what `aselect` keeps. `asplit` + an `atrim` per range + `concat` was
+ tried and works, but costs about 81 command bytes per range against 56: at `--max-cuts 400` on
+ an hour-long file that is past Windows' 32767-character command line. `asegment`'s timestamp
+ mode compares pts with a sample count and is right only for a stream that starts at 0. Code:
+ `silence.main()`. Test: `test_silence_removal_cuts_the_sound_with_the_picture`.
+- **On 8.0, 8.0.1 and 8.1.0, a multi-line `graphics.py` label goes through libass under
+ `--text-render auto`**, decided after the template has wrapped its labels (so `main()` runs
+ once more with the route forced). The releases are named, not probed: `--dry-run` may not start
+ ffmpeg, and a git build without a release number is taken to be fixed. `overlay.py` has no
+ libass route and warns in `notes` instead of drawing each line with its own `drawtext`, which
+ would change how a block is aligned. Code: `drawtext_draws_newline_glyph()`. Test:
+ `test_multi_line_text_avoids_drawtext_on_releases_that_draw_the_line_break`.
+
+## Unreleased — doctor's FFmpeg advisory and the Python 3.9 deprecation
+
+- **The FFmpeg CVE advisory is a warning, never a failure, and never says "vulnerable".** `doctor`
+ sees only the upstream number in `ffmpeg -version`, and distributions backport fixes under it
+ (Ubuntu `8.0.1-3ubuntu2`, Debian `+deb13u1`), so the line says the build is older than the first
+ upstream release with the fix and that a distro may have backported it. It names an update command.
+ `ok`, each tool's `usable` and the exit code stay what the capabilities say: an advisory that
+ failed doctor would fail every patched distro build. Code: `_contract.ffmpeg_security()`.
+ Tests: `test_ffmpeg_security_compares_with_the_fix_on_the_version_s_branch`,
+ `test_doctor_advisory_is_a_warning_never_a_failure`.
+- **A version on a branch with no fixed release is compared with the oldest release that has the
+ fix.** security.html lists CVE-2026-8461's fix under 9.0, 8.1.2 and 8.0.3 and under no 7.x or 6.x
+ release. Read literally, "older than the fix on its branch" would leave 6.1 and 7.1 (Ubuntu 24.04,
+ Debian 13) silent. The line for them says no release on their branch is listed with the fix,
+ which is what the page shows; it does not claim the old branch has the bug. A version that is not
+ a release number (`N-12345-g…`, a dated git build) is `unknown` and gets no line.
+- **The table is hand-maintained and offline.** It is the list on ffmpeg.org/security.html on the
+ date in `FFMPEG_ADVISORIES_CHECKED`, and only CVEs that page lists go in. Fetching it at run
+ time would break `execution.network: false`, and a stale table only means a missed warning, not
+ a false one. Test: `test_ffmpeg_advisory_table_is_dated_sourced_and_documented`.
+- **The Python 3.9 deprecation is on stderr only; the FFmpeg advisory is in the document too.**
+ Every deprecation warning has been a stderr line (`--crf` in 1.10), and the machine-readable
+ form is `contract --json`'s `deprecated`. The FFmpeg advisory is about the machine, which is what
+ `doctor --json` describes, so it has a key (`ffmpeg_security.warnings`). The 3.9 floor and CI's
+ 3.9 job stay until 3.0. Tests: `test_python_3_9_is_deprecated_on_every_surface`,
+ `test_doctor_prints_the_python_3_9_warning_on_stderr_only`, `test_installer_warns_once_on_python_3_9`.
diff --git a/references/ci-platform-pitfalls.md b/references/ci-platform-pitfalls.md
index 161ad2a..e7f9dc1 100644
--- a/references/ci-platform-pitfalls.md
+++ b/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
diff --git a/references/scripts.md b/references/scripts.md
index ad57427..d5984d1 100644
--- a/references/scripts.md
+++ b/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
diff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.py
index 759d852..ae4db2b 100644
--- a/scripts/_common/__init__.py
+++ b/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",
diff --git a/scripts/_common/drawtext.py b/scripts/_common/drawtext.py
index c130d42..576f313 100644
--- a/scripts/_common/drawtext.py
+++ b/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
diff --git a/scripts/_common/runner.py b/scripts/_common/runner.py
index bc346b1..131fedd 100644
--- a/scripts/_common/runner.py
+++ b/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 "".
diff --git a/scripts/_common/text.py b/scripts/_common/text.py
index 2501850..bfc00c7 100644
--- a/scripts/_common/text.py
+++ b/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,
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 626d050..cdf62b6 100644
--- a/scripts/_contract.py
+++ b/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
@@ -1512,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,
@@ -1576,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:
diff --git a/scripts/graphics.py b/scripts/graphics.py
index 6cf2c19..a686d00 100755
--- a/scripts/graphics.py
+++ b/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
diff --git a/scripts/overlay.py b/scripts/overlay.py
index c0f0ec3..e217273 100755
--- a/scripts/overlay.py
+++ b/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
diff --git a/scripts/pad.py b/scripts/pad.py
index 5fd2dda..d39074d 100644
--- a/scripts/pad.py
+++ b/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:
diff --git a/scripts/silence.py b/scripts/silence.py
index 8f934d0..3236bc9 100755
--- a/scripts/silence.py
+++ b/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:
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 9a6b7a9..6e251a0 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -1340,7 +1340,9 @@ class ContractTests(unittest.TestCase):
# Release date of each version a deprecation dates from (git tag date). CI checks out without
# tags, so the dates live here, and they stay after the major that removes the entries: they
# are what that major's own PR is checked against.
- DEPRECATION_RELEASE_DATES = {"1.10.0": "2026-09-13"}
+ # None: not released yet. Set it to the tag date when that version ships; a major bump fails
+ # while it is None, because the 90-day window cannot be counted from an unknown date.
+ DEPRECATION_RELEASE_DATES = {"1.10.0": "2026-09-13", "2.11.0": None}
# A major released before step 2's 90 days had passed, by the maintainer's decision. Each one
# must be stated in docs/contract.md (the needle below), so it is a written waiver, not a slip.
WINDOW_WAIVERS = {2: "**2.0.0 waived the 90-day half of step 2.**"}
@@ -1374,6 +1376,7 @@ class ContractTests(unittest.TestCase):
if s_major >= major:
continue # its removal is a later major's; nothing to check until then
with self.subTest(since=since):
+ self.assertIsNotNone(day, f"{since}: set its release date in DEPRECATION_RELEASE_DATES before a major removes it")
later_minors = {(a, b) for a, b, _ in released if a == s_major and b > s_minor}
self.assertGreaterEqual(len(later_minors), 2, f"{since}: fewer than two further minor releases")
if s_major + 1 in self.WINDOW_WAIVERS:
@@ -1690,6 +1693,77 @@ class ContractTests(unittest.TestCase):
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
self.assertEqual(proc.returncode, 0, proc.stderr or proc.stdout)
+ def test_python_3_9_is_deprecated_on_every_surface(self):
+ """2.11.0 deprecates Python 3.9 per docs/contract.md's policy: an entry in `deprecated`
+ (removed in 3.0.0), the floor unchanged (3.9 still runs), and one identical warning line from
+ doctor (Python) and the npx installer (Node)."""
+ entry = [e for e in self.contract["deprecated"] if "Python 3.9" in e["what"]]
+ self.assertEqual(len(entry), 1)
+ self.assertEqual((entry[0]["since"], entry[0]["removed_in"], entry[0]["where"]), ("2.11.0", "3.0.0", "behaviour"))
+ self.assertIn("3.10", entry[0]["replacement"])
+ self.assertTrue(self.contract["requirements"]["python"].startswith(">=3.9 "), "the hard floor stays 3.9 until 3.0")
+ self.assertIn("deprecated", self.contract["requirements"]["python"])
+ self.assertEqual(_contract.python_deprecation((3, 9, 18)), _contract.PY39_DEPRECATION)
+ for vi in ((3, 10, 0), (3, 13, 1), (3, 8, 10)):
+ self.assertIsNone(_contract.python_deprecation(vi), vi)
+ line = _contract.PY39_DEPRECATION
+ self.assertTrue(line.startswith("warning: ") and "\n" not in line)
+ for needle in ("3.0", "3.10+"):
+ self.assertIn(needle, line)
+ js = (ROOT / "bin" / "install.js").read_text(encoding="utf-8")
+ self.assertIn(f"const PY39_DEPRECATION = '{line}';", js, "install.js must print the same line as doctor")
+ ci = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+ self.assertIn('python: ["3.9"]', ci, "deprecating 3.9 does not drop it from CI before 3.0")
+ for doc in ("README.md", "docs/contract.md", "CONTRIBUTING.md", "SKILL.md"):
+ text = (ROOT / doc).read_text(encoding="utf-8")
+ self.assertRegex(text, r"3\.9[^\n]*deprecated|deprecated[^\n]*3\.9", doc)
+
+ def test_doctor_prints_the_python_3_9_warning_on_stderr_only(self):
+ """Deprecation warnings go to stderr (policy step 1), never into stdout: `doctor --json`
+ stays one JSON document, with no key that exists only on 3.9."""
+ import contextlib
+ import io
+ from unittest import mock
+ fake = {"ffmpeg_security": {"warnings": []}, "ok": True, "missing": []}
+ for vi, expect in (((3, 9, 18, "final", 0), True), ((3, 12, 1, "final", 0), False)):
+ out, err = io.StringIO(), io.StringIO()
+ with mock.patch.object(_contract, "doctor", return_value=fake), \
+ mock.patch.object(sys, "argv", ["_contract.py", "doctor", "--json"]), \
+ mock.patch.object(sys, "version_info", vi), \
+ contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+ code = _contract.main()
+ self.assertEqual(code, 0)
+ self.assertEqual(json.loads(out.getvalue()), fake)
+ self.assertEqual(_contract.PY39_DEPRECATION in err.getvalue(), expect, vi)
+
+ def test_installer_warns_once_on_python_3_9(self):
+ """bin/install.js reads major.minor from its interpreter probe and prints the deprecation
+ line after an install on 3.9; nothing on 3.10+, nor when the probe printed no version."""
+ probe = self.out("python_dep_probe.js")
+ probe.write_text(
+ "const inst = require(process.argv[2]);\n"
+ "function stubFor(ver) { return (cmd, args) => (args[0] === '-c' ? { status: 0, error: null, stdout: ver } : { status: 0 }); }\n"
+ "const seen = [];\n"
+ "const warn = (l) => seen.push(l);\n"
+ "if (inst.findPython('linux', stubFor('3.9')).version !== '3.9') process.exit(2);\n"
+ "if (inst.warnDeprecatedPython('linux', stubFor('3.9'), warn) !== inst.PY39_DEPRECATION) process.exit(3);\n"
+ "if (seen.length !== 1 || !seen[0].includes(inst.PY39_DEPRECATION)) process.exit(4);\n"
+ "if (inst.warnDeprecatedPython('linux', stubFor('3.10'), warn) !== null) process.exit(5);\n"
+ "if (inst.warnDeprecatedPython('linux', stubFor(undefined), warn) !== null) process.exit(6);\n"
+ "if (inst.warnDeprecatedPython('linux', () => ({ error: new Error('ENOENT'), status: null }), warn) !== null) process.exit(7);\n"
+ "if (seen.length !== 1) process.exit(8);\n"
+ "const ran = inst.runWithPython(['doctor'], 'linux', stubFor('3.9'));\n"
+ "if (ran.missing || ran.status !== 0) process.exit(9);\n",
+ encoding="utf-8")
+ proc = subprocess.run(["node", str(probe), str(ROOT / "bin" / "install.js")],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ self.assertEqual(proc.returncode, 0, proc.stderr or proc.stdout)
+ # the real probe prints this interpreter's major.minor
+ found = subprocess.run(["node", "-e", "console.log(JSON.stringify(require(process.argv[1]).findPython(process.platform)))",
+ str(ROOT / "bin" / "install.js")], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ if found.returncode == 0 and found.stdout.strip() and "missing" not in found.stdout:
+ self.assertRegex(json.loads(found.stdout)["version"], r"^3\.\d+$")
+
def test_npm_package_omits_the_maintainer_diary(self):
"""docs/design-decisions.md: references/process-pitfalls.md stays out of the npm package.
@@ -2607,6 +2681,67 @@ class ContractTests(unittest.TestCase):
out = subprocess.run([sys.executable, "-c", code], env=env, stdout=subprocess.PIPE, text=True, check=True).stdout
self.assertEqual(out.strip(), "(7, 0)")
+ def _release_shim(self, name, banner):
+ """A PATH holding an ffprobe that answers `-version` with `banner` and hands every other
+ call to the real ffprobe, so a tool plans for that release on any machine."""
+ shim = self.out(name); shim.mkdir(exist_ok=True)
+ (shim / "ffprobe").write_text("#!/bin/sh\nif [ \"$1\" = \"-version\" ]; then printf '%s\\n'; exit 0; fi\n"
+ "exec %s \"$@\"\n" % (banner, shutil.which("ffprobe")))
+ (shim / "ffprobe").chmod(0o755)
+ return dict(os.environ, PATH=f"{shim}{os.pathsep}{os.environ['PATH']}")
+
+ @unittest.skipIf(platform.system() == "Windows", "the fake ffprobe is a #!/bin/sh shim on a POSIX-only PATH")
+ def test_ffmpeg_release_reads_the_point_release(self):
+ """A drawtext bug that 8.0 introduced and 8.0.2 / 8.1.1 fixed cannot be told apart by
+ ffmpeg_version()'s major.minor; ffmpeg_release() reads the patch level too (a distro suffix
+ is ignored, a bare major.minor is .0) and has none for a git build."""
+ code = ("import sys; sys.path.insert(0, %r); import _common; "
+ "print(_common.ffmpeg_release(), _common.drawtext_draws_newline_glyph())" % str(SCRIPTS))
+ for banner, expected in (("ffprobe version 8.0.1-3ubuntu2 Copyright (c) 2007-2025", "(8, 0, 1) True"),
+ ("ffprobe version n8.1 Copyright (c) 2007-2026", "(8, 1, 0) True"),
+ ("ffprobe version 8.0.2 Copyright (c) 2007-2026", "(8, 0, 2) False"),
+ ("ffprobe version 8.1.1 Copyright (c) 2007-2026", "(8, 1, 1) False"),
+ ("ffprobe version 6.1.1-3ubuntu5 Copyright (c) 2007-2023", "(6, 1, 1) False"),
+ ("ffprobe version N-121000-g1234abcd Copyright (c) 2007-2026", "None False")):
+ env = self._release_shim("release_shim", banner)
+ out = subprocess.run([sys.executable, "-c", code], env=env, stdout=subprocess.PIPE, text=True, check=True).stdout
+ self.assertEqual(out.strip(), expected, banner)
+
+ @unittest.skipIf(platform.system() == "Windows", "the fake ffprobe is a #!/bin/sh shim on a POSIX-only PATH")
+ def test_multi_line_text_avoids_drawtext_on_releases_that_draw_the_line_break(self):
+ """FFmpeg 8.0, 8.0.1 (Ubuntu 26.04's apt build) and 8.1.0 shape each line of a multi-line
+ drawtext WITH its newline, so the font's missing-glyph box is drawn at the end of every line
+ but the last (CI on ubuntu-latest: the lower-third's title measured as three yellow bands).
+ graphics.py's auto route sends such a label -- given with a newline or wrapped there --
+ through libass on those releases, keeps drawtext for one line and on fixed releases, and a
+ pinned --text-render drawtext warns; overlay.py, which has no libass route, says so in notes."""
+ bad = self._release_shim("nl_shim_801", "ffprobe version 8.0.1-3ubuntu2 Copyright (c) 2007-2025")
+ good = self._release_shim("nl_shim_802", "ffprobe version 8.0.2 Copyright (c) 2007-2026")
+
+ def gfx(env, *extra):
+ proc = tool("graphics", self.src, "--template", "lower-third", "--name", "Jane", *extra,
+ "--dry-run", "--json", "-o", self.out("nl_gfx.mp4"), env=env)
+ return json.loads(proc.stdout), proc.stderr
+
+ doc, err = gfx(bad, "--title", "CEO\nand founder")
+ self.assertEqual(doc["text_renderer"], "ass", err[-400:])
+ self.assertIn("box at each line break", err)
+ wrapped = json.loads(tool("graphics", self.src, "--template", "meme", "--top", "a caption far too long to fit "
+ "across the frame on a single line", "--dry-run", "--json", "-o", self.out("nl_meme.mp4"),
+ env=bad).stdout)
+ self.assertEqual(wrapped["text_renderer"], "ass", "a label graphics.py wrapped to two lines")
+ self.assertEqual(gfx(bad, "--title", "CEO")[0]["text_renderer"], "drawtext", "one line keeps drawtext")
+ self.assertEqual(gfx(good, "--title", "CEO\nand founder")[0]["text_renderer"], "drawtext", "8.0.2 is fixed")
+ doc, err = gfx(bad, "--title", "CEO\nand founder", "--text-render", "drawtext")
+ self.assertEqual(doc["text_renderer"], "drawtext")
+ self.assertIn("warning: this ffmpeg's drawtext draws a box", err)
+ doc = json.loads(tool("overlay", self.src, "--text", "two\nlines", "--dry-run", "--json",
+ "-o", self.out("nl_ov.mp4"), env=bad).stdout)
+ self.assertTrue(any("missing-glyph box" in n for n in doc.get("notes", [])), doc.get("notes"))
+ doc = json.loads(tool("overlay", self.src, "--text", "two\nlines", "--dry-run", "--json",
+ "-o", self.out("nl_ov.mp4"), env=good).stdout)
+ self.assertNotIn("notes", doc)
+
def test_fourth_review_p3_regressions(self):
"""Fourth review P3 items: render re-encoded a clip at speed 1.0 (#47); a brand's default
caption.animate made --mode mux fail (#32); shell_quote left a newline bare (#54);
@@ -3312,6 +3447,86 @@ class ContractTests(unittest.TestCase):
self.assertEqual(before, after, f"{p.name} modified")
+class FfmpegSecurityTableTests(unittest.TestCase):
+ """doctor's `ffmpeg_security` table and comparison, without running ffmpeg (every OS)."""
+
+ def test_ffmpeg_security_compares_with_the_fix_on_the_version_s_branch(self):
+ """doctor's FFmpeg advisory: a version older than the first upstream release on its branch
+ that fixes a listed CVE gets a warning; a fixed or newer one, an unparseable one and no
+ binary get none. The wording never claims the build is vulnerable (distros backport)."""
+ cases = {
+ "8.0.1-3ubuntu2": ("older_than_fix", "8.0.3", True),
+ "8.0.2": ("older_than_fix", "8.0.3", True),
+ "8.0.3": ("not_older", None, None),
+ "8.1": ("older_than_fix", "8.1.2", True),
+ "n8.1.1": ("older_than_fix", "8.1.2", True),
+ "8.1.2-full_build-www.gyan.dev": ("not_older", None, None),
+ "9.0": ("not_older", None, None),
+ "9.0.1-essentials_build-www.gyan.dev": ("not_older", None, None),
+ "10.0": ("not_older", None, None),
+ "7.1.2-0+deb13u1": ("older_than_fix", "8.0.3", False),
+ "6.1.1-3ubuntu5": ("older_than_fix", "8.0.3", False),
+ "N-121234-g0123abcd": ("unknown", None, None),
+ "2026-10-01-git-0123abcd-full_build-www.gyan.dev": ("unknown", None, None),
+ "unknown": ("unknown", None, None),
+ None: ("unknown", None, None),
+ }
+ for version, (status, first_fix, on_branch) in cases.items():
+ with self.subTest(version=version):
+ sec = _contract.ffmpeg_security({"ffmpeg": version, "ffprobe": None})
+ self.assertEqual(sec["ffmpeg"]["status"], status)
+ self.assertEqual(sec["ffprobe"]["status"], "unknown")
+ if first_fix is None:
+ self.assertEqual(sec["ffmpeg"]["advisories"], [])
+ self.assertEqual(sec["warnings"], [])
+ continue
+ adv = sec["ffmpeg"]["advisories"][0]
+ self.assertEqual((adv["cve"], adv["first_fix"], adv["fix_on_branch"]), ("CVE-2026-8461", first_fix, on_branch))
+ self.assertEqual(len(sec["warnings"]), 1)
+ line = sec["warnings"][0]
+ self.assertTrue(line.startswith(f"warning: ffmpeg {version} is older than"), line)
+ self.assertNotIn("\n", line)
+ self.assertIn("CVE-2026-8461", line)
+ self.assertIn(first_fix, line)
+ self.assertIn("backported", line)
+ self.assertIn("not proof the build is vulnerable", line)
+ self.assertIn(_contract.FFMPEG_ADVISORIES_CHECKED, line)
+ if "ubuntu" in version or "+deb" in version:
+ self.assertIn("sudo apt", line)
+ # the same version on both binaries warns once; a different ffprobe gets its own line
+ same = _contract.ffmpeg_security({"ffmpeg": "8.0.1", "ffprobe": "8.0.1"})
+ self.assertEqual(len(same["warnings"]), 1)
+ self.assertEqual(same["ffprobe"]["status"], "older_than_fix")
+ mixed = _contract.ffmpeg_security({"ffmpeg": "9.0", "ffprobe": "8.1.1"})
+ self.assertEqual(len(mixed["warnings"]), 1)
+ self.assertTrue(mixed["warnings"][0].startswith("warning: ffprobe 8.1.1"))
+
+ def test_ffmpeg_advisory_table_is_dated_sourced_and_documented(self):
+ """The table is hand-maintained: it names its source and the day it was checked, every
+ fixing release parses, and docs/contract.md states the same date and field."""
+ import datetime
+ datetime.date.fromisoformat(_contract.FFMPEG_ADVISORIES_CHECKED)
+ self.assertEqual(_contract.FFMPEG_ADVISORY_SOURCE, "https://ffmpeg.org/security.html")
+ self.assertTrue(_contract.FFMPEG_ADVISORIES)
+ for adv in _contract.FFMPEG_ADVISORIES:
+ self.assertRegex(adv["cve"], r"^CVE-\d{4}-\d+$")
+ self.assertGreaterEqual(adv["cvss"], 7.0, "the table lists high-severity CVEs only")
+ for branch, fix in adv["fixed_in"].items():
+ v = _contract._parse_ffmpeg_version(fix)
+ self.assertIsNotNone(v, fix)
+ self.assertEqual(f"{v[0]}.{v[1]}", branch)
+ contract_md = (ROOT / "docs" / "contract.md").read_text(encoding="utf-8")
+ self.assertIn("`ffmpeg_security`", contract_md)
+ self.assertIn(_contract.FFMPEG_ADVISORIES_CHECKED, contract_md)
+ for adv in _contract.FFMPEG_ADVISORIES:
+ self.assertIn(adv["cve"], contract_md)
+ self.assertIn("ffmpeg_security", (ROOT / "README.md").read_text(encoding="utf-8"))
+ # offline: the advisory is a table lookup, the module opens no connection
+ src = (SCRIPTS / "_contract.py").read_text(encoding="utf-8")
+ for mod in ("urllib", "http.client", "socket", "requests"):
+ self.assertNotRegex(src, rf"(?m)^\s*(import|from) {re.escape(mod)}\b", mod)
+
+
@unittest.skipIf(platform.system() == "Windows", "every test here drives a fake ffmpeg via a #!/bin/sh POSIX shell shim on PATH to force specific fixture layouts; not portable to Windows. doctor's own detection logic still runs against the REAL ffmpeg on Windows CI through ContractTests' setUpClass and test_doctor_reports_this_installed_copys_own_version -- what's untested on Windows specifically is the fixture-driven FFmpeg 6/7/8/9 layout-parsing behaviour this class exists to pin. See README, 'Development'.")
class DoctorDetectionTests(unittest.TestCase):
"""Capability detection reads every `ffmpeg -filters` layout and never confuses "unreadable" with "absent".
@@ -3527,6 +3742,37 @@ class DoctorDetectionTests(unittest.TestCase):
# a tool needing only ffprobe/ffmpeg binaries (not a specific filter) is unaffected by the filter listing
self.assertEqual(d2["tools"]["probe"]["usable"], "yes")
+ def test_doctor_advisory_is_a_warning_never_a_failure(self):
+ """End to end with a fake `ffmpeg -version`: the advisory is in the JSON and on stderr, and
+ `ok`, the tools' `usable` and the exit code are what the same build reports without it."""
+ results = {}
+ for version in ("8.0.1-3ubuntu2", "8.1.2"):
+ shim = self.work / f"shim_{version}"
+ shim.mkdir()
+ script = "#!/bin/sh\ncase \"$2\" in\n"
+ for flag, name in (("-filters", "ffmpeg_filters_6.1.txt"), ("-encoders", "ffmpeg_encoders_6.1.txt"), ("-bsfs", "ffmpeg_bsfs_6.1.txt")):
+ script += f" {flag}) cat '{self.FIX / name}'; exit 0;;\n"
+ script += f"esac\ncase \"$1\" in -version) echo 'ffmpeg version {version} Copyright (c) 2000-2026'; exit 0;; esac\nexit 1\n"
+ (shim / "ffmpeg").write_text(script)
+ (shim / "ffmpeg").chmod(0o755)
+ env = dict(os.environ, PATH=f"{shim}:{os.environ['PATH']}")
+ proc = sh(sys.executable, SCRIPTS / "_contract.py", "doctor", "--json", env=env, check=False)
+ plain = sh(sys.executable, SCRIPTS / "_contract.py", "doctor", env=env, check=False)
+ results[version] = (json.loads(proc.stdout), proc.returncode, proc.stderr, plain)
+ old, old_code, old_err, old_plain = results["8.0.1-3ubuntu2"]
+ new, new_code, new_err, new_plain = results["8.1.2"]
+ self.assertEqual(old["ffmpeg"], "8.0.1-3ubuntu2")
+ self.assertEqual(old["ffmpeg_security"]["ffmpeg"]["status"], "older_than_fix")
+ self.assertEqual(new["ffmpeg_security"]["ffmpeg"]["status"], "not_older")
+ line = next(w for w in old["ffmpeg_security"]["warnings"] if w.startswith("warning: ffmpeg 8.0.1-3ubuntu2"))
+ self.assertIn(line, old_err)
+ self.assertIn(line, old_plain.stderr)
+ self.assertNotIn(line, old_plain.stdout)
+ self.assertFalse(any(w.startswith("warning: ffmpeg ") for w in new["ffmpeg_security"]["warnings"]))
+ self.assertNotIn("warning: ffmpeg 8.1.2", new_err)
+ self.assertEqual((old["ok"], old_code, old_plain.returncode), (new["ok"], new_code, new_plain.returncode))
+ self.assertEqual(old["tools"], new["tools"])
+
def test_doctor_json_keeps_its_keys(self):
"""Consumers of 0.9.0 read available / missing / missing_optional / ok; those keys and types stay."""
d, _ = self._doctor("ffmpeg_filters_8.0_constructed.txt")
diff --git a/tests/test_editing.py b/tests/test_editing.py
index 572cfe0..9dad8f4 100644
--- a/tests/test_editing.py
+++ b/tests/test_editing.py
@@ -617,6 +617,32 @@ class EditingTests(MediaFixtures):
m = probe(str(out))
self.assertClose(m["duration"], 15.0, 0.3)
+ def test_pad_with_sound_is_one_filter_graph(self):
+ """FFmpeg 8.0.1's scheduler (and conda-forge's 7.1.1) deadlocks (no CPU, until --timeout) when one demuxer feeds
+ a -vf graph and an -af graph whose audio both delays its start and pads its tail: pad.py
+ hung for 1800 s on Ubuntu 26.04's 8.0.1 (and on conda-forge's 7.1.1 before it). Both
+ streams now go through one -filter_complex, which runs on every release. That graph gets
+ no even scale from run()'s retry, so pad.py adds it for an odd-sized source itself."""
+ doc = json.loads(script("pad.py", self.src, "--start", "1", "--end", "2", "--dry-run", "--json",
+ "-o", OUT / "pad_plan.mp4").stdout)
+ cmd = doc["commands"][-1]
+ self.assertIn("-filter_complex", cmd)
+ self.assertNotIn(" -af ", cmd)
+ self.assertNotIn(" -vf ", cmd)
+ odd = OUT / "pad_odd_in.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=641x359:rate=30",
+ "-f", "lavfi", "-i", "sine=f=440:r=48000", "-t", "2", "-pix_fmt", "yuv444p", "-c:v", "libx264",
+ "-preset", "veryfast", "-c:a", "aac", odd)
+ out = OUT / "pad_odd.mp4"
+ script("pad.py", odd, "--start", "1", "--end", "1", "--color", "0x2878C8", "--preset", "veryfast", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"] % 2, m["video"]["height"] % 2), (0, 0))
+ self.assertClose(m["duration"], 4.0, 0.15)
+ streams = json.loads(sh("ffprobe", "-v", "error", "-show_entries", "stream=codec_type,duration",
+ "-of", "json", out).stdout)["streams"]
+ lengths = {s["codec_type"]: float(s["duration"]) for s in streams}
+ self.assertClose(lengths["audio"], lengths["video"], 0.1)
+
def test_pad_nothing_refused(self):
script("pad.py", self.src, expect_fail=True)
@@ -1014,6 +1040,28 @@ class EditingTests(MediaFixtures):
script("cut.py", gappy, "--segments", segs, "--accurate", "--preset", "veryfast", "-o", out2)
self.assertClose(probe(str(out2))["duration"], 6.75, 0.4)
+ def test_silence_removal_cuts_the_sound_with_the_picture(self):
+ """FFmpeg 8.0 and 8.0.1 (Ubuntu 26.04) 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), so silence.py
+ cut the picture to 6.75 s and left the sound at 12 s. The container duration is the longer
+ stream, so each stream is measured here. The sound is selected through ametadata (tag the
+ frames the expression keeps, keep the tagged ones), which behaves the same on every release,
+ and is never planned through aselect again."""
+ gappy = OUT / "gappy_streams.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "aevalsrc='0.5*sin(2*PI*440*t)*gt(sin(2*PI*0.25*t)\\,0)':s=48000",
+ "-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30", "-t", "12", "-c:v", "libx264", "-preset", "veryfast",
+ "-c:a", "aac", gappy)
+ plan = json.loads(script("silence.py", gappy, "--dry-run", "--json", "-o", OUT / "tight_plan.mp4").stdout)
+ self.assertNotIn("aselect", plan["commands"][-1])
+ for name in ("tight_streams.mp4", "tight_streams.m4a"):
+ out = OUT / name
+ script("silence.py", gappy, "--preset", "veryfast", "-o", out)
+ streams = json.loads(sh("ffprobe", "-v", "error", "-show_entries", "stream=codec_type,duration",
+ "-of", "json", out).stdout)["streams"]
+ for s in streams:
+ self.assertClose(float(s["duration"]), 6.75, 0.1, f"{name} {s['codec_type']}")
+
def test_silence_on_wav_input_keeps_pcm_not_forced_aac(self):
"""silence.py's final ffmpeg command used to unconditionally append aac_args() (-c:a aac)
regardless of the output container. That's fine for .mp4/.m4a, but AAC cannot be muxed