ffmpeg-skill 1.8.0 → 1.9.0

package/README.md

@@ -355,6 +355,7 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **108 / 108** | 1.8.0 re-run (2026-09-12, three passes per prompt, Sonnet agent, regex grader + independent Opus grader that re-probed 22 outputs): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 22/24, report format 108/108 by regex (91/108 by the stricter grader: 'What/how:' in place of Steps:), user's language 98/108 by the stricter grader (Japanese labels-only reports counted), trigger set 22/22; 13 of 14 platform exports used `--normalize` and platform jobs went from three encodes to one; r04/f01 now answered in the request's language 5/6 (was 0/6). Details in `evals/results/iteration-8.json` |
 | **108 / 108** | 1.7.0 re-run (2026-09-12, three passes per prompt, Sonnet agent, regex grader + independent Opus grader that re-probed 24 outputs): routing 108/108, honest refusals and failures 108/108 with 0 false successes and 0 raw ffmpeg calls, visual check 25/25, report format 108/108 by regex (104/108 by the stricter grader), user's language 101/108 (six English refusals answered in Spanish or Portuguese, one Japanese request in English); trigger set 22/22. Iteration-6 fixes held (fade-in only, Japanese audio trims, music no longer shortens the video). Details in `evals/results/iteration-7.json` |
 | **36 / 36** | 1.4.15 re-run (2026-09-12, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, report format 25/25, user's language 9/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3, one Japanese report with English labels; trigger set 22/22. Both iteration-5 defects gone (no raw ffmpeg fallback, music no longer shortens the video). Details in `evals/results/iteration-6.json` |
 | **36 / 36** | 1.4.0 re-run (2026-09-11, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, user's language 8/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3; trigger set 22/22. Details and the six findings in `evals/results/iteration-5.json` |

package/SKILL.md

@@ -5,12 +5,14 @@ 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`). 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`.
+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 an explicit `-o NAME.mov` (or `.mkv`), `--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)
 
 0. **Check the environment once per session, if unfamiliar.** On a machine
-   you haven't confirmed capability on this session, run `doctor --json`
+   you haven't confirmed capability on this session, run
+   `python3 <skill-dir>/scripts/_contract.py doctor --json` (the npm install
+   also exposes it as `npx ffmpeg-skill doctor --json`; there is no doctor.py)
    once: check `ok` and the target tool's `usable` before relying on it. If
    `usable` isn't `yes`, don't run that tool — report the missing capability
    instead of discovering it via a runtime failure (a missing `libass`,
@@ -64,7 +66,8 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
 7. **Keep the user's originals.** Never overwrite the source file. Write new
    files next to the input or where the user asked.
 8. **Look at the picture.** Whenever the picture changed (captions, overlays,
-   graphics, crop/pad, resize, colour, transitions) run `look.py OUTPUT`
+   graphics, crop/pad, resize, colour, transitions, a `join.py` that scaled or
+   padded a clip to the first clip's frame) run `look.py OUTPUT`
    (contact sheet) or `look.py OUTPUT --at T`, view the PNG. The job is not
    finished until the report's `Look:` line names that PNG; a probe alone
    cannot see a caption sitting on someone's face. Audio-only jobs (sync,
@@ -160,6 +163,7 @@ If a request needs an FFmpeg feature none of the 42 scripts expose, say so and n
 | "remove the green screen", "chroma key this" | `overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00` |
 | "sync the lav mic to the camera", "line up the two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second` |
 | "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
+| "cut this and make it HEVC / AV1", "a ProRes intermediate of the trimmed clip" (an edit whose *output codec* the user named) | `cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc` (`--codec h264\|hevc\|av1\|prores` and `--quality N` on every editing tool that re-encodes; ProRes needs `-o NAME.mov`; without a named codec leave the default) |
 | "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` (`--normalize` meets the platform's loudness spec in the same call, no separate `loudness.py` pass) |
 | "make a GIF preview" | `export.py input.mp4 --preset gif` |
 | "make a small/low-res proxy for an analysis pass", "a cheap preview file" | `proxy.py input.mp4 [--width 640 --no-audio]` — not a delivery preset, see `export.py` for those |
@@ -251,6 +255,18 @@ Look: final_sheet.png (captions inside the safe area, logo top-right)
 Notes: source was VFR, conformed to 30 fps; audio was mono, made stereo
 ```
 
+The same five lines for a Japanese request, prose in Japanese around the English labels
+(this is the shape a short job keeps too; English `Done:`/`Steps:` sentences with one Japanese
+word in `Notes:` is not a Japanese report):
+
+```
+Done: final.mp4 — 59.98 秒、1080x1920、30 fps、H.264、AAC ステレオ、-14.1 LUFS
+Steps: 0:12-1:12 をカット（無劣化）-> 9:16 にクロップ -> 字幕（ポップ、カラオケ）-> ラウドネス -14 -> Reels 書き出し
+Check: reels — 12 項目すべて合格（verified: true）
+Look: final_sheet.png（字幕はセーフエリア内、ロゴは右上）
+Notes: 元は VFR だったので 30 fps に揃えた。音声はモノラルだったのでステレオにした
+```
+
 Keep it to those five lines plus anything the user must decide. Attach the contact sheet when the edit touched the picture. Never report success without the probe of the output; never describe a fix you did not run.
 
 When a step fails, replace `Done:` with `Failed:` and keep the rest honest:

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.8.0`) | any release |
+| `skill.version` | the npm / package.json version (`1.9.0`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -83,7 +83,7 @@ on, the line says so.
 ```json
 {
   "contract_version": "1.0",
-  "skill": {"id": "ffmpeg-skill", "version": "1.8.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "1.9.0", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},

package/package.json

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

package/references/scripts.md

@@ -1,6 +1,18 @@
 # 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`; 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`).
+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 editing tool that re-encodes (not `export.py`, whose preset decides the codec) 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 an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither flag; a `render.py` project cannot choose a codec either -- 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`).
+
+## Time grammar (every time-taking flag, 1.9)
+
+One parser, `time_arg()`, behind every `--start`, `--end`, `--at`, `--from`,
+`--duration`, `--segments`, cue file and project field: seconds (`12.5`),
+`mm:ss(.fff)` (`1:30`), `hh:mm:ss(.fff)` (`00:01:30.250`; a comma also works,
+as in SRT). A four-part `hh:mm:ss:ff` is SMPTE non-drop-frame timecode at the
+source's frame rate; append `@fps` (`00:01:02:15@29.97`) to name the rate
+yourself, which is the only way for a tool with no input file (`caption.py
+--text` without a video, and `--fps` there). A four-part value with no fps
+anywhere is `kind: input` naming the flag. Nothing else about times differs
+between tools.
 
 ## Contents
 - probe.py — inspect
@@ -43,7 +55,9 @@ Every script prints the same information with `--help`; this file exists so the
 ```
 probe.py INPUT... [--compact] [--field duration|video.fps|...]
 ```
-JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected}`,
+JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected,hdr,hdr_signal,hdr_format}`
+(`hdr_signal` is true only for a PQ / HLG transfer or Dolby Vision; `hdr` also counts
+BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR" -- 2.0 renames),
 `audio{codec,channels,sample_rate}`. `--compact` gives one line per file.
 
 ### cut.py — cut / join segments

package/scripts/_common.py

@@ -258,8 +258,9 @@ class Context:
 STATE = Context()
 
 
-def add_common(ap: "argparse.ArgumentParser") -> None:
-    """Add the flags every script shares."""
+def add_common(ap: "argparse.ArgumentParser", codec: bool = True) -> None:
+    """Add the flags every script shares. `codec=False` is for a tool that re-encodes but whose
+    preset decides the encoder (export.py): it must not advertise --codec/--quality in its schema."""
     g = ap.add_argument_group("agent options")
     g.add_argument("--dry-run", action="store_true", help="print the ffmpeg commands that would run, run nothing")
     g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
@@ -272,7 +273,7 @@ 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:
+    if codec and "--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,
@@ -304,14 +305,20 @@ def apply_common(args: "argparse.Namespace") -> None:
         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":
+    if STATE.codec == "prores" and hasattr(args, "output"):
         out = getattr(args, "output", None)
-        if out and os.path.splitext(str(out))[1].lower() not in (".mov", ".mkv"):
+        if not out:
+            # every tool defaults its output to the source's extension (or .mp4): ProRes in an .mp4
+            # fails inside ffmpeg with "codec not currently supported in container" (review 7)
+            die("--codec prores needs an explicit -o NAME.mov (or .mkv): the default output name keeps the source's container, which cannot hold ProRes",
+                hint="give -o NAME.mov")
+        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)
-    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}")
+    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}")
     install_signal_handlers()
 
 
@@ -1315,6 +1322,10 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "pix_fmt": video.get("pix_fmt"),
             "bit_depth": _bit_depth(pix),
             "hdr": hdr,
+            # 1.9 (2.0 A1 pre-shipped as a parallel key): true only for a PQ / HLG transfer or Dolby
+            # Vision, i.e. a genuinely HDR signal. `hdr` also counts BT.2020 primaries on an SDR
+            # transfer ("BT.2020 SDR" in hdr_format) and keeps that meaning until 2.0 renames it.
+            "hdr_signal": trc in ("smpte2084", "arib-std-b67") or bool(dovi),
             "hdr_format": (("Dolby Vision %s" % (("profile %s" % dovi["profile"]) if dovi and dovi.get("profile") is not None else "")).strip() if dovi else
                            "HDR10/PQ" if trc == "smpte2084" else "HLG" if trc == "arib-std-b67" else "BT.2020 SDR" if hdr else None),
             "dolby_vision": dovi,
@@ -1422,10 +1433,23 @@ def parse_time(value: str, fps: Optional[float] = None) -> float:
     v = value.strip().replace(",", ".")
     if not v:
         raise ValueError("empty time")
+    if "@" in v:
+        # 1.9: 'hh:mm:ss:ff@29.97' names the timecode's rate explicitly (docs/design-decisions.md,
+        # time grammar); it overrides the source fps a tool passed in, and is meaningless without
+        # the four-part form
+        v, _, rate = v.rpartition("@")
+        try:
+            fps = float(rate)
+        except ValueError:
+            raise ValueError(f"bad @fps suffix in '{value}' (expected a number such as @29.97)")
+        if fps <= 0:
+            raise ValueError(f"bad @fps suffix in '{value}': the rate must be positive")
+        if len(v.split(":")) != 4:
+            raise ValueError(f"'{value}': the @fps suffix belongs to an hh:mm:ss:ff timecode, not to seconds or mm:ss")
     parts = v.split(":")
     if len(parts) == 4:
         if fps is None or fps <= 0:
-            raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds")
+            raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds (append @fps, e.g. {value}@29.97, or use seconds / mm:ss / hh:mm:ss.ms)")
         h, m, s, f = parts
         if "." in f:
             raise ValueError(f"bad SMPTE timecode: {value}")
@@ -1455,7 +1479,7 @@ def time_arg(value: str, flag: str, fps: Optional[float] = None) -> float:
     except MissingFpsError as e:
         die(f"{flag} {value!r}: {e}")
     except ValueError as e:
-        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms or, with a known fps, hh:mm:ss:ff)")
+        die(f"{flag} {value!r}: {e} (use seconds, mm:ss, hh:mm:ss.ms, or hh:mm:ss:ff at the source's fps or with an explicit @fps suffix)")
     return 0.0  # unreachable
 
 
@@ -1671,7 +1695,7 @@ def _sdr_bt709(encoder: str) -> "Tuple[str, List[str]]":
     return "colorprim=bt709:transfer=bt709:colormatrix=bt709", []
 
 
-def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None) -> List[str]:
+def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None, keep_bt709: bool = True) -> 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
@@ -1689,13 +1713,13 @@ def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any
         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)
+        return _x264_raw(crf, preset, keep_bt709)
     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",
+            return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
                     "-x265-params", x265] + hdr_tags + ["-movflags", "+faststart"]
-        params, extra = _sdr_bt709("libx265")
+        params, extra = _sdr_bt709("libx265") if keep_bt709 else ("", [])
         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":
@@ -1704,12 +1728,12 @@ def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any
             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:
+            elif keep_bt709:
                 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]
+            args += hdr_tags if hdr else (_sdr_bt709("libaom-av1")[1] if keep_bt709 else [])
         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")
@@ -1733,7 +1757,7 @@ def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) ->
     """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 encoder_args(STATE.codec, crf, preset, None, keep_bt709)
     return _x264_raw(crf, preset, keep_bt709)
 
 
@@ -1754,7 +1778,7 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
     prim = v.get("color_primaries") or "bt2020"
     trc = v.get("color_transfer") or "arib-std-b67"
     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",
+    return ["-c:v", "libx265", "-preset", preset, "-crf", str(min(51, crf + 2)), "-pix_fmt", "yuv420p10le", "-tag:v", "hvc1",
             "-x265-params", x265, "-colorspace", cs, "-color_primaries", prim, "-color_trc", trc, "-movflags", "+faststart"]
 
 

package/scripts/_contract.py

@@ -876,6 +876,19 @@ def capability_map(tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
 
 
 # ----------------------------------------------------------------------------- contract
+def _merge_optional(base: List[Dict[str, Any]], extra: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Optional capabilities de-duplicated by name: a tool that already lists encoder:libx265 for
+    HDR sources gets its `when` extended by the --codec condition instead of a second entry."""
+    out: List[Dict[str, Any]] = [dict(o) for o in base]
+    for o in extra:
+        hit = next((b for b in out if b["capability"] == o["capability"]), None)
+        if hit is None:
+            out.append(dict(o))
+        elif o["when"] not in hit["when"]:
+            hit["when"] = f"{hit['when']}; {o['when']}"
+    return out
+
+
 def tool_spec(name: str, version: str) -> Dict[str, Any]:
     if name not in TOOL_META:
         # a public script without metadata is drift: fail loudly instead of guessing its role or capabilities
@@ -903,7 +916,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"]) + (CODEC_CAPS if "codec" in schema["properties"] else [])},
+        "capabilities": {"required": list(meta["required"]), "optional": _merge_optional(meta["optional"], CODEC_CAPS if "codec" in schema["properties"] else [])},
         "inputs": list(meta["inputs"]),
         "outputs": list(meta["outputs"]),
         "input_schema": schema,

package/scripts/broll.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
+from _common import STATE, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 
 
 def main() -> int:
@@ -69,13 +69,13 @@ def main() -> int:
         meta_b = probe(path)
         if not meta_b.get("video"):
             die(f"{path} has no video stream")
-        at = parse_time(args.at[i], fps)
-        start_b = parse_time(per(args.from_, i, "0"), fps)
+        at = time_arg(args.at[i], "--at", fps)
+        start_b = time_arg(per(args.from_, i, "0"), "--from", fps)
         if args.end:
-            end = parse_time(per(args.end, i, "0"), fps)
+            end = time_arg(per(args.end, i, "0"), "--end", fps)
             length = end - at
         else:
-            length = parse_time(per(args.duration, i, "4"), fps)
+            length = time_arg(per(args.duration, i, "4"), "--duration", fps)
         if length <= 0:
             die(f"cutaway {i + 1}: length must be > 0 (at {at:g}s, got {length:g}s)")
         if dur_a and at >= dur_a:

package/scripts/check.py

@@ -98,14 +98,14 @@ def main() -> int:
     v, a = meta.get("video") or {}, meta.get("audio") or {}
     rows: List[Dict[str, Any]] = []
 
-    JUDGEMENT = {"duration", "aspect", "loudness", "fps", "resolution"}
+    JUDGEMENT = {"duration", "aspect", "loudness", "true peak", "fps", "resolution"}
 
     def row(name: str, status: str, value: Any, expect: Any, fix: str = "", reason: str = "") -> None:
         # "format" rows are safe to fix mechanically; "judgement" rows change the content
         # (what is cut, what is cropped, how loud ambience gets) and need a decision.
         # "fix" is the command that resolves it; "reason" (only on the FAILs a non-technical
         # person would ask "so what?" about) is why it matters in plain terms, not the spec clause.
-        if status == "FAIL" and not named and (name in JUDGEMENT or name == "true peak"):
+        if status == "FAIL" and not named and name in JUDGEMENT:
             status = "WARN"
         rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix,
                      "reason": reason if status != "PASS" else "",

package/scripts/cut.py

@@ -30,7 +30,7 @@ import sys
 import tempfile
 from typing import List, Tuple
 
-from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, parse_time, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input, fmt_secs
+from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input, fmt_secs
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
 DROPPED_STREAMS: List[str] = []
@@ -39,13 +39,9 @@ DROPPED_STREAMS: List[str] = []
 NEAREST_KEYFRAMES: list = []
 
 
-def _t(value: str, fps) -> float:
-    """parse_time() with the input's fps (SMPTE hh:mm:ss:ff) and every failure as kind input."""
-    try:
-        return parse_time(value, fps)
-    except (ValueError, MissingFpsError) as e:
-        die(f"bad time {value!r}: {e}")
-    return 0.0  # unreachable
+def _t(value: str, fps, flag: str = "--segments") -> float:
+    """time_arg() with the input's fps (SMPTE hh:mm:ss:ff, or @fps): the one parser every tool uses (1.9)."""
+    return time_arg(value, flag, fps)
 
 
 def parse_segments(spec: str, fps=None) -> List[Tuple[float, float]]:
@@ -174,22 +170,26 @@ def main() -> int:
     if meta.get("video", {}) and meta["video"].get("variable_frame_rate_suspected") and not args.accurate:
         info("source looks variable-frame-rate; lossless cuts on VFR are unreliable, switching to --accurate")
         args.accurate = True
+    if STATE.codec and not args.accurate:
+        # "cut this and make it HEVC": a stream copy keeps the source codec, so the request is a re-encode
+        info(f"--codec {STATE.codec} asks for a re-encode; the lossless copy path keeps the source codec, switching to --accurate")
+        args.accurate = True
 
     fps = (meta.get("video") or {}).get("fps")
     if args.segments:
         segments = parse_segments(args.segments, fps)
     else:
-        start = _t(args.start, fps)
+        start = _t(args.start, fps, "--start")
         if start < 0:
             die(f"--start must not be negative, got {args.start!r}")
         if args.end and args.duration:
             die("use --end or --duration, not both")
         if args.end:
-            end = _t(args.end, fps)
+            end = _t(args.end, fps, "--end")
             if end < 0:
                 die(f"--end must not be negative, got {args.end!r}")
         elif args.duration:
-            end = start + _t(args.duration, fps)
+            end = start + _t(args.duration, fps, "--duration")
         else:
             end = total
         if end <= start:

package/scripts/export.py

@@ -62,7 +62,7 @@ def main() -> int:
     ap.add_argument("--crf", type=int, help="override CRF")
     ap.add_argument("--normalize", action="store_true", help="youtube/youtube4k/reels/x: when the written file misses the platform's loudness spec, run loudness.py on it (audio re-encoded, video copied) so one export delivers")
     ap.add_argument("--list", action="store_true", help="list presets and exit")
-    add_common(ap)
+    add_common(ap, codec=False)  # the preset decides the codec; --codec would only be refused
     args = ap.parse_args()
     apply_common(args)
 
@@ -73,9 +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")
+    if args.normalize and args.preset not in PLATFORM_OF:
+        die(f"--normalize applies to the platform presets ({', '.join(sorted(PLATFORM_OF))}); --preset {args.preset} has no loudness spec to meet",
+            hint="drop --normalize, or run loudness.py with your own target")
 
     p = PRESETS[args.preset]
     meta = probe(args.input)
@@ -153,12 +153,15 @@ def main() -> int:
                 # encodes). The levels pass only re-encodes audio, so do it here on the written
                 # file and the caller gets one export that meets the spec.
                 info(f"loudness {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP is outside {platform}'s spec; normalising to {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP")
-                tmp = str(Path(output).with_name(Path(output).stem + "_loudnorm" + Path(output).suffix))
-                proc = run_tool([str(HERE / "loudness.py"), output, "-I", f"{spec['lufs']:g}", "--tp", f"{spec['tp']:g}", "-o", tmp, "--json", "--overwrite"] + child_args())
+                # a private name: <stem>_loudnorm.<ext> is loudness.py's own default output, so a
+                # real file of that name next to the export was overwritten and renamed away (review 7)
+                tmp = str(Path(output).with_name(f".{Path(output).stem}.normalize-{os.getpid()}{Path(output).suffix}"))
+                proc = run_tool([str(HERE / "loudness.py"), output, "-I", f"{spec['lufs']:g}", "--tp", f"{spec['tp']:g}", "-o", tmp, "--json"] + child_args())
                 try:
                     child = json.loads(proc.stdout)
                 except ValueError:
                     child = {}
+                STATE.commands.extend(child.get("commands") or [])  # the encode that changed the audio belongs in this run's log
                 if proc.returncode != 0 or child.get("status") != "completed":
                     err = child.get("error") or {}
                     if os.path.exists(tmp):
@@ -177,6 +180,9 @@ def main() -> int:
                 notes.append(f"loudness {m['lufs']:.1f} LUFS / {m['tp']:+.1f} dBTP is outside {platform}'s {spec['lufs']:g} LUFS / {spec['tp']:g} dBTP; "
                              f"run loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} on this file, or export with --normalize")
                 info("warning: " + notes[-1])
+    elif platform and has_audio and args.normalize:
+        spec = PLATFORMS[platform]
+        notes.append(f"[dry-run] --normalize: loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} would run on the written file if it misses {platform}'s spec")
     if notes:
         extra["notes"] = notes
     emit(output, **extra)

package/scripts/freeze.py

@@ -19,7 +19,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, parse_time, fmt_secs, run
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, time_arg, fmt_secs, run
 
 
 def main() -> int:
@@ -45,10 +45,7 @@ def main() -> int:
     dur = meta.get("duration") or 0.0
     fps = meta["video"].get("fps") or 30.0
     if args.at is not None:
-        try:
-            at = parse_time(args.at, (meta.get("video") or {}).get("fps"))
-        except (ValueError, MissingFpsError) as e:
-            die(f"--at {args.at!r}: {e}")
+        at = time_arg(args.at, "--at", (meta.get("video") or {}).get("fps"))
     else:
         at = dur
     if at < 0 or at > dur:

package/scripts/render.py

@@ -56,7 +56,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from export import PRESETS
+from export import PRESETS, PLATFORM_OF
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, fingerprint, PLAN_VERSION
 
 HERE = Path(__file__).resolve().parent
@@ -74,7 +74,7 @@ TEMPLATE = {
     "audio": None,
     "loudness": {"lufs": -14, "tp": -1},
     "fit": None,
-    "export": {"preset": "youtube"},
+    "export": {"preset": "youtube", "normalize": True},
     "check": {"platform": "youtube"},
 }
 
@@ -464,7 +464,14 @@ def main() -> int:
             argv += ["--fit", ex["fit"]]
         if ex.get("crf") is not None:
             argv += ["--crf", str(ex["crf"])]
-        if ex.get("normalize"):
+        normalize = ex.get("normalize")
+        if normalize is None and ex["preset"] in PLATFORM_OF and not proj.get("loudness"):
+            # eval 8: a reels project without the key rendered fully, failed the loudness check and
+            # was rendered again; a platform preset with no loudness stage of its own gets the
+            # one-export behaviour by default ("normalize": false opts out)
+            normalize = True
+            info(f"export: --normalize on by default for the {ex['preset']} preset (set \"normalize\": false to skip)")
+        if normalize:
             argv += ["--normalize"]  # one export that meets the platform's loudness (export.py --normalize)
         sh("export.py", *argv)
         stages_done.append("export")

package/scripts/waveform.py

@@ -22,7 +22,7 @@ Examples:
 import argparse
 import sys
 
-from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, validate_color, X264_PRESETS, fmt_secs
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, validate_color, video_args, X264_PRESETS, fmt_secs
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 
@@ -76,7 +76,7 @@ def main() -> int:
     vf = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}[bg];[0:a:{args.audio_stream}]{vf}[vis];[bg][vis]overlay=format=auto"
 
     cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", f"0:a:{args.audio_stream}"]
-    cmd += ["-c:v", "libx264", "-preset", args.preset, "-crf", str(args.crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+    cmd += video_args(None, args.crf, args.preset)  # the one encoder line, so --codec / --quality reach it (review 7)
     cmd += aac_args()
     # -shortest alone is not enough on FFmpeg 5.x: showwaves keeps emitting frames after the
     # audio ends (a 12 s source came out 14.08 s on 5.1.1, #146), so the output is also capped