ffmpeg-skill 1.25.0 → 2.0.0

package/scripts/_common/runner.py

@@ -195,45 +195,20 @@ def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
         g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
                        help=f"kill an ffmpeg run past this many seconds, kind=timeout (default {DEFAULT_TIMEOUT:.0f}; 0 = no limit)")
     g.add_argument("--overwrite", action="store_true",
-                   help="allow replacing an existing output (warned today, refused from 2.0)")
+                   help="allow replacing an existing output (refused without it)")
     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 codec and "--crf" in ap._option_string_actions:
-        # --crf became an alias of --quality in 1.8; 1.10 deprecates it (removed in 2.0, see the
-        # `deprecated` list in `contract --json` and docs/contract.md "What 2.0 changes"). Marked
-        # here, once, rather than in each re-encoding tool's own parser.
-        crf = ap._option_string_actions["--crf"]
-        # The flag's own default moves aside so apply_common() can tell an explicit --crf (in any
-        # spelling argparse accepts, including the --cr / --c abbreviations) from the default;
-        # apply_common() puts _CRF_DEFAULT back when the flag was absent.
-        global _CRF_DEFAULT
-        _CRF_DEFAULT = crf.default
-        crf.deprecated_default = crf.default  # the schema still advertises it (_contract._json_type)
-        crf.default = None
-        if "deprecated" not in (crf.help or ""):
-            # the nine tools that declare --crf with no help string used to fall through this and
-            # never show the mark at all (review 9)
-            crf.help = (crf.help or "x264 CRF when re-encoding (default 18)") + " (deprecated: use --quality)"
-        # 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)
+    if codec and "crf" in ap._defaults:
+        # A tool that re-encodes declares its CRF default with set_defaults(crf=N) before calling
+        # this; --codec/--quality are its only encoder flags, resolved in video_args(). --crf was
+        # the 1.x spelling of --quality (an alias from 1.8, deprecated in 1.10, removed in 2.0).
         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")
-
-
-# The declared default of a deprecated --crf, parked by add_common() (one parser per process).
-_CRF_DEFAULT: Optional[int] = None
+        g.add_argument("--quality", type=int, default=ap._defaults["crf"], metavar="N",
+                       help="encoder quality on the CRF scale (default %(default)s; lower = better; 18 visually lossless for x264/x265, up to 63 for av1); ignored by prores")
 
 
 def apply_common(args: "argparse.Namespace") -> None:
-    # Was --crf typed? add_common() parked the flag's default (None in its place) on every tool
-    # whose --crf is deprecated, i.e. the ones that also have --quality; export.py's --crf is not
-    # an alias and keeps its own default. Scanning sys.argv for "--crf" instead missed the unique
-    # prefixes argparse accepts (--cr, --c) and never ran for batch.py's recipe steps (review 9).
-    crf_explicit = hasattr(args, "quality") and getattr(args, "crf", None) is not None
-    if hasattr(args, "quality") and hasattr(args, "crf") and args.crf is None:
-        args.crf = _CRF_DEFAULT
     STATE.plan = getattr(args, "plan", None) or None
     STATE.dry_run = bool(getattr(args, "dry_run", False)) or bool(STATE.plan)
     if STATE.plan:
@@ -269,12 +244,7 @@ def apply_common(args: "argparse.Namespace") -> None:
         if 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)
-    # The warning the deprecation policy asks for, only when the caller typed the flag (see
-    # crf_explicit above). export.py has no --quality (its preset chooses the encoder), so its
-    # --crf is not an alias and is not deprecated: warn only where --quality exists.
-    if crf is not None and crf_explicit:
-        info("warning: --crf is deprecated since 1.10.0; use --quality N (the same CRF scale, codec-neutral). --crf is removed in 2.0.")
+    crf = getattr(args, "crf", None)  # export.py's own --crf (its preset chooses the encoder)
     top = 63 if STATE.codec == "av1" else 51
     if crf is not None and not 0 <= int(crf) <= top:
         die(f"--crf must be between 0 and {top} ({'SVT-AV1' if STATE.codec == 'av1' else 'x264/x265'} scale; 18 is visually lossless), got {crf}")
@@ -565,9 +535,9 @@ def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
 def _check_existing_output(cmd: Sequence[str]) -> None:
     """An output path that already exists is someone's file: a previous result, a source the
     agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
-    a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
-    warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
-    2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths this
+    a run never blocks on a y/N prompt) would replace it without a word. Since 2.0 it is refused
+    (kind: input, before anything runs, dry runs included) unless --overwrite gives explicit
+    consent; 1.x only warned, and FFMPEG_SKILL_NO_OVERWRITE=1 was the opt-in to this. Paths this
     process wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""
     output = cmd[-1]
     if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
@@ -586,10 +556,8 @@ def _check_existing_output(cmd: Sequence[str]) -> None:
         pass
     if STATE.overwrite:
         return
-    if os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):
-        die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")
-    info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "
-         f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
+    die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path",
+        kind="input", hint="pass --overwrite, or choose another -o path")
 
 
 def _remember_output(cmd: Sequence[str]) -> None:

package/scripts/_contract.py

@@ -351,9 +351,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
         if isinstance(action, argparse._HelpAction):
             continue
         prop: Dict[str, Any] = _json_type(action)
-        # add_common() parks a deprecated --crf's default aside (so an explicit flag is
-        # distinguishable from the default); the schema still advertises the real one
-        default = getattr(action, "deprecated_default", action.default)
+        default = action.default
         if action.help and action.help != argparse.SUPPRESS:
             prop["description"] = action.help % {"default": default} if "%(default)" in action.help else action.help
         if action.choices:
@@ -1087,34 +1085,39 @@ def tool_spec(name: str, version: str) -> Dict[str, Any]:
 # tools that print JSON without --json (probe) or whose primary output is a file path (look): the transport
 # does not append --json for them (stated in invocation.structured.argument_mapping.json)
 # ----------------------------------------------------------------------------- deprecations
-# What 2.0.0 removes, announced here per docs/contract.md's three-step deprecation policy:
+# What the next major removes, announced here per docs/contract.md's three-step deprecation policy:
 # 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. docs/contract.md's
-# "What 2.0 changes" section is written from this list.
-DEPRECATED: List[Dict[str, str]] = [
-    {"what": "top-level per-tool keys next to result_v2 in a success document (output, probe, commands, verified, verification and each tool's own keys)",
-     "since": "1.10.0", "replacement": "result_v2 (FFMPEG_SKILL_RESULT_V2=1 today; the only shape in 2.0)",
-     "removed_in": "2.0.0", "where": "json"},
+# 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]] = []
+
+# 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
+# a CHANGELOG. docs/contract.md's "What 2.0 changed" table is written from this list.
+REMOVED: List[Dict[str, str]] = [
     {"what": "--crf as an alias of --quality on every re-encoding tool that takes --quality (export.py keeps --crf: its preset chooses the encoder)",
-     "since": "1.10.0", "replacement": "--quality N (same CRF scale, codec-neutral)",
-     "removed_in": "2.0.0", "where": "cli"},
+     "since": "1.10.0", "removed_in": "2.0.0", "where": "cli",
+     "replacement": "--quality N (the same CRF scale, codec-neutral; each tool's old --crf default is its --quality default)"},
     {"what": "json and progress in the MCP inputSchema (they are CLI transport flags, not tool arguments)",
-     "since": "1.10.0", "replacement": "nothing: the MCP transport sets them itself (FFMPEG_SKILL_MCP_LEAN=1 drops them today)",
-     "removed_in": "2.0.0", "where": "mcp"},
+     "since": "1.10.0", "removed_in": "2.0.0", "where": "mcp",
+     "replacement": "nothing: the MCP transport sets them itself; a client that still sends them is not refused"},
     {"what": "probe's hdr meaning BT.2020 primaries or a PQ/HLG transfer",
-     "since": "1.10.0", "replacement": "hdr_signal (true only for PQ / HLG / Dolby Vision); in 2.0 hdr takes that meaning and hdr_format keeps naming the BT.2020 SDR case",
-     "removed_in": "2.0.0", "where": "json"},
-    {"what": "overwriting an existing output without --overwrite (warned, not refused)",
-     "since": "1.10.0", "replacement": "--overwrite, or FFMPEG_SKILL_NO_OVERWRITE=1 to refuse today",
-     "removed_in": "2.0.0", "where": "behaviour"},
+     "since": "1.10.0", "removed_in": "2.0.0", "where": "json",
+     "replacement": "hdr is now true only for PQ / HLG / Dolby Vision (as hdr_signal, which stays); bt2020_or_hdr carries the 1.x meaning"},
+    {"what": "overwriting an existing output without --overwrite (1.x warned)",
+     "since": "1.10.0", "removed_in": "2.0.0", "where": "behaviour",
+     "replacement": "--overwrite as explicit consent; without it an existing output is refused (kind: input) before anything runs"},
+    {"what": "the result_v2 preview key and FFMPEG_SKILL_RESULT_V2 (the v1 top-level keys it was to replace were un-deprecated: they are the 2.0 shape)",
+     "since": "1.10.0", "removed_in": "2.0.0", "where": "json",
+     "replacement": "the top-level keys, unchanged from 1.x; --json-brief for a short document"},
 ]
 
 
 MCP_JSON_EXEMPT = ("look", "probe")
-# opt-in lean MCP schema (roadmap 1.10.0): json/progress are transport flags the server appends
-# itself, not tool arguments. Off by default so tools/list stays byte-identical to the CLI surface
-# the contract promises; 2.0 drops them unconditionally.
-MCP_LEAN_DROP = ("json", "progress")
+# json/progress are CLI transport flags the MCP server sets itself, not tool arguments: 2.0 leaves
+# them out of every inputSchema (1.10.0-1.x kept them unless FFMPEG_SKILL_MCP_LEAN=1). A client
+# that still sends them is not refused -- build_argv() maps them like any other key.
+MCP_TRANSPORT_FLAGS = ("json", "progress")
 # default MCP tools/list surface (roadmap P1-7, shipped 1.18.3): the 42-tool schema dump costs
 # every MCP session context whether it needs it or not. These 12 are the tools eval iterations
 # 17-20's ground-truth `expect` lists actually name most often across the 118 agent prompts in
@@ -1185,7 +1188,7 @@ MCP_PROMPTS: List[Dict[str, Any]] = [
         "template": ("Bring {input} from HDR/Dolby Vision down to SDR: `color.py {input} --to-sdr` (or `--strip-dovi` "
                      "to keep HDR and only drop the Dolby Vision layer, when strip_dovi is asked for). A flat, washed-out "
                      "look after a re-encode usually means HDR metadata was lost upstream; `probe` shows `hdr: true` "
-                     "for BT.2020 primaries or a PQ/HLG transfer, and `hdr_signal: true` only for a real PQ/HLG/DV transfer."),
+                     "only for a real PQ/HLG/Dolby Vision signal, and `bt2020_or_hdr: true` also for BT.2020 SDR."),
     },
 ]
 
@@ -1259,13 +1262,12 @@ def mcp_input_schema(spec: Dict[str, Any]) -> Dict[str, Any]:
     one_of = [[{"required": [d]} for d in group] for group in src.get("one_of_required", [])]
     if one_of:
         structured["anyOf"] = one_of[0] if len(one_of) == 1 else [{"allOf": [{"anyOf": g} for g in one_of]}]
-    if os.environ.get("FFMPEG_SKILL_MCP_LEAN", "") not in ("", "0"):
-        for dest in MCP_LEAN_DROP:
-            props.pop(dest, None)
-        if structured.get("required"):
-            structured["required"] = [d for d in structured["required"] if d not in MCP_LEAN_DROP]
-            if not structured["required"]:
-                del structured["required"]
+    for dest in MCP_TRANSPORT_FLAGS:
+        props.pop(dest, None)
+    if structured.get("required"):
+        structured["required"] = [d for d in structured["required"] if d not in MCP_TRANSPORT_FLAGS]
+        if not structured["required"]:
+            del structured["required"]
     schema: Dict[str, Any] = {"type": "object", "properties": props, "additionalProperties": False}
     if structured:
         schema["anyOf"] = [{"required": ["argv"]}, structured]
@@ -1297,6 +1299,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
     return {
         "contract_version": CONTRACT_VERSION,
         "deprecated": [dict(d) for d in DEPRECATED],
+        "removed": [dict(d) for d in REMOVED],
         "skill": {
             "id": SKILL_ID,
             "version": version,

package/scripts/background.py

@@ -28,7 +28,7 @@ def main() -> int:
     src.add_argument("--color", default="black", help="solid background colour, e.g. black, 0x101010 (default black)")
     src.add_argument("--gradient", help="two colours as C1:C2 for a linear gradient, e.g. 0xff6a00:0x0057ff")
     ap.add_argument("--angle", type=float, default=0.0, help="gradient angle in degrees (with --gradient, default 0 = left to right)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()

package/scripts/broll.py

@@ -35,7 +35,7 @@ def main() -> int:
     ap.add_argument("--from", dest="from_", action="append", metavar="TIME", help="where in B to start from (default 0); one per --insert, or omit")
     ap.add_argument("--audio", choices=["a", "b", "mix"], default="a", help="under a cutaway: A's audio (default), B's audio, or both mixed")
     ap.add_argument("--pad-color", default="black", help="pad colour when B's aspect differs from A's (default black)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
@@ -104,7 +104,7 @@ def main() -> int:
     for i, c in enumerate(cutaways):
         geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
         parts.append(f"[{i + 1}:v]trim=start={c['from']:.3f}:duration={c['length']:.3f},setpts=PTS-STARTPTS+{c['at']:.3f}/TB,"
-                     f"{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('hdr') else 'yuv420p'}[b{i}]")
+                     f"{geo},setsar=1,fps={fps:g},format={'yuv420p10le' if (meta_a.get('video') or {}).get('bt2020_or_hdr') else 'yuv420p'}[b{i}]")
         parts.append(f"{cur}[b{i}]overlay=0:0:eof_action=pass:enable='between(t,{c['at']:.3f},{c['at'] + c['length']:.3f})'[v{i}]")
         cur = f"[v{i}]"
     vout = cur

package/scripts/caption.py

@@ -939,7 +939,7 @@ def main() -> int:
                       help="how words are timed inside a cue: 'energy' follows the speech loudness in the audio (default), 'even' splits time equally")
     anim.add_argument("--write-ass", help="where to save the generated ASS (default: next to the output)")
     enc = ap.add_argument_group("encoding")
-    enc.add_argument("--crf", type=int, default=18)
+    enc.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args(_glue_negative_offset(sys.argv[1:]))

package/scripts/check.py

@@ -137,14 +137,14 @@ def main() -> int:
         if args.platform in ("reels", "tiktok", "x", "linkedin", "facebook"):
             row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p",
                 reason="QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0")
-        if spec["sdr_only"] and v.get("hdr"):
+        if spec["sdr_only"] and v.get("bt2020_or_hdr"):
             row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr",
                 reason="a platform or player without HDR support will show this washed-out, too dark, or with wrong colours -- not a rendering glitch, a colour space mismatch")
         else:
             tags = (v.get("color_primaries"), v.get("color_transfer"))
             untagged = not tags[0] and not tags[1]
-            if v.get("hdr") or tags == ("bt709", "bt709") or args.platform in ("podcast", "custom"):
-                row("colour", "PASS", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("hdr") else ""), "bt709/bt709 tagged (or HDR)")
+            if v.get("bt2020_or_hdr") or tags == ("bt709", "bt709") or args.platform in ("podcast", "custom"):
+                row("colour", "PASS", f"{tags[0]}/{tags[1]}" + (f" ({v.get('hdr_format')})" if v.get("bt2020_or_hdr") else ""), "bt709/bt709 tagged (or HDR)")
             elif untagged and (v.get("bit_depth") or 8) == 8:
                 # untagged 8-bit video is treated as BT.709 by every player and platform; nothing to fix
                 row("colour", "PASS", "untagged (players assume bt709)", "bt709/bt709 tagged (or HDR)")

package/scripts/color.py

@@ -203,7 +203,7 @@ def main() -> int:
                           "the first track, same as leaving it unset always did. Only affects modes that re-encode "
                           "audio (--to-sdr, --lut, --correct, and --retag's re-encode fallback) -- --strip-dovi and "
                           "a successful --retag stream-copy all streams untouched, so the flag has nothing to select there.")
-    ap.add_argument("--crf", type=int, default=18)
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
@@ -279,13 +279,13 @@ def main() -> int:
 
     measurements = None
     if args.to_sdr:
-        if not v.get("hdr") and not args.force:
+        if not v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
         vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
     elif args.correct:
-        if v.get("hdr") and not args.force:
+        if v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is HDR ({v.get('hdr_format')}); --correct works on SDR pixels and would tag PQ/HLG data as BT.709 "
                 f"without a tone map (sweep F10). Run --to-sdr first, or --force to grade the raw values anyway")
         vf = correction_chain(args)
@@ -295,7 +295,7 @@ def main() -> int:
         # "looks better" judgement -- the same primitive probe.py --analyze uses for Log detection.
         measurements = None if STATE.dry_run else {"input": analyze_levels(args.input)}
     else:
-        if v.get("hdr") and not args.force:
+        if v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is HDR ({v.get('hdr_format')}); a LUT made for SDR applied to PQ/HLG pixels gives a wrong picture "
                 f"tagged BT.709 (sweep F10). Run --to-sdr first (or chain it), or --force if the LUT expects HDR input")
         if not os.path.exists(args.lut):

package/scripts/crop.py

@@ -32,7 +32,7 @@ def main() -> int:
     ap.add_argument("--y", type=int, required=True, help="top edge of the crop rectangle, in source pixels")
     ap.add_argument("--width", type=int, required=True, help="crop width in px (must be even)")
     ap.add_argument("--height", type=int, required=True, help="crop height in px (must be even)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)

package/scripts/cut.py

@@ -292,7 +292,7 @@ def main() -> int:
                            "this media file) instead of measuring the input again")
     snap.add_argument("--min-confidence", type=float, default=BEAT_MIN_CONFIDENCE,
                       help=f"refuse to snap below this measured beat confidence (default {BEAT_MIN_CONFIDENCE})")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset when re-encoding")
     add_common(ap)
     args = ap.parse_args()

package/scripts/deinterlace.py

@@ -40,7 +40,7 @@ def main() -> int:
                      help="only deinterlace frames the source marks as interlaced; leave the rest untouched")
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (default 0)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()

package/scripts/denoise.py

@@ -42,7 +42,7 @@ def main() -> int:
     ap.add_argument("--chroma-temporal", type=float, help="temporal chroma denoising strength (default from --strength)")
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (default 0)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)

package/scripts/export.py

@@ -141,13 +141,13 @@ def main() -> int:
     if not meta.get("video"):
         die("input has no video stream")
     notes: List[str] = []
-    if p.get("hdr_only") and not meta["video"].get("hdr"):
+    if p.get("hdr_only") and not meta["video"].get("bt2020_or_hdr"):
         # The point of this preset is that the delivery stays HDR. Running it on an SDR source
         # would write a 10-bit HEVC file labelled with SDR tags and call it an HDR delivery.
         die(f"--preset {args.preset} delivers HDR and this source is SDR ({meta['video'].get('codec')}, "
             f"{meta['video'].get('color_transfer') or 'untagged'})",
             hint="use --preset youtube for an SDR delivery; there is no way to invent HDR range from an SDR master")
-    if meta["video"].get("hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
+    if meta["video"].get("bt2020_or_hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
         notes.append("source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
         info("warning: " + notes[-1])
     has_audio = bool(meta.get("audio"))

package/scripts/fit.py

@@ -106,7 +106,7 @@ def main() -> int:
     r.add_argument("--rotate", type=int, choices=[90, 180, 270], help="rotate the picture clockwise by this many degrees")
     r.add_argument("--flip", choices=["h", "v"], help="mirror the picture horizontally (h) or vertically (v)")
     e = ap.add_argument_group("encoding")
-    e.add_argument("--crf", type=int, default=18)
+    e.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     e.add_argument("--preset", default="medium", choices=X264_PRESETS)
     e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)
@@ -227,7 +227,7 @@ def main() -> int:
             # (gamma-encoded) signal and something else entirely on a PQ/HLG one -- so an HDR
             # source keeps its blurred background undimmed rather than being silently altered
             # (review 12). The blur itself is neutral either way, and no tone mapping happens.
-            darken = 0.0 if meta["video"].get("hdr") else BLUR_DARKEN
+            darken = 0.0 if meta["video"].get("bt2020_or_hdr") else BLUR_DARKEN
             if not darken:
                 info("--fit blur: HDR source, so the blurred background is not dimmed "
                      "(an eq on PQ/HLG code values is not the -15%% dim it is on SDR); "

package/scripts/freeze.py

@@ -30,7 +30,7 @@ def main() -> int:
     ap.add_argument("--hold", type=float, required=True, help="how long the freeze lasts, in seconds")
     ap.add_argument("--mode", choices=["insert", "extend"], default="insert",
                      help="insert (default): hold pushes the rest of the clip later; extend: only valid at/after the clip's end, makes the last frame last longer with nothing pushed")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()

package/scripts/graphics.py

@@ -115,7 +115,7 @@ def main() -> int:
     emo.add_argument("--emoji-scale", type=float, default=1.0,
                      help="emoji box as a multiple of the line's font size (default 1.0)")
     emo.add_argument("--emoji-max", type=int, default=60, help="most emoji overlays one run may build (default 60)")
-    ap.add_argument("--crf", type=int, default=18)
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()

package/scripts/grid.py

@@ -49,7 +49,7 @@ def main() -> int:
     ap.add_argument("--audio-from", type=int, help="0-based index into inputs to take audio from (default: no audio)")
     ap.add_argument("--gap", type=int, default=0, help="gap between cells in px, must be even (default 0, cells touch)")
     ap.add_argument("--background", default="black", help="colour of the gap/pad borders (default black)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()
@@ -124,7 +124,7 @@ def main() -> int:
     # A grid is an 8-bit SDR composite by design (a comparison/contact artefact, not a
     # deliverable); an HDR input is flattened like look.py's contact sheet flattens it. Say so
     # once so the caller is not surprised by the 8-bit output.
-    if any((m.get("video") or {}).get("hdr") for m in metas):
+    if any((m.get("video") or {}).get("bt2020_or_hdr") for m in metas):
         info("note: an HDR input is composited into an 8-bit SDR grid (grid.py is a comparison artefact); use color.py --to-sdr first for a graded conversion")
     cmd += video_args(None, args.crf, args.preset)
     cmd += cfr_args(None, args.fps)

package/scripts/insert.py

@@ -46,7 +46,7 @@ def main() -> int:
     ap.add_argument("--zoom", choices=["in", "out"], help="Ken Burns: slow linear zoom in or out across the clip")
     ap.add_argument("--zoom-amount", type=float, default=1.3, help="end (zoom in) or start (zoom out) zoom factor, > 1.0 (default 1.3)")
     ap.add_argument("--pan", choices=["left", "right", "up", "down"], help="drift the visible window this direction while zoomed (needs --zoom)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()

package/scripts/join.py

@@ -93,7 +93,7 @@ def main() -> int:
     ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
     ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
     ap.add_argument("--pad-color", default="black")
-    ap.add_argument("--crf", type=int, default=18)
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     aud = ap.add_argument_group("audio-only inputs")
     aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
@@ -170,7 +170,7 @@ def main() -> int:
         geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"
     # Any HDR input makes the join HDR (10-bit, HEVC via video_args on that clip's tags): an SDR
     # first clip used to drag an HDR second clip down to 8-bit without a tone map.
-    hdr_meta = next((m for m in metas if (m.get("video") or {}).get("hdr")), None)
+    hdr_meta = next((m for m in metas if (m.get("video") or {}).get("bt2020_or_hdr")), None)
     pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
     # the audio-only join keeps the widest layout; the video join used to force stereo and
     # silently dropped the centre/LFE of 5.1 material

package/scripts/look.py

@@ -191,7 +191,7 @@ def main() -> int:
              f"left {z['left'] * 100:.0f}% / right {z['right'] * 100:.0f}% of the frame -- keep text out of those")
     tc = safe_filter + tc
     # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
-    if meta["video"].get("hdr"):
+    if meta["video"].get("bt2020_or_hdr"):
         v = meta["video"]
         tm = (f"zscale=tin={v.get('color_transfer') or 'arib-std-b67'}:pin={v.get('color_primaries') or 'bt2020'}:min={v.get('color_space') or 'bt2020nc'}:rin=tv:t=linear:npl=1000,"
               "format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable,zscale=t=bt709:m=bt709:r=tv,format=yuv420p,")

package/scripts/loop.py

@@ -28,7 +28,7 @@ def main() -> int:
     group = ap.add_mutually_exclusive_group(required=True)
     group.add_argument("--times", type=int, help="repeat the whole clip this many times (2 = original + 1 repeat)")
     group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()

package/scripts/multicam.py

@@ -144,7 +144,7 @@ def main() -> int:
     ap.add_argument("--width", type=int, help="output width (default: reference)")
     ap.add_argument("--height", type=int, help="output height (default: reference)")
     ap.add_argument("--fps", type=float, help="output fps (default: reference)")
-    ap.add_argument("--crf", type=int, default=18)
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()
@@ -260,7 +260,7 @@ def main() -> int:
         w, h = h, w
     fps = args.fps or v0.get("fps") or 30.0
     fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
-    pixfmt = "yuv420p10le" if v0.get("hdr") else "yuv420p"
+    pixfmt = "yuv420p10le" if v0.get("bt2020_or_hdr") else "yuv420p"
     geo = f"scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps={fps:g},format={pixfmt}"
 
     cmd = ffmpeg_base()

package/scripts/overlay.py

@@ -137,7 +137,7 @@ def main() -> int:
     emo.add_argument("--emoji-max", type=int, default=60, help="most emoji overlays one run may build")
     txt.add_argument("--box-color", default="black@0.5")
     enc = ap.add_argument_group("encoding")
-    enc.add_argument("--crf", type=int, default=18)
+    enc.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
     add_common(ap)
     args = ap.parse_args()

package/scripts/pad.py

@@ -26,7 +26,7 @@ def main() -> int:
     ap.add_argument("--start", default="0", help="padding to add before the clip: seconds or mm:ss (default 0)")
     ap.add_argument("--end", default="0", help="padding to add after the clip: seconds or mm:ss (default 0)")
     ap.add_argument("--color", default="black", help="padding colour (default black)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     add_common(ap)
     args = ap.parse_args()

package/scripts/probe.py

@@ -48,7 +48,7 @@ def main() -> int:
                 line += f" | {v.get('width')}x{v.get('height')} @ {v.get('fps')}fps {v.get('codec')} {v.get('pix_fmt')}"
                 if v.get("variable_frame_rate_suspected"):
                     line += " (VFR?)"
-                if v.get("hdr"):
+                if v.get("bt2020_or_hdr"):  # hdr_format also names the BT.2020 SDR case
                     line += f" [{v.get('hdr_format')}]"
                 if r.get("levels", {}).get("looks_like_log"):
                     line += " [Log?]"

package/scripts/proxy.py

@@ -5,7 +5,7 @@ editing-decision workflows that only need to look at (or feed a model) a
 much smaller stand-in for the original.
 
 Resizes to --width (default 640px, height follows the source aspect) or by
---scale factor, re-encodes at a proxy-grade --crf (default 30 - well above any
+--scale factor, re-encodes at a proxy-grade --quality (default 30 - well above any
 delivery preset's 18-24 in export.py, since a proxy trades visual quality for
 size and speed), and always uses the fastest x264/x265 preset. Keeps the
 source's own dynamic range (an HDR source proxies to HEVC10, same as every
@@ -39,7 +39,7 @@ def main() -> int:
     ap.add_argument("-o", "--output", help="output file (default: <name>_proxy.<ext>)")
     ap.add_argument("--width", type=int, default=640, help="output width in px, height follows the source aspect (default 640)")
     ap.add_argument("--scale", type=float, help="scale factor applied to the source dimensions instead of --width (0 < scale <= 1)")
-    ap.add_argument("--crf", type=int, default=30, help="proxy-grade CRF, higher = smaller/lower quality (default 30)")
+    ap.set_defaults(crf=30)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--fps", type=float, help="force a constant output frame rate")
     ap.add_argument("--no-audio", action="store_true", help="drop audio entirely (default: keep it)")
     add_common(ap)

package/scripts/redact.py

@@ -36,7 +36,7 @@ def main() -> int:
     ap.add_argument("--block-size", type=int, default=12, help="mosaic block size in px, --mode pixelate only (default 12)")
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (default 0)")
-    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset")
     ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
     add_common(ap)

package/scripts/render.py

@@ -64,7 +64,7 @@ from typing import Any, Dict, List, Optional, Sequence
 
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import STATE, add_common, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, fingerprint, PLAN_VERSION, ffmpeg_version
+from _common import STATE, add_common, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, _check_existing_output, fingerprint, PLAN_VERSION, ffmpeg_version
 import subprocess
 from _contract import CONTRACT_VERSION
 from batch import file_key
@@ -816,6 +816,9 @@ def main() -> int:
     output = rel(proj.get("output") or "final.mp4")
     # the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)
     refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])
+    # 2.0 refuses an existing output without --overwrite; the final place_output() would, but
+    # only after every stage had run -- say so before the first one instead
+    _check_existing_output(["ffmpeg", output])
     # The default work dir name comes only from the output path, with no PID or timestamp --
     # two concurrent render.py runs targeting the same output (a batch.py "project" recipe
     # processing several files in parallel, or simply running render.py twice by mistake) shared

package/scripts/report.py

@@ -71,7 +71,7 @@ def media_rows(meta: Dict[str, Any], ld: Dict[str, Any]) -> List[List[str]]:
         ["Duration", fmt_dur(meta.get("duration"))],
         ["Size", f"{(meta.get('size_bytes') or 0) / 1024 / 1024:.1f} MB"],
         ["Video", f"{v.get('codec')} {v.get('width')}×{v.get('height')} @ {v.get('fps')} fps, {v.get('pix_fmt')}" if v else "none"],
-        ["Colour", (f"{v.get('color_primaries')}/{v.get('color_transfer')}" + (f" — {v.get('hdr_format')}" if v.get("hdr") else " (SDR)")) if v else "—"],
+        ["Colour", (f"{v.get('color_primaries')}/{v.get('color_transfer')}" + (f" — {v.get('hdr_format')}" if v.get("bt2020_or_hdr") else " (SDR)")) if v else "—"],
         ["Frame rate", ("variable (suspected)" if v.get("variable_frame_rate_suspected") else "constant") if v else "—"],
         ["Audio", f"{a.get('codec')} {a.get('channels')} ch {a.get('sample_rate')} Hz" if a else "none"],
     ]