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.

feat: --codec h264|hevc|av1|prores and --quality on every re-encoding tool, resolved in encoder_args() (#203)

claude[bot]3806959d8025
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 979a7b7..ce1d670 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
## Unreleased
-(nothing yet)
+- `--codec h264|hevc|av1|prores` and `--quality N` on every tool that re-encodes (issue #189 B, pre-shipped from the 2.0 decision in docs/design-decisions.md). One resolver, `_common.encoder_args()`: hevc keeps HDR sources Main10 with their tags and writes 8-bit BT.709 for SDR; av1 uses SVT-AV1 (libaom fallback), 10-bit for HDR; prores is 422 HQ and needs a `.mov`/`.mkv` output; h264 refuses HDR (`kind: input`, the hint names `color.py --to-sdr`). `--quality` is the CRF scale and overrides `--crf`; without `--codec` nothing changes (x264 for SDR, x265 for HDR). `export.py` keeps its presets and refuses `--codec`. The contract lists the encoder each `--codec` value needs under the tool's optional capabilities.
## 1.7.2
diff --git a/SKILL.md b/SKILL.md
index 96ef77c..5659a16 100644
--- a/SKILL.md
+++ b/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)
diff --git a/docs/contract.md b/docs/contract.md
index 6fa9fa3..010fb36 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -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
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 9c3ab8e..0f5af0b 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -144,6 +144,8 @@ exists. When a decision changes, edit the entry in the same PR.
`export.py` presets are the only place a non-x264 codec is chosen. Rejected: a per-tool
`--codec` added piecemeal in 1.x (the audits found HDR fragility wherever encoder choice was
duplicated; one more duplication is the wrong direction). Code: `_common.video_args()`.
+ 1.8.0 shipped the two flags (`add_common()` adds them to every tool that declares `--crf`;
+ `encoder_args()` resolves them; `--crf`/`--preset` unchanged), so 2.0 only has to deprecate the aliases.
- **Per-request Context: `STATE` stays process-global through 1.x; 2.0 passes a `Context`
explicitly to `run()`/`emit()`/`die()`.** Today the MCP server spawns one subprocess per
call, so the global is never shared between requests; the risk only appears if a future
diff --git a/references/scripts.md b/references/scripts.md
index 70fc366..eed5b1f 100644
--- a/references/scripts.md
+++ b/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
diff --git a/scripts/_common.py b/scripts/_common.py
index ec56ecd..a8b79a4 100755
--- a/scripts/_common.py
+++ b/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)
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 4bc6339..07a0b16 100644
--- a/scripts/_contract.py
+++ b/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,
diff --git a/scripts/export.py b/scripts/export.py
index 06a19f0..10e7cc4 100755
--- a/scripts/export.py
+++ b/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)
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index f2e6d8a..8a27084 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -56,6 +56,7 @@
"properties": [
"angle",
"argv",
+ "codec",
"color",
"crf",
"dry_run",
@@ -70,6 +71,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout",
"width"
],
@@ -100,6 +102,7 @@
"argv",
"at",
"audio",
+ "codec",
"crf",
"dry_run",
"duration",
@@ -115,6 +118,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout"
],
"required": []
@@ -130,6 +134,7 @@
"bold",
"box",
"brand",
+ "codec",
"color",
"crf",
"dry_run",
@@ -155,6 +160,7 @@
"position",
"preset",
"progress",
+ "quality",
"shadow",
"size",
"srt",
@@ -193,6 +199,7 @@
"properties": [
"argv",
"audio_stream",
+ "codec",
"contrast",
"correct",
"crf",
@@ -219,6 +226,7 @@
"plan",
"preset",
"progress",
+ "quality",
"retag",
"saturation",
"strip_dovi",
@@ -234,6 +242,7 @@
"name": "crop",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -246,6 +255,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout",
"width",
"x",
@@ -277,6 +287,7 @@
"properties": [
"accurate",
"argv",
+ "codec",
"crf",
"dry_run",
"duration",
@@ -289,6 +300,7 @@
"plan",
"preset",
"progress",
+ "quality",
"segments",
"start",
"timeout",
@@ -301,6 +313,7 @@
"properties": [
"argv",
"audio_stream",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -314,6 +327,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout"
],
"required": []
@@ -325,6 +339,7 @@
"audio_stream",
"chroma_spatial",
"chroma_temporal",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -338,6 +353,7 @@
"plan",
"preset",
"progress",
+ "quality",
"strength",
"timeout"
],
@@ -348,6 +364,7 @@
"properties": [
"allow_long",
"argv",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -365,6 +382,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout"
],
"required": []
@@ -375,6 +393,7 @@
"argv",
"aspect",
"audio_stream",
+ "codec",
"crf",
"crop_x",
"crop_y",
@@ -398,6 +417,7 @@
"plan",
"preset",
"progress",
+ "quality",
"rotate",
"smooth",
"timeout",
@@ -410,6 +430,7 @@
"properties": [
"argv",
"at",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -422,6 +443,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout"
],
"required": []
@@ -432,6 +454,7 @@
"argv",
"audio_stream",
"brand",
+ "codec",
"count_from",
"crf",
"dry_run",
@@ -449,6 +472,7 @@
"preset",
"primary",
"progress",
+ "quality",
"scale",
"start",
"subtitle",
@@ -467,6 +491,7 @@
"background",
"cell_height",
"cell_width",
+ "codec",
"cols",
"crf",
"dry_run",
@@ -485,6 +510,7 @@
"plan",
"preset",
"progress",
+ "quality",
"rows",
"timeout"
],
@@ -494,6 +520,7 @@
"name": "insert",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"duration",
@@ -508,6 +535,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout",
"width",
"zoom",
@@ -520,6 +548,7 @@
"properties": [
"argv",
"channels",
+ "codec",
"crf",
"dry_run",
"duration",
@@ -535,6 +564,7 @@
"plan",
"preset",
"progress",
+ "quality",
"sample_rate",
"timeout",
"transition",
@@ -567,6 +597,7 @@
"name": "loop",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"duration",
@@ -578,6 +609,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout",
"times"
],
@@ -636,6 +668,7 @@
"argv",
"audio",
"auto",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -651,6 +684,7 @@
"plan",
"preset",
"progress",
+ "quality",
"switch",
"timeout",
"width"
@@ -670,6 +704,7 @@
"chromakey",
"chromakey_blend",
"chromakey_similarity",
+ "codec",
"crf",
"dry_run",
"end",
@@ -691,6 +726,7 @@
"position",
"preset",
"progress",
+ "quality",
"scale",
"scale_percent",
"start",
@@ -704,6 +740,7 @@
"name": "pad",
"properties": [
"argv",
+ "codec",
"color",
"crf",
"dry_run",
@@ -716,6 +753,7 @@
"plan",
"preset",
"progress",
+ "quality",
"start",
"timeout"
],
@@ -743,6 +781,7 @@
"name": "proxy",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -754,6 +793,7 @@
"overwrite",
"plan",
"progress",
+ "quality",
"scale",
"timeout",
"width"
@@ -767,6 +807,7 @@
"audio_stream",
"block_size",
"blur_strength",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -780,6 +821,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout",
"width",
"x",
@@ -832,6 +874,7 @@
"name": "reverse",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -843,6 +886,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout"
],
"required": []
@@ -876,6 +920,7 @@
"name": "sequence",
"properties": [
"argv",
+ "codec",
"crf",
"dir",
"dry_run",
@@ -889,6 +934,7 @@
"plan",
"preset",
"progress",
+ "quality",
"start_number",
"timeout",
"width"
@@ -899,6 +945,7 @@
"name": "silence",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"edl",
@@ -914,6 +961,7 @@
"plan",
"preset",
"progress",
+ "quality",
"threshold",
"timeout"
],
@@ -923,6 +971,7 @@
"name": "speedramp",
"properties": [
"argv",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -933,6 +982,7 @@
"plan",
"preset",
"progress",
+ "quality",
"segments",
"timeout"
],
@@ -943,6 +993,7 @@
"properties": [
"argv",
"audio_stream",
+ "codec",
"crf",
"dry_run",
"fast",
@@ -959,6 +1010,7 @@
"plan",
"preset",
"progress",
+ "quality",
"roll",
"stereo",
"timeout",
@@ -972,6 +1024,7 @@
"name": "stabilize",
"properties": [
"argv",
+ "codec",
"crf",
"crop",
"dry_run",
@@ -983,6 +1036,7 @@
"plan",
"preset",
"progress",
+ "quality",
"shakiness",
"smoothing",
"timeout",
@@ -996,6 +1050,7 @@
"properties": [
"argv",
"audio_stream",
+ "codec",
"crf",
"degrees",
"dry_run",
@@ -1010,6 +1065,7 @@
"plan",
"preset",
"progress",
+ "quality",
"timeout"
],
"required": []
@@ -1019,6 +1075,7 @@
"properties": [
"analyze_seconds",
"argv",
+ "codec",
"crf",
"drift_window",
"dry_run",
@@ -1031,6 +1088,7 @@
"overwrite",
"plan",
"progress",
+ "quality",
"reference",
"replace_audio",
"second",
@@ -1066,6 +1124,7 @@
"argv",
"audio_stream",
"background",
+ "codec",
"color",
"crf",
"dry_run",
@@ -1079,6 +1138,7 @@
"plan",
"preset",
"progress",
+ "quality",
"split_channels",
"style",
"timeout",
diff --git a/tests/test_all.py b/tests/test_all.py
index b2aafa0..4e467c4 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -2230,6 +2230,58 @@ class FFmpegSkillTests(unittest.TestCase):
self.assertFalse(data["levels"]["looks_like_log"])
# ---------------------------------------------------------------- v0.5: check / scenes / render
+ def test_codec_and_quality_resolve_in_one_place(self):
+ """1.8 (issue #189 B pre-shipped): --codec / --quality on every re-encoding tool, resolved by
+ encoder_args(). hevc on SDR is 8-bit BT.709 HEVC; prores needs a .mov; h264 refuses HDR;
+ --quality is the CRF; export keeps its presets; without --codec nothing changes."""
+ sys.path.insert(0, str(SCRIPTS))
+ try:
+ import _common
+ finally:
+ sys.path.pop(0)
+ out = OUT / "codec_hevc.mp4"
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "hevc", "--quality", "30", "-o", out, "--fast", "--json", "--overwrite").stdout)
+ self.assertEqual(d["status"], "completed")
+ m = probe(str(out))
+ self.assertEqual(m["video"]["codec"], "hevc")
+ self.assertIn("yuv420p", m["video"].get("pix_fmt", "yuv420p"))
+ self.assertTrue(any("-crf 30" in c for c in d["commands"]), d["commands"])
+ # prores wants a .mov: .mp4 is refused before ffmpeg runs, .mov works
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--codec", "prores", "-o", OUT / "codec_prores.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn(".mov", d["error"]["hint"])
+ mov = OUT / "codec_prores.mov"
+ script("fit.py", self.src, "--width", "320", "--codec", "prores", "-o", mov, "--fast", "--json", "--overwrite")
+ self.assertEqual(probe(str(mov))["video"]["codec"], "prores")
+ # h264 cannot carry HDR; hevc keeps it
+ d = json.loads(script("fit.py", self.hdr, "--width", "320", "--codec", "h264", "-o", OUT / "codec_hdr_h264.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ self.assertIn("to-sdr", d["error"]["hint"])
+ hdr_out = OUT / "codec_hdr_hevc.mp4"
+ script("fit.py", self.hdr, "--width", "320", "--codec", "hevc", "-o", hdr_out, "--fast", "--json", "--overwrite")
+ self.assertTrue(probe(str(hdr_out))["video"]["hdr"])
+ # av1 when the build has an encoder, a missing_tool refusal otherwise
+ av1 = OUT / "codec_av1.mp4"
+ proc = script("fit.py", self.src, "--width", "320", "--codec", "av1", "-o", av1, "--fast", "--json", "--overwrite", expect_fail=not (_common.ffmpeg_encoders() & {"libsvtav1", "libaom-av1"}))
+ d = json.loads(proc.stdout)
+ if d["status"] == "completed":
+ self.assertEqual(probe(str(av1))["video"]["codec"], "av1")
+ else:
+ self.assertEqual(d["error"]["kind"], "missing_tool")
+ # --quality bounds follow the codec; export refuses --codec
+ d = json.loads(script("fit.py", self.src, "--width", "320", "--quality", "60", "-o", out, "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ d = json.loads(script("export.py", self.src, "--preset", "x", "--codec", "hevc", "-o", OUT / "codec_export.mp4", "--json", expect_fail=True).stdout)
+ self.assertEqual(d["error"]["kind"], "input")
+ # no --codec: the old default line, byte for byte
+ d = json.loads(script("fit.py", self.src, "--width", "320", "-o", out, "--fast", "--json", "--overwrite").stdout)
+ self.assertTrue(any("libx264" in c for c in d["commands"]))
+ # every tool that declares --crf now advertises the two flags
+ for name in ("cut", "caption", "overlay", "color", "join", "proxy"):
+ h = script(f"{name}.py", "--help").stdout
+ self.assertIn("--codec", h, name)
+ self.assertIn("--quality", h, name)
+
def test_check_compliance(self):
reels = OUT / "export_reels.mp4"
if not reels.exists():