ffmpeg-skill 1.7.2 → 1.8.0

package/README.md

@@ -441,6 +441,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
 | | |
 |---|---|
 | [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |
+| [docs/roadmap.md](docs/roadmap.md) | 1.8.0 to 1.20.0 one theme per minor (1.8 to 1.10 pre-ship 2.0), and what 2.0.0 then removes |
 | [docs/design-decisions.md](docs/design-decisions.md) | behaviours that look like bugs but are decisions, with rationale and the pinning test; read before filing a bug |
 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Contributor Covenant 2.1; reports go through the SECURITY.md channel |
 | [SECURITY.md](SECURITY.md) | how to report a vulnerability privately |

package/SKILL.md

@@ -5,7 +5,7 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0) and `--plan FILE` (a dry run written as a plan: fingerprinted inputs, commands, expected output, verify steps; `render.py FILE` executes it later and refuses if an input changed, so "plan → user confirms → execute" is one round trip). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0) and `--plan FILE` (a dry run written as a plan: fingerprinted inputs, commands, expected output, verify steps; `render.py FILE` executes it later and refuses if an input changed, so "plan → user confirms → execute" is one round trip). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact (nor side files such as `--edl`, `--sheet` or a generated `.ass`); `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Every tool that re-encodes also takes `--codec h264|hevc|av1|prores` and `--quality N` (CRF scale; overrides `--crf`): without them SDR is x264 and HDR is x265 Main10, as before; `--codec prores` needs a `.mov` output, `--codec h264` refuses an HDR source (run `color.py --to-sdr` first). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
 
 ## Workflow (always follow this order)
 

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.7.2`) | any release |
+| `skill.version` | the npm / package.json version (`1.8.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`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.7.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.8.0", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -162,6 +162,16 @@ tool's job; only the artifact is skipped, including side files such as `--edl`,
 generated `.ass`), and `verify` does not support dry-run (its steps run). `SKILL.md` and
 `references/scripts.md` repeat the same list; the contract is the authority.
 
+`--codec h264|hevc|av1|prores` and `--quality N` (1.8) are on every tool whose schema has
+`crf` (the ones that re-encode), marked `common`. They are resolved in one place
+(`_common.encoder_args()`): hevc keeps an HDR source Main10 with its tags and writes 8-bit
+BT.709 for SDR; av1 is SVT-AV1 with libaom as the fallback; prores is 422 HQ and needs a
+`.mov`/`.mkv` output; h264 refuses an HDR source (`kind: input`). `--quality` is the CRF scale
+and overrides `--crf`. Without `--codec` the encoder is what it always was (x264 for SDR, x265
+Main10 for HDR), so the flags add no behaviour to a caller that does not pass them. The
+encoder each value needs is listed under the tool's optional capabilities (`--codec hevc` and
+so on). `export.py` refuses `--codec`: its presets decide the codec.
+
 `--plan FILE` (1.6) is a dry run that also writes a plan document: `{"plan_version": 1,
 "tool", "argv", "cwd", "inputs": [{"path", "size", "sha256_head_tail"}], "commands",
 "output", "verify": [{"tool": "probe"}, {"tool": "check", "platform"}], "notes"}`. It

package/package.json

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

package/references/scripts.md

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py), `-o OUT`; every tool that re-encodes (the ones with `--crf`) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, overrides `--crf`; up to 63 for av1; ignored by prores). `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs a `.mov`/`.mkv` output, `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and refuses `--codec` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Contents
 - probe.py — inspect

package/scripts/_common.py

@@ -218,6 +218,10 @@ def require_tool(name: str) -> str:
 
 
 X264_PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo")
+CODECS = ("h264", "hevc", "av1", "prores")
+# x264 preset names mapped onto SVT-AV1's 0-13 speed scale (lower = slower / better)
+SVT_PRESET = {"ultrafast": 12, "superfast": 11, "veryfast": 10, "faster": 9, "fast": 8, "medium": 6, "slow": 4, "slower": 3, "veryslow": 2, "placebo": 1}
+_ENCODERS: Optional[set] = None
 
 
 class Context:
@@ -228,7 +232,7 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs")
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec")
 
     def __init__(self) -> None:
         self.reset()
@@ -247,6 +251,7 @@ class Context:
         self.plan: Optional[str] = None              # --plan FILE: write the dry-run as a plan document (implies --dry-run)
         self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
         self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
+        self.codec: Optional[str] = None             # --codec: encoder for the re-encode (None = x264 for SDR, x265 for HDR)
 
 
 
@@ -267,6 +272,13 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
                    help="allow replacing an existing output (warned today, refused from 2.0)")
     g.add_argument("--plan", metavar="FILE",
                    help="write the dry run as a plan (inputs fingerprinted, commands, expected output, verify steps) that render.py FILE executes later; implies --dry-run")
+    if "--crf" in ap._option_string_actions:
+        # only the tools that re-encode (they declare --crf before add_common): one encoder choice
+        # resolved in video_args(), the 2.0 encoder abstraction pre-shipped in 1.8 (docs/roadmap.md)
+        g.add_argument("--codec", choices=CODECS, default=None,
+                       help="video encoder for the re-encode: h264 (x264, the default for SDR), hevc (x265, the default for HDR), av1 (SVT-AV1 or libaom), prores (422 HQ, needs a .mov/.mkv output); HDR sources keep their colour on hevc/av1/prores")
+        g.add_argument("--quality", type=int, default=None, metavar="N",
+                       help="encoder quality on the CRF scale (lower = better; 18 visually lossless for x264/x265, up to 63 for av1); overrides --crf, ignored by prores")
 
 
 def apply_common(args: "argparse.Namespace") -> None:
@@ -285,8 +297,20 @@ def apply_common(args: "argparse.Namespace") -> None:
         STATE.timeout = max(0.0, float(args.timeout))
     if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
+    STATE.codec = getattr(args, "codec", None) or None
+    quality = getattr(args, "quality", None)
+    if quality is not None:
+        top = 63 if STATE.codec == "av1" else 51
+        if not 0 <= int(quality) <= top:
+            die(f"--quality must be between 0 and {top} for {STATE.codec or 'h264'} (CRF scale; 18 is visually lossless), got {quality}")
+        args.crf = int(quality)  # every tool reads args.crf; --quality is the codec-neutral spelling of it
+    if STATE.codec == "prores":
+        out = getattr(args, "output", None)
+        if out and os.path.splitext(str(out))[1].lower() not in (".mov", ".mkv"):
+            die(f"--codec prores needs a .mov (or .mkv) output; {os.path.basename(str(out))} cannot hold ProRes",
+                hint="give -o NAME.mov")
     crf = getattr(args, "crf", None)
-    if crf is not None and not 0 <= int(crf) <= 51:
+    if crf is not None and not 0 <= int(crf) <= (63 if STATE.codec == "av1" else 51):
         die(f"--crf must be between 0 and 51 (x264/x265 scale; 18 is visually lossless, 23 the encoder default), got {crf}")
     install_signal_handlers()
 
@@ -1619,13 +1643,100 @@ def bt709_tag_args(encoder: str = "libx264") -> List[str]:
     return ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
 
 
-def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
+def ffmpeg_encoders() -> set:
+    """Names from `ffmpeg -encoders`, read once; empty when ffmpeg is missing. Used only to pick
+    an AV1 encoder and to refuse --codec av1 / prores before ffmpeg would."""
+    global _ENCODERS
+    if _ENCODERS is None:
+        _ENCODERS = set()
+        try:
+            out = subprocess.run([shutil.which("ffmpeg") or "ffmpeg", "-hide_banner", "-encoders"], stdout=subprocess.PIPE,
+                                 stderr=subprocess.DEVNULL, text=True, timeout=PROBE_TIMEOUT).stdout
+            _ENCODERS = set(re.findall(r"^\s*[VAS][.\w]{5}\s+(\S+)", out, re.M))
+        except (OSError, subprocess.SubprocessError):
+            pass
+    return _ENCODERS
+
+
+def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
+    """BT.709 SDR tags for `encoder` as (encoder-params string, extra output options): the two
+    spellings bt709_tag_args() picks between, split so a caller that already builds an encoder
+    params string can merge them (the option given twice keeps only the last)."""
+    if ffmpeg_version() < (7, 1):
+        return "", ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+    if encoder == "libsvtav1":
+        return "color-primaries=1:transfer-characteristics=1:matrix-coefficients=1", []
+    if encoder == "libaom-av1":
+        return "", []  # no VUI params option; an untagged 8-bit stream reads as BT.709 everywhere
+    return "colorprim=bt709:transfer=bt709:colormatrix=bt709", []
+
+
+def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None) -> List[str]:
+    """The one place that turns (--codec, --quality, --preset, source) into encoder options.
+
+    h264 -> x264 8-bit BT.709 (refuses HDR: 8-bit H.264 cannot carry it); hevc -> x265, Main10
+    with the source's tags for HDR, 8-bit BT.709 otherwise; av1 -> SVT-AV1 (libaom fallback),
+    10-bit for HDR; prores -> ProRes 422 HQ, source tags kept. 1.8: chosen by --codec; without
+    it video_args() does what it always did (x264 for SDR, x265 Main10 for HDR).
+    """
+    v = (meta or {}).get("video") or {}
+    hdr = bool(v.get("hdr"))
+    cs = v.get("color_space") or "bt2020nc"
+    prim = v.get("color_primaries") or "bt2020"
+    trc = v.get("color_transfer") or "arib-std-b67"
+    hdr_tags = ["-colorspace", cs, "-color_primaries", prim, "-color_trc", trc]
+    if codec == "h264":
+        if hdr:
+            die(f"--codec h264 cannot carry HDR ({v.get('hdr_format') or 'BT.2020'}): 8-bit H.264 is SDR only",
+                hint="run color.py --to-sdr first, or use --codec hevc / av1 / prores, which keep the source's HDR")
+        return _x264_raw(crf, preset)
+    if codec == "hevc":
+        if hdr:
+            x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
+            return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf + 2), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
+                    "-x265-params", x265] + hdr_tags + ["-movflags", "+faststart"]
+        params, extra = _sdr_bt709("libx265")
+        return ["-c:v", "libx265", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-tag:v", "hvc1",
+                "-x265-params", "log-level=error" + (":" + params if params else "")] + extra + ["-movflags", "+faststart"]
+    if codec == "av1":
+        pix = "yuv420p10le" if hdr else "yuv420p"
+        if "libsvtav1" in ffmpeg_encoders():
+            args = ["-c:v", "libsvtav1", "-preset", str(SVT_PRESET.get(preset, 6)), "-crf", str(min(63, crf)), "-pix_fmt", pix]
+            if hdr:
+                args += hdr_tags
+            else:
+                params, extra = _sdr_bt709("libsvtav1")
+                args += (["-svtav1-params", params] if params else []) + extra
+        elif "libaom-av1" in ffmpeg_encoders():
+            args = ["-c:v", "libaom-av1", "-crf", str(min(63, crf)), "-b:v", "0", "-cpu-used", "6", "-row-mt", "1", "-pix_fmt", pix]
+            args += hdr_tags if hdr else _sdr_bt709("libaom-av1")[1]
+        else:
+            die("--codec av1 needs an AV1 encoder (libsvtav1 or libaom-av1) and this ffmpeg build has neither", kind="missing_tool",
+                hint="install an ffmpeg built with SVT-AV1 (most distribution builds are), or use --codec hevc")
+        return args + ["-movflags", "+faststart"]
+    if codec == "prores":
+        if "prores_ks" not in ffmpeg_encoders():
+            die("--codec prores needs the prores_ks encoder and this ffmpeg build lacks it", kind="missing_tool")
+        return ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"] + (hdr_tags if hdr else [])
+    die(f"unknown --codec {codec!r} (one of {', '.join(CODECS)})")
+    return []
+
+
+def _x264_raw(crf: int, preset: str, keep_bt709: bool = True) -> List[str]:
     args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
     if keep_bt709:
         args += bt709_tag_args("libx264")
     return args
 
 
+def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
+    """SDR H.264 encoder args -- or, when --codec named another encoder, that encoder's SDR args
+    (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it)."""
+    if STATE.codec and STATE.codec != "h264":
+        return encoder_args(STATE.codec, crf, preset, None)
+    return _x264_raw(crf, preset, keep_bt709)
+
+
 def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
     """Encoder args that preserve what the source is.
 
@@ -1634,6 +1745,8 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
     so cutting/captioning/fitting an iPhone HDR clip stays HDR instead of becoming a
     washed-out file mislabelled as BT.709. Use color.py --to-sdr when SDR is wanted.
     """
+    if STATE.codec:
+        return encoder_args(STATE.codec, crf, preset, meta)
     v = (meta or {}).get("video") or {}
     if not v.get("hdr"):
         return x264_args(crf, preset)

package/scripts/_contract.py

@@ -57,6 +57,10 @@ ROLES = {
 FF = ["ffmpeg", "ffprobe"]
 X264 = "encoder:libx264"
 X265 = "encoder:libx265"
+# --codec (1.8, every tool that re-encodes): the encoder the flag names, on top of the tool's own list
+CODEC_CAPS = [{"capability": X265, "when": "--codec hevc"},
+              {"capability": "encoder:libsvtav1", "when": "--codec av1 (libaom-av1 is the fallback)"},
+              {"capability": "encoder:prores_ks", "when": "--codec prores"}]
 AAC = "encoder:aac"
 HDR_X265 = {"capability": X265, "when": "the source is HDR (kept as HEVC Main10)"}
 AUDIO_OUT = [
@@ -333,7 +337,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     props: Dict[str, Any] = {}
     required: List[str] = []
     positional: List[str] = []
-    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite", "plan"}
+    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite", "plan", "codec", "quality"}
     for action in parser._actions:
         if isinstance(action, argparse._HelpAction):
             continue
@@ -648,6 +652,7 @@ def required_capabilities() -> Dict[str, List[str]]:
     for meta in TOOL_META.values():
         req.update(meta["required"])
         opt.update(o["capability"] for o in meta["optional"] if o["capability"] != "delegated")
+    opt.update(o["capability"] for o in CODEC_CAPS)
     opt -= req
     return {"required": sorted(req), "optional": sorted(opt)}
 
@@ -898,7 +903,7 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
         "description": (parser.description or "").strip().splitlines()[0] if parser.description else "",
         "executable": f"scripts/{name}.py",
         "role": meta["role"],
-        "capabilities": {"required": list(meta["required"]), "optional": list(meta["optional"])},
+        "capabilities": {"required": list(meta["required"]), "optional": list(meta["optional"]) + (CODEC_CAPS if "codec" in schema["properties"] else [])},
         "inputs": list(meta["inputs"]),
         "outputs": list(meta["outputs"]),
         "input_schema": schema,

package/scripts/export.py

@@ -73,6 +73,9 @@ def main() -> int:
     if not args.input or not args.preset:
         die("input and --preset are required (or use --list)")
     validate_color(args.pad_color, "--pad-color")
+    if args.codec:
+        die(f"export.py's presets decide the codec (--preset h265 for HEVC, prores for ProRes); --codec {args.codec} is for the editing tools",
+            hint="drop --codec here, or run the edit with --codec and export with --preset copy")
 
     p = PRESETS[args.preset]
     meta = probe(args.input)