ffmpeg-skill 1.26.0 → 2.1.0

package/scripts/_contract.py

@@ -206,7 +206,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                  required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"},
                                                           {"capability": "filter:drawbox", "when": "--safe NAME (the platform's occluded zones)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
                  video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
-    "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)"],
+    "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)", "editor timeline (.fcpxml / .edl / .otio) instead of a render (--export-timeline)"],
                    required=FF, optional=[{"capability": "delegated", "when": "each stage (and each destination of --template) runs cut / join / fit / caption / graphics / overlay / audio / loudness / export / check with their capabilities"}],
                    video_required=True, audio_only=False, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],
@@ -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:
@@ -428,7 +426,10 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"]},
                  "plan": {"type": "string", "description": "when the argument was a plan.json (written by <tool> --plan): its path"},
                  "tool": {"type": "string", "description": "plan execution: the tool the plan ran"},
-                 "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"}}
+                 "tool_result": {"type": "object", "description": "plan execution: the tool's own --json document"},
+                 "timeline": {"type": "object", "description": "--export-timeline: format, rate, duration, frames, clips, transition, "
+                              "transition_frames, music, markers, notes, and not_exported (what the project asks for that an "
+                              "editor timeline cannot carry)"}}
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]}, "files": {"type": "array"}, "failed": {"type": "integer"}, "total": {"type": "integer"}}
     elif name == "batch":
@@ -1087,34 +1088,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 +1191,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 +1265,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 +1302,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,14 +141,17 @@ 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"):
-        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"))
+    if meta["video"].get("bt2020_or_hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
+        # 2.0: `hdr` is a real PQ/HLG/DV signal; bt2020_or_hdr also covers BT.2020 SDR, which is
+        # not HDR but still needs converting before BT.709 tags describe it (eval 24 h1)
+        kind = "HDR" if meta["video"].get("hdr") else "wide-gamut SDR, not HDR"
+        notes.append("source is %s (%s). This preset outputs SDR BT.709 tags without converting it; run color.py --to-sdr first for correct colours." % (kind, meta["video"].get("hdr_format")))
         info("warning: " + notes[-1])
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, args.preset, p["ext"])

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, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version
 import subprocess
 from _contract import CONTRACT_VERSION
 from batch import file_key
@@ -718,6 +718,44 @@ def frame_from_preset(frame: Dict[str, Any], export: Dict[str, Any]) -> None:
     info(f"frame: {preset['w']}x{preset['h']} from the {export['preset']} export preset (captions and overlays are sized for delivery)")
 
 
+def export_timeline(proj: Dict[str, Any], rel, dest: str) -> int:
+    """--export-timeline: the project's cut as an editor timeline, nothing rendered (_common.timeline)."""
+    from _common import timeline as tlmod
+    fmt = tlmod.FORMATS.get(Path(dest).suffix.lower())
+    if not fmt:
+        die(f"--export-timeline {dest}: unknown timeline format", kind="input",
+            hint="name the file .fcpxml, .edl or .otio")
+    paths = [rel(c["src"]) for c in proj.get("clips") or [] if c.get("src")]
+    if (proj.get("audio") or {}).get("music"):
+        paths.append(rel(proj["audio"]["music"]))
+    probes: Dict[str, Dict[str, Any]] = {}
+    for path in paths:
+        if not os.path.exists(path):
+            die(f"timeline source not found: {path}")
+        probes[path] = probe(path)  # a timeline needs real durations and rates, dry run or not
+    try:
+        tl = tlmod.build(proj, probes, rel)
+    except tlmod.TimelineError as exc:
+        die(f"--export-timeline: {exc}", kind="input")
+    text = tlmod.WRITERS[fmt](tl)
+    report = tlmod.summary(tl, fmt)
+    _check_output_path(["ffmpeg", dest])
+    _check_existing_output(["ffmpeg", dest])
+    verification: List[Dict[str, Any]] = []
+    if not STATE.dry_run:
+        try:
+            Path(dest).write_text(text, encoding="utf-8")
+        except OSError as exc:
+            die(f"cannot write {dest}: {exc}", kind="output")
+        verification.append({"step": "parse", "ok": tlmod.parses(dest, fmt)})
+    for line in report["not_exported"]:
+        info(f"not exported: {line}")
+    info(("[dry-run] would write " if STATE.dry_run else "wrote ") +
+         f"{dest} ({fmt}, {report['clips']} clips, {report['duration']}s at {report['rate']} fps)")
+    emit(dest, timeline=report, verification=verification)
+    return 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("project", nargs="?", help="project.json, or a plan.json written by <tool> --plan")
@@ -732,6 +770,10 @@ def main() -> int:
                     choices=list(STAGE_ORDER),
                     help="start at this stage, taking every earlier one from --cache; refuses if "
                          "one of them is not there")
+    ap.add_argument("--export-timeline", metavar="FILE",
+                    help="write the project's cut as an editor timeline instead of rendering it: .fcpxml (Final Cut, "
+                         "Resolve), .edl (CMX 3600: Premiere, Resolve, Avid) or .otio (OpenTimelineIO); clips, speed, "
+                         "transitions, the music bed and chapter markers carry over, everything else is listed as not exported")
     ap.add_argument("--stop-after", choices=["clips", "join", "silence", "fit", "captions", "graphics", "overlays", "audio", "loudness", "export"], help="stop after this stage (for iterating)")
     tpl = ap.add_argument_group("delivery templates (one command per destination)")
     tpl.add_argument("--template", metavar="NAME", help="render INPUT with a shipped template: " + ", ".join(template_names())
@@ -810,12 +852,18 @@ def main() -> int:
     if isinstance(proj.get("chapters"), str) and not os.path.exists(rel(proj["chapters"])):
         die(f"chapters file not found: {rel(proj['chapters'])}")
 
+    if args.export_timeline:
+        return export_timeline(proj, rel, args.export_timeline)
+
     clips = proj.get("clips") or []
     if not clips:
         die("project.clips is empty")
     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"],
     ]

package/scripts/reverse.py

@@ -22,7 +22,7 @@ def main() -> int:
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_reverse.<ext>)")
     ap.add_argument("--no-audio", action="store_true", help="drop audio instead of reversing it")
-    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()