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.

Deprecate FFmpeg 5.x: doctor and the installer warn; 3.0 requires 6.1 (#354)

Shogo Kajiyama7accea696aac
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5b53cb1..f1f01e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@
## Unreleased
-(nothing yet)
+### Deprecated
+
+- **Running on FFmpeg 5.x.** It still works in 2.x: `requirements.ffmpeg` stays `>=5.0` and CI keeps its 5.1.1 job. 3.0.0 requires FFmpeg 6.1. On a 5.x build, `doctor` and the `npx` installer print one stderr warning, and `contract --json`'s `deprecated` lists it.
## 2.13.0
diff --git a/README.md b/README.md
index 5b552d6..59d0990 100644
--- a/README.md
+++ b/README.md
@@ -420,7 +420,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); Python 3.10+ is recommended: 3.9 still works but is deprecated since 2.10.9 (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:
+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). FFmpeg 6.1+ is recommended: FFmpeg 5.x still works but is deprecated since 2.14.0, `doctor` and the `npx` installer warn on it, and 3.0 requires 6.1. Python 3.10+ is recommended too: 3.9 still works but is deprecated since 2.10.9 (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 |
|---|---|---|
@@ -527,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.
+- FFmpeg 5.0+ (FFmpeg 5.x is deprecated since 2.14.0 and 3.0 requires 6.1; 6.1+ recommended). 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.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
diff --git a/bin/install.js b/bin/install.js
index 394a786..451bbbb 100755
--- a/bin/install.js
+++ b/bin/install.js
@@ -55,6 +55,16 @@ function pythonDeprecation(version) {
return version === '3.9' ? PY39_DEPRECATION : null;
}
+// 2.14.0 deprecates FFmpeg 5.x the same way. The same line as scripts/_contract.py's
+// FFMPEG5_DEPRECATION (a test keeps them equal).
+const FFMPEG5_DEPRECATION = 'warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (the 5.x branches date from 2022; Ubuntu 24.04 ships 6.1); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.';
+
+// The line for `ffmpeg -version`'s first line, or null (not 5.x, or not a release number).
+function ffmpegDeprecation(versionLine) {
+ const m = /^ffmpeg version n?(\d+)\.\d+/.exec(versionLine || '');
+ return m && m[1] === '5' ? FFMPEG5_DEPRECATION : null;
+}
+
function pythonCandidates(platform) {
return platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
}
@@ -146,7 +156,10 @@ function checkFfmpeg() {
console.warn(' Windows: winget install Gyan.FFmpeg\n');
return false;
}
- console.log(` found ${r.stdout.split('\n')[0]}`);
+ const first = r.stdout.split('\n')[0];
+ console.log(` found ${first}`);
+ const line = ffmpegDeprecation(first);
+ if (line) console.warn(`\n ${line}`);
return true;
}
@@ -211,4 +224,4 @@ if (require.main === module) {
main();
}
-module.exports = { pythonCandidates, runWithPython, findPython, pythonDeprecation, warnDeprecatedPython, PY39_DEPRECATION };
+module.exports = { pythonCandidates, runWithPython, findPython, pythonDeprecation, warnDeprecatedPython, PY39_DEPRECATION, ffmpegDeprecation, FFMPEG5_DEPRECATION };
diff --git a/docs/contract.md b/docs/contract.md
index f46cfbd..9324d36 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -88,6 +88,11 @@ in October 2025 and gets no security fixes, but raising the floor is a break, so
recommended: on 3.9, `doctor` and the `npx` installer print one stderr line,
`warning: Python 3.9 is deprecated since ffmpeg-skill 2.10.9 (...); 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.
+Since 2.14.0 there is a second entry, **running on FFmpeg 5.x** (`where: behaviour`, `removed_in: 3.0.0`),
+handled the same way: `requirements.ffmpeg` stays `>=5.0` and CI keeps its 5.1.1 job until 3.0, which
+requires 6.1. When `ffmpeg -version` reads 5.x, `doctor` and the `npx` installer print one stderr line,
+`warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (...); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.`
+A version that is not a release number (a git snapshot) gets no line.
`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.
@@ -123,12 +128,13 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
```json
{
"contract_version": "1.0",
- "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
+ "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"},
+ {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 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.13.0", "execution_mode": "local", "kind": "execution",
"entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
- "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
+ "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},
"execution": {"shell": false, "arbitrary_executables": false, "network": false,
"model_downloads": {"when": "...", "in_process": {"faster-whisper": "..."},
"child_process": {"parakeet-mlx": "...", "openai-whisper": "..."},
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 93244fa..dbc8468 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -43,6 +43,7 @@ exists. When a decision changes, edit the entry in the same PR.
- [2.10.9 — FFmpeg 8.0.1 (Ubuntu 26.04)](#2109--ffmpeg-801-ubuntu-2604)
- [2.10.9 — doctor's FFmpeg advisory and the Python 3.9 deprecation](#2109--doctors-ffmpeg-advisory-and-the-python-39-deprecation)
- [2.11.0–2.12.0 — nothing happens silently](#21102120--nothing-happens-silently)
+- [2.14.0 — the FFmpeg 5.x deprecation](#2140--the-ffmpeg-5x-deprecation)
<!-- contents:end -->
## Time limits
@@ -2055,3 +2056,14 @@ What was decided there:
pins that): JSON-RPC answers an invalid request with `-32600`, but a scalar on stdin is no request
this server can name, and replying to one was not asked for. Code: `mcp/server.py` `main()`. Test:
`test_mcp_server_error_paths_raw_argv_and_call_helper`.
+
+## 2.14.0 — the FFmpeg 5.x deprecation
+
+- **FFmpeg 5.x is deprecated, not dropped.** The 5.x branches date from 2022. Debian 12 still
+ ships 5.1, so raising `requirements.ffmpeg` is a break and waits for 3.0, which requires 6.1
+ (Ubuntu 24.04's). Until then 5.0 keeps working, CI keeps its 5.1.1 job, and the version-specific
+ workarounds stay. It follows the Python 3.9 route above: an entry in `contract --json`'s
+ `deprecated`, and one stderr line from `doctor` and the `npx` installer when `ffmpeg -version`
+ reads 5.x, never a key in `doctor --json` and never a failure. A git snapshot's version is not a
+ release number and gets no line, the same rule as the security advisory. Tests:
+ `test_ffmpeg_5_is_deprecated_on_every_surface`, `test_doctor_prints_the_ffmpeg_5_warning_on_stderr_only`.
diff --git a/scripts/_contract.py b/scripts/_contract.py
index c262442..77b5edf 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -987,6 +987,20 @@ def python_deprecation(version_info: Optional[tuple] = None) -> Optional[str]:
return PY39_DEPRECATION if vi == (3, 9) else None
+# 2.14.0 deprecates FFmpeg 5.x the same way (DEPRECATED below): 2.x keeps running on it and CI keeps
+# its 5.1.1 job, and the line names 3.0.0 as the release that raises the floor to 6.1. bin/install.js
+# prints it too (FFMPEG5_DEPRECATION there; a test keeps the two equal).
+FFMPEG5_DEPRECATION = ("warning: FFmpeg 5.x is deprecated since ffmpeg-skill 2.14.0 (the 5.x branches date from 2022; "
+ "Ubuntu 24.04 ships 6.1); it still works in 2.x and support ends in 3.0.0: use FFmpeg 6.1+.")
+
+
+def ffmpeg_deprecation(version: Optional[str]) -> Optional[str]:
+ """The deprecation line for this ffmpeg's version token, or None (not 5.x, or not a release
+ number: a git snapshot gets no line, as with the security advisory)."""
+ v = _parse_ffmpeg_version(version)
+ return FFMPEG5_DEPRECATION if v and v[0] == 5 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
@@ -1549,6 +1563,12 @@ DEPRECATED: List[Dict[str, str]] = [
{"what": "running on Python 3.9 (the requirements.python floor)",
"since": "2.10.9", "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"},
+ # FFmpeg 5.x: the 5.x branches date from 2022 and keep version-specific workarounds alive.
+ # 2.x keeps running on 5.0+ (CI still tests 5.1.1) and doctor / bin/install.js print
+ # FFMPEG5_DEPRECATION; 3.0.0 raises requirements.ffmpeg to 6.1.
+ {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)",
+ "since": "2.14.0", "removed_in": "3.0.0", "where": "behaviour",
+ "replacement": "FFmpeg 6.1 or later; on 5.x, 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
@@ -1787,7 +1807,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; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
+ "requirements": {"python": ">=3.9 (standard library only; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0", "node": ">=16 (npx installer only)"},
"execution": {
"shell": False,
"arbitrary_executables": False,
@@ -1872,8 +1892,9 @@ def main() -> int:
# 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"]:
+ # "Deprecation policy" step 1), and machine-readable in `contract --json`'s `deprecated`;
+ # so is the FFmpeg 5.x one.
+ for line in [python_deprecation(), ffmpeg_deprecation(d.get("ffmpeg"))] + d["ffmpeg_security"]["warnings"]:
if line:
print(line, file=sys.stderr)
if args.json:
diff --git a/tests/test_contract.py b/tests/test_contract.py
index e9aea2f..994615c 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -1350,7 +1350,7 @@ class ContractTests(unittest.TestCase):
# are what that major's own PR is checked against.
# 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.10.9": "2026-10-22"}
+ DEPRECATION_RELEASE_DATES = {"1.10.0": "2026-09-13", "2.10.9": "2026-10-22", "2.14.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.**"}
@@ -1752,6 +1752,58 @@ class ContractTests(unittest.TestCase):
text = (ROOT / doc).read_text(encoding="utf-8")
self.assertRegex(text, r"3\.9[^\n]*deprecated|deprecated[^\n]*3\.9", doc)
+ def test_ffmpeg_5_is_deprecated_on_every_surface(self):
+ """2.14.0 deprecates FFmpeg 5.x like Python 3.9: an entry in `deprecated` (removed in
+ 3.0.0), the floor unchanged (5.0 still runs, CI keeps its 5.1.1 job), and one identical
+ warning line from doctor (Python) and the npx installer (Node), only for a 5.x release."""
+ entry = [e for e in self.contract["deprecated"] if "FFmpeg 5.x" in e["what"]]
+ self.assertEqual(len(entry), 1)
+ self.assertEqual((entry[0]["since"], entry[0]["removed_in"], entry[0]["where"]), ("2.14.0", "3.0.0", "behaviour"))
+ self.assertIn("6.1", entry[0]["replacement"])
+ self.assertTrue(self.contract["requirements"]["ffmpeg"].startswith(">=5.0 "), "the hard floor stays 5.0 until 3.0")
+ self.assertIn("deprecated", self.contract["requirements"]["ffmpeg"])
+ line = _contract.FFMPEG5_DEPRECATION
+ self.assertTrue(line.startswith("warning: ") and "\n" not in line)
+ for needle in ("2.14.0", "3.0.0", "6.1+"):
+ self.assertIn(needle, line)
+ for version in ("5.1.1-static", "5.0", "n5.1.6", "5.1.6-0+deb12u1"):
+ self.assertEqual(_contract.ffmpeg_deprecation(version), line, version)
+ for version in ("6.1.1-3ubuntu5", "8.0.1", "4.4.2", "N-12345-gabcdef", "unknown", None):
+ self.assertIsNone(_contract.ffmpeg_deprecation(version), version)
+ js = (ROOT / "bin" / "install.js").read_text(encoding="utf-8")
+ self.assertIn(f"const FFMPEG5_DEPRECATION = '{line}';", js, "install.js must print the same line as doctor")
+ probe = self.out("ffmpeg_dep_probe.js")
+ probe.write_text(
+ "const inst = require(process.argv[2]);\n"
+ "const cases = [['ffmpeg version 5.1.1-static https://johnvansickle.com/ffmpeg/ Copyright', true],\n"
+ " ['ffmpeg version n5.0 Copyright (c) 2000-2022', true], ['ffmpeg version 6.1.1-3ubuntu5 Copyright', false],\n"
+ " ['ffmpeg version N-12345-gabcdef Copyright', false], ['', false], [undefined, false]];\n"
+ "for (const [l, want] of cases) if ((inst.ffmpegDeprecation(l) === inst.FFMPEG5_DEPRECATION) !== want) process.exit(2);\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)
+ ci = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+ self.assertIn("ffmpeg-5.1.1", ci, "deprecating 5.x does not drop its CI job before 3.0")
+ for doc in ("README.md", "docs/contract.md"):
+ text = (ROOT / doc).read_text(encoding="utf-8")
+ self.assertRegex(text, r"FFmpeg 5\.x[^\n]*deprecated", doc)
+
+ def test_doctor_prints_the_ffmpeg_5_warning_on_stderr_only(self):
+ import contextlib
+ import io
+ from unittest import mock
+ for version, expect in (("5.1.1-static", True), ("6.1.1-3ubuntu5", False), (None, False)):
+ fake = {"ffmpeg_security": {"warnings": []}, "ok": True, "missing": [], "ffmpeg": version}
+ out, err = io.StringIO(), io.StringIO()
+ with mock.patch.object(_contract, "doctor", return_value=fake), \
+ mock.patch.object(sys, "argv", ["_contract.py", "doctor", "--json"]), \
+ 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.FFMPEG5_DEPRECATION in err.getvalue(), expect, version)
+
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."""