ffmpeg-skill 2.13.0 → 2.14.0

package/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
 

package/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 };

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.13.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.14.0`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -88,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",
+  "skill": {"id": "ffmpeg-skill", "version": "2.14.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": "..."},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/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: