ffmpeg-skill 3.8.13 → 3.8.15

package/README.md

@@ -331,6 +331,7 @@ rather than drifting silently. There is no separate `input_schema` file to forge
 ```bash
 npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py --json
 npx ffmpeg-skill contract --json --static   # without environment detection
+npx ffmpeg-skill contract --json --tool cut # one tool's entry under `tools` (repeatable): ~60 KB, not ~950 KB
 ```
 
 The contract is generated from the code that runs, not maintained beside it. For each of the 42 tools (`ffmpeg-skill/<name>`) it states:

package/SKILL.md

@@ -16,7 +16,7 @@ Shared flags (the rest, codec defaults and `--hw`: `references/flags.md`):
 
 Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`,
 `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`, `overlay`, `metadata`, `cut`, `render`,
-`batch`) may still run ffmpeg/ffprobe without writing artifacts; `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
+`batch`) may still run ffmpeg/ffprobe without writing artifacts; `verify` ignores the flag. Per tool: `contract --json --tool NAME` `dry_run`.
 
 Audio-only files work in the audio tools; picture tools refuse them (`references/workflow.md#audio-only-files`).
 

package/docs/contract.md

@@ -7,6 +7,11 @@ dry-run, input preservation and repeatability. It is the interface a planning ag
 consumes instead of reading `SKILL.md`, which stays written for a coding agent that
 follows the workflow by hand.
 
+The whole document is about 950 KB, almost all of it the 42 `tools` entries. `--tool NAME`
+(repeatable; `cut` or `cut.py`) keeps only the named tools under `tools`, in the order given,
+and every other key as it is: about 55 to 85 KB for one tool. An unknown name is refused (exit
+2) with the list of tools, and `doctor` does not take the flag.
+
 The contract is derived from the code that runs, not maintained beside it:
 
 - the tool list is every script in `scripts/` that does not start with `_`;
@@ -21,7 +26,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.13`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.15`) | 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`
@@ -149,7 +154,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.8.13", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.15", "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.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -951,7 +956,7 @@ A refusal also carries `error.reason`, a stable snake_case code for *why*
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
 `output_container_codecs` (a `.webm` output for an H.264/HEVC or AAC encode, which WebM cannot hold),
 `media_path_is_url` (`subfile,...:` included), `media_path_is_playlist` (an HLS, DASH, IMF or ffconcat playlist given as media, DASH and IMF told by content whatever the file is called), `media_path_has_line_break` (a path with a line break, which a concat list cannot hold),
-`output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
+`output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_extension_missing` (a media output with no file extension, which leaves ffmpeg no container to choose), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
 `render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and
 `encoder_list_unreadable`, and `--transcribe`'s `asr_engine_missing`, `no_speech`, `engine_failed`
 and `english_only`), and `error.details`, the facts the message is written from, so a

package/mcp/server.py

@@ -18,7 +18,6 @@ Claude Desktop / Claude Code config example:
 """
 import json
 import os
-import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.13",
+  "version": "3.8.15",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "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": [
@@ -53,7 +53,10 @@
     "docs/contract.md",
     "SKILL.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/__pycache__/**",
+    "!**/*.pyc",
+    "!**/*.pyo"
   ],
   "scripts": {
     "test": "python3 tests/run_parallel.py && python3 tests/test_contract.py",

package/references/flags.md

@@ -5,7 +5,7 @@ The long form of SKILL.md's Quick start. `--help` on a script is still its full
 
 ## Running the scripts
 
-Scripts live in `scripts/` next to SKILL.md; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. SKILL.md is enough to do a job: SKILL.md's request table routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as SKILL.md; open one only for a question you have: `references/scripts.md` (most flags; `--help` lists all), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end of SKILL.md). MCP: `tools/list` shows only the core 12 by default; the other 30 (per SKILL.md's request table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
+Scripts live in `scripts/` next to SKILL.md; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. SKILL.md is enough to do a job: SKILL.md's request table routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as SKILL.md; open one only for a question you have: `references/scripts.md` (most flags; `--help` lists all), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end of SKILL.md). MCP: `tools/list` shows only the core 12 by default; the other 30 (per SKILL.md's request table) stay callable by name via `tools/call`, described by `contract --json --tool NAME`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
 
 ## Shared flags
 
@@ -13,4 +13,4 @@ Shared flags (every script accepts them; the exceptions are named): `--dry-run`
 
 ## What `--dry-run` runs
 
-Writing tools run no ffmpeg under `--dry-run` (ffprobe still reads an input that exists); the measuring tools (`probe` with `--analyze`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`; `overlay` for a multi-line `--text` on FFmpeg 8.0-8.1.0; `metadata` with `--auto-chapters`; `cut` with `--snap beats`) still run their ffmpeg measurements, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`), and `render` and `batch` run each stage or step as its own dry run; `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
+Writing tools run no ffmpeg under `--dry-run` (ffprobe still reads an input that exists); the measuring tools (`probe` with `--analyze`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`; `overlay` for a multi-line `--text` on FFmpeg 8.0-8.1.0; `metadata` with `--auto-chapters`; `cut` with `--snap beats`) still run their ffmpeg measurements, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`), and `render` and `batch` run each stage or step as its own dry run; `verify` ignores the flag. Per tool: `contract --json --tool NAME` `dry_run`.

package/references/scripts.md

@@ -131,7 +131,10 @@ JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation
 (`hdr`, and `hdr_signal` equal to it, is true only for a PQ / HLG transfer or Dolby Vision -- since 2.0;
 `bt2020_or_hdr` also counts BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR"),
 `audio{codec,channels,sample_rate,start_time}` (`start_time`: where the stream starts on the file's
-own clock, `null` when unknown). `--compact` gives one line per file.
+own clock, `null` when unknown). `--compact` gives one line per file. `--field` prints one line
+per file: a string as itself and any other value as JSON (`true`, `{"codec": ...}`), an empty
+line for a field that is not there; with `--json` every line is JSON (a string quoted, a
+missing field `null`).
 
 ### cut.py — cut / join segments
 ```
@@ -338,7 +341,7 @@ the rectangle for you. Use this when the rectangle is already known (a
 face-detection box, a saved crop, a hand-picked region). The rectangle must
 lie entirely inside the source frame (after accounting for display rotation);
 `--width`/`--height` must be even (4:2:0 chroma) and are refused, never
-rounded, if they aren't.
+rounded, if they aren't; an odd `--x`/`--y` is taken as given.
 
 ### cropdetect.py — measure black bars, report the crop rectangle
 ```
@@ -429,7 +432,9 @@ Wraps FFmpeg's `v360` filter to bake out an ordinary flat clip pointed at a
 fixed direction — the same "look this way" operation a VR headset or a 360
 player's viewport does. `--yaw`/`--pitch`/`--roll` aim the camera (each
 -180..180, default 0); `--h-fov`/`--v-fov` set how wide the view is (each
-1..170, default 90/60). `--input-projection` must match the source's own
+1..170; `--h-fov` defaults to 90, and without `--v-fov` the vertical view is the
+one that keeps the output's pixels square, 58.7 at 90 and 1920x1080; a pair that
+is not square-pixel is drawn as given and said in `notes`). `--input-projection` must match the source's own
 projection (default `equirect`, the most common capture/export format) —
 this tool cannot detect it from the pixels, so a wrong value produces a
 distorted or garbled output, not an error. There is no subject detection or
@@ -502,7 +507,9 @@ a temporary transforms file (deleted after the run), pass 2 smooths and
 re-renders. `--shakiness` (default 5) trades analysis time for how much
 motion it looks for; `--smoothing` (default 15) is how many neighbouring
 frames the camera path is averaged over; `--zoom` crops in slightly to hide
-the black edges stabilizing can introduce. Needs an ffmpeg built with
+the black edges stabilizing can introduce, and is the only zoom applied (0, the
+default, keeps the original framing and lets the edges show: vidstab's own
+"optimal zoom" is off). Needs an ffmpeg built with
 `--enable-libvidstab`; `doctor` reports this tool `usable: no` when that's
 missing (a plain Homebrew ffmpeg build, for example) rather than failing at
 run time.
@@ -1669,14 +1676,17 @@ Each step runs with `--json`, and a failed one keeps its tool's own `kind`,
 completed one carries the tool's `verified`. Steps that do not apply are listed
 under the file's `skipped` (`quick`, `no_video`, `no_audio`, `not_hdr`,
 `not_multichannel`, `input_unreadable`) and as SKIP rows in the report.
+`--overwrite` and `--fast` given to verify.py reach every step, so a rerun into the same
+`--out` replaces the earlier outputs. The outputs are kept in `--out`, or with `--keep` alone
+in a new folder; either is the result's `out_dir` (`null` when they were deleted).
 Run this first when a user hands over footage from a device you have not
 seen before, and fix or report what fails.
 
 ### look.py — see the result
 ```
-look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes
+look.py INPUT [--tiles 4x3] [--width 1280] [-o sheet.png]         # contact sheet with timecodes (-o basename -> basename_sheet.png)
 look.py INPUT --at 2.5 [--at 7] [-o basename]                     # single frames -> basename_2.500s.png
-look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame
+look.py BEFORE --compare AFTER --at 4 [-o cmp.png]                # side-by-side frame (-o basename -> basename_vs_AFTER_0_4.000s.png)
 look.py INPUT --safe tiktok [--at 3]                              # shade what the app's UI covers
 look.py INPUT --guides title,action,4:3 [--at 3]                  # broadcast safe-area outlines
 ```
@@ -2370,7 +2380,8 @@ neither.
 proxy.py INPUT [--width W | --scale F] [--quality N] [--fps N] [--no-audio] [-o OUT]
 ```
 Not a delivery preset: resizes to `--width` (default 640) or by `--scale`
-factor, re-encodes at a proxy-grade `--quality` (default 30) with the fastest
+factor, never wider than the source and never under 2 px (a `notes` line says
+when either caps the width asked), re-encodes at a proxy-grade `--quality` (default 30) with the fastest
 x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;
 run `color.py --to-sdr` first if SDR is wanted) and keeps a subtitle/data
 track when the container can hold it (`dropped_non_av_streams`). Only executes the spec

package/scripts/_common/asr.py

@@ -1098,7 +1098,7 @@ def transcribe_words_result(video: str, language: "Optional[str]" = None, model:
     _shutil = SafeShutil(_shutil)  # look engines up and launch them by full path, never from the working directory
     import subprocess as _subprocess
     import tempfile as _tempfile
-    from _common import require_tool, run_analysis, STATE
+    from _common import require_tool, STATE
     ffmpeg = require_tool("ffmpeg")
     wanted = requested_engine(engine)
     language = engine_language(language)

package/scripts/_common/color.py

@@ -395,8 +395,13 @@ def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float = 1000.0, desat: floa
     prim = v.get("color_primaries") or "bt2020"
     space = v.get("color_space") or "bt2020nc"
     source_peak = HLG_PEAK_NITS if trc == "arib-std-b67" else peak
-    # zscale needs explicit input tags when the file lacks them
-    chain: List[str] = [
+    # zscale needs explicit input tags when the file lacks them, and on 6.1 its `pin` does not
+    # reach a frame whose own primaries are unspecified ("no path between colorspaces", kind
+    # ffmpeg: --to-sdr --force on an untagged file failed through 3.8.8), so a frame missing a tag
+    # is labelled with what the chain reads it as first
+    missing = not (v.get("color_transfer") and v.get("color_primaries") and v.get("color_space"))
+    label = [f"setparams=color_primaries={prim}:color_trc={trc}:colorspace={space}"] if missing else []
+    chain: List[str] = label + [
         f"zscale=tin={trc}:pin={prim}:min={space}:rin={v.get('color_range') or 'tv'}:t=linear"
         f":npl={TONEMAP_REFERENCE_NITS:g}",
         "format=gbrpf32le",

package/scripts/_common/decision.py

@@ -695,6 +695,16 @@ def _vt_bt709(codec: str) -> List[str]:
     return ["-bsf:v", f"{codec}_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1"]
 
 
+def source_transfer(v: Dict[str, Any]) -> str:
+    """The transfer a 10-bit re-encode of a BT.2020 / HDR source is tagged with: the source's own
+    tag, or, when it has none, what probe() read it as. BT.2020 primaries with no transfer tag are
+    `hdr_format` "BT.2020 SDR" (not an HDR signal), so they are tagged bt2020-10, the SDR curve
+    BT.2020 defines; through 3.8.8 every such re-encode came out tagged HLG (audit A153). An
+    HDR signal with no transfer tag (Dolby Vision whose base layer is untagged) keeps the HLG
+    default it always had."""
+    return v.get("color_transfer") or ("arib-std-b67" if v.get("hdr_signal") else "bt2020-10")
+
+
 def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: bool) -> Optional[List[str]]:
     """VideoToolbox encoder options for `codec`, or None (with a note in STATE.hw_notes) when the
     request stays on the CPU: no VideoToolbox encoder for the codec, this machine cannot, or the
@@ -716,7 +726,7 @@ def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: b
     v = (meta or {}).get("video") or {}
     hdr = bool(v.get("bt2020_or_hdr"))
     hdr_tags = ["-colorspace", v.get("color_space") or "bt2020nc", "-color_primaries", v.get("color_primaries") or "bt2020",
-                "-color_trc", v.get("color_transfer") or "arib-std-b67"]
+                "-color_trc", source_transfer(v)]
     if codec == "prores":
         return ["-c:v", name, "-profile:v", "hq", "-pix_fmt", "p210le"] + (hdr_tags if hdr else [])
     # The HDR curve was fitted on the Main10 HEVC line; an 8-bit H.264 line (an export preset on
@@ -847,7 +857,7 @@ def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str
     hdr = bool(v.get("bt2020_or_hdr"))
     cs = v.get("color_space") or "bt2020nc"
     prim = v.get("color_primaries") or "bt2020"
-    trc = v.get("color_transfer") or "arib-std-b67"
+    trc = source_transfer(v)
     hdr_tags = ["-colorspace", cs, "-color_primaries", prim, "-color_trc", trc]
     if codec == "h264":
         if hdr:
@@ -1152,7 +1162,7 @@ def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, prese
 def _x265_hdr_default(v: Dict[str, Any], crf: int, preset: str) -> List[str]:
     cs = v.get("color_space") or "bt2020nc"
     prim = v.get("color_primaries") or "bt2020"
-    trc = v.get("color_transfer") or "arib-std-b67"
+    trc = source_transfer(v)
     x265 = f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}:range=limited:hdr10-opt=1{hdr10_x265_params(v)}" if trc == "smpte2084" else f"log-level=error:colorprim={prim}:transfer={trc}:colormatrix={cs}"
     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/_common/probe.py

@@ -10,6 +10,8 @@ import math
 import os
 import re
 import statistics
+import sys
+from array import array
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, warn
@@ -70,15 +72,13 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
         if check:
             die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr.decode(errors="replace")))
         return []
-    import array
-    import sys
     data, proc = proc.stdout, None
-    pcm = array.array("h")
+    pcm = array("h")
     pcm.frombytes(memoryview(data)[: len(data) // 2 * 2])
     del data
     if sys.byteorder == "big":
         pcm.byteswap()  # s16le on the pipe
-    return array.array("f", (v / 32768.0 for v in pcm))
+    return array("f", (v / 32768.0 for v in pcm))
 
 
 def rms_envelope(samples: Sequence[float], step: int, *, full_blocks_only: bool = False, remove_mean: bool = False) -> List[float]:

package/scripts/_common/runner.py

@@ -511,6 +511,11 @@ def apply_common(args: "argparse.Namespace") -> None:
     # --json-brief is a shorter --json, not a second output mode: it implies it, so a caller that
     # passes only --json-brief still gets a JSON document (and --json --json-brief is the brief one).
     STATE.json = bool(getattr(args, "json", False)) or STATE.json_brief
+    if hasattr(args, "json"):
+        # and a tool that branches on args.json reads the same mode: through 3.8.13, probe --field,
+        # check, cropdetect, silence --list, report and verify printed text (or a bare document,
+        # or a document and then a path) under --json-brief alone (review of #521)
+        args.json = STATE.json
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
     STATE.overwrite = bool(getattr(args, "overwrite", False))
@@ -991,7 +996,7 @@ def _refuse_output_is_input(output: str, inp: str, real: str, why: str) -> None:
            **details)
 
 
-def refuse_output_is_input(output: str, *inputs: str) -> None:
+def refuse_output_is_input(output: str, *inputs: str, why: str = "the result would replace the source") -> None:
     """Tool-level twin of the run() guard, for tools whose final ffmpeg command does not name
     the user's input at all. `cut.py --segments` cuts each part into a temp dir and then concats
     a list file: the last command's only `-i` is that list, so `-o` equal to the input sailed
@@ -1009,7 +1014,7 @@ def refuse_output_is_input(output: str, *inputs: str) -> None:
         except OSError:
             continue
         if same:
-            _refuse_output_is_input(output, inp, out_real, "the result would replace the source")
+            _refuse_output_is_input(output, inp, out_real, why)
 
 
 def _check_output_path(cmd: Sequence[str]) -> None:
@@ -1040,6 +1045,24 @@ def _check_output_path(cmd: Sequence[str]) -> None:
         refuse("input", "output_dir_not_writable", f"output directory {parent!r} is not writable", output=output, directory=parent)
 
 
+def _check_output_extension(cmd: Sequence[str]) -> None:
+    """An ffmpeg output with no file extension and no `-f` after its last input leaves the muxer
+    nothing to choose a container by: refused as `kind: input` before anything runs, dry runs
+    included. Through 3.8.8 every tool that writes media handed it on and failed as `kind: ffmpeg`
+    ("Unable to choose an output format", audit A159's sweep). Only the ffmpeg commands run()
+    executes are checked: a sidecar (a report, an SRT) is a plain file and needs no extension,
+    and look.py takes an -o without an image extension as a stem (docs/design-decisions.md)."""
+    output = cmd[-1]
+    if output == "-" or output.startswith("pipe:") or len(os.path.splitext(output)[1]) > 1:
+        return
+    last_input = max((i for i, tok in enumerate(cmd[:-1]) if tok == "-i"), default=-1)
+    if "-f" in cmd[last_input + 2:-1]:
+        return
+    refuse("input", "output_extension_missing",
+           f"output {output!r} has no file extension, so ffmpeg cannot tell which container to write; "
+           f"name it with one (for example {output + '.mp4'!r})", output=output)
+
+
 # What the WebM muxer takes (6.1: "Only VP8 or VP9 or AV1 video and Vorbis or Opus audio and
 # WebVTT subtitles are supported for WebM"), by the encoder a command names (#488).
 _WEBM_VIDEO_ENCODER_RE = re.compile(r"^(?:libvpx(?:-vp9)?|vp8|vp9|libaom-av1|libsvtav1|librav1e|av1|vp8_\w+|vp9_\w+|av1_\w+)$")
@@ -2017,6 +2040,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
         _refuse_url_media(cmd)
         _check_no_overwrite_input(cmd)
         _check_output_path(cmd)
+        _check_output_extension(cmd)
         _check_container_codecs(cmd)
         _check_build_components(cmd)
         _check_existing_output(cmd)
@@ -2615,7 +2639,6 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     with os.replace() under the lock instead of copied -- a checked `cut.py --segments` join was
     copied whole, about 2 s for 240 MB. A rename that fails (another filesystem) falls back to
     the copy."""
-    import shutil
     cmd = ["ffmpeg", dst]
     _check_output_path(cmd)
     _check_existing_output(cmd)

package/scripts/_contract.py

@@ -3,6 +3,7 @@
 
     python3 scripts/_contract.py --json              # the contract, with detected capabilities
     python3 scripts/_contract.py --json --static     # same, without environment detection
+    python3 scripts/_contract.py --json --tool cut   # only cut under `tools` (repeatable)
     python3 scripts/_contract.py doctor [--json]     # which required capabilities this machine has
     ffmpeg-skill contract --json                     # the same through the npm entry point
 
@@ -21,7 +22,6 @@ import argparse
 import functools
 import importlib.util
 import json
-import os
 import platform
 import re
 import shutil
@@ -442,6 +442,7 @@ ERROR_REASONS = {
     "output_looks_like_option": "the output starts with '-' (other than '-' for stdout), which ffmpeg would read as an option; ./name writes a file of that name; details: {output}",
     "media_path_is_url": "an input or output has a protocol prefix (tcp:, http://, file:, ...) that ffmpeg would open as a URL; the skill reads and writes local files only; details: {path, scheme}",
     "output_dir_missing": "the output's directory does not exist; details: {output, directory}",
+    "output_extension_missing": "a media output with no file extension (and no -f naming its format), so ffmpeg could not choose a container; refused before ffmpeg runs, dry runs included; details: {output}",
     "output_dir_not_writable": "the output's directory is not writable; details: {output, directory}",
     "output_container_codecs": "a .webm output whose command encodes video or sound WebM cannot hold (H.264/HEVC, AAC; WebM takes VP8/VP9/AV1 and Opus/Vorbis), refused before ffmpeg runs; details: {output, container, encoders}",
     "timemap_path_taken": "silence.py --timemap names the same file as -o, --edl or --plan; details: {timemap, flag, path}",
@@ -775,7 +776,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]},
                  "files": {"type": "array", "description": "one entry per file: {file, probe, steps, skipped}. A step is {step, ok, seconds, error (one line, for the table)}, plus the tool's verified when it completed, and on a failure its own kind, reason, message, details and exit_code (reason step_timeout or step_output_unparsed when the tool printed no failure document); skipped lists the steps that do not apply as {step, reason: quick|no_video|no_audio|not_hdr|not_multichannel|input_unreadable, message}"},
-                 "failed": {"type": "integer"}, "total": {"type": "integer"}}
+                 "failed": {"type": "integer"}, "total": {"type": "integer"},
+                 "out_dir": {"type": ["string", "null"], "description": "the folder the steps' outputs are in when they are kept: --out, or with --keep alone a new folder that outlives the run; null when they were written to a temporary folder and deleted"}}
     elif name == "batch":
         extra = {"results": {"type": "array", "description": "one row per input, every input (an interrupted batch included): ok (every step completed), verified (every step also verified what it wrote; false under --dry-run) and unverified ([{step, tool, failed}] naming the steps that did not); a failed row's error {step, tool, kind, message, code, reason, details, hint, exit_code} from the failing step's own document; diagnostics from its steps (tagged with step); cache_miss {reason: output_missing|output_changed|entry_unverifiable, ...} when a cache entry was not served; skipped \"timeout\" or \"interrupted\" for an item that never started and interrupted true for one stopped while running; under --watch, skipped \"settling\" (ok false, not cached) for a source that changed since the previous poll, or, first seen, was modified within one poll interval: it is processed on a later pass. A row whose recipe ran cut.py carries cut_reencoded (each cut.py call's reencoded) and cut_reencode_reasons (each reason those calls named, once per call)"},
                  "processed": {"type": "integer"}, "total": {"type": "integer"},
@@ -1039,11 +1041,6 @@ def _ff_listing(binary: str, flag: str) -> Dict[str, Any]:
     return {"names": names, "status": "parsed", "detail": f"{len(names)} entries"}
 
 
-def _ff_list(binary: str, flag: str) -> List[str]:
-    """Names from `ffmpeg -encoders` / `-filters` / `-bsfs` (empty list when ffmpeg is missing or unparsed)."""
-    return _ff_listing(binary, flag)["names"]
-
-
 # GPU-backed encoders are named `<codec>_<backend>` by every ffmpeg build (h264_nvenc,
 # hevc_videotoolbox, av1_qsv, h264_vaapi, hevc_amf, ...); recognised by the backend suffix so a
 # new codec in a future ffmpeg build needs no change here.
@@ -2179,7 +2176,19 @@ def main() -> int:
     ap.add_argument("command", nargs="?", choices=["contract", "doctor"], default="contract")
     ap.add_argument("--json", action="store_true", help="JSON on stdout (the contract is always JSON)")
     ap.add_argument("--static", action="store_true", help="omit environment detection (available / missing capabilities)")
+    ap.add_argument("--tool", action="append", metavar="NAME",
+                    help="only this tool's entry under `tools` (repeatable; `cut` or `cut.py`); every other key is "
+                         "unchanged. The whole contract is about 950 KB; with one tool, 55-85 KB")
     args = ap.parse_args()
+    wanted: List[str] = []
+    for name in args.tool or []:
+        name = name[:-3] if name.endswith(".py") else name
+        if name not in public_tools():
+            ap.error(f"--tool {name}: no such tool (one of: {', '.join(public_tools())})")
+        if name not in wanted:
+            wanted.append(name)
+    if wanted and args.command == "doctor":
+        ap.error("--tool selects from the contract; doctor --json lists every tool under `tools`")
     if args.command == "doctor":
         d = doctor()
         # On stderr in both modes, so `doctor --json`'s stdout stays one JSON document: an
@@ -2225,7 +2234,12 @@ def main() -> int:
         # 1: something required is missing; 2: nothing proven missing but a required capability is unknown
         # an unsupported Python/FFmpeg is a known failure, like a missing capability (not "unknown")
         return 1 if d["missing"] or d.get("unsupported") else 2
-    print(json.dumps(build(detect=not args.static), indent=2, sort_keys=True, ensure_ascii=False))
+    doc = build(detect=not args.static)
+    if wanted:
+        # in the order asked; `provides` and `capability_map` stay whole (a few KB): they map ids
+        # to tools across the skill, which one tool's entry does not change (#467 A220)
+        doc["tools"] = sorted((t for t in doc["tools"] if t["name"] in wanted), key=lambda t: wanted.index(t["name"]))
+    print(json.dumps(doc, indent=2, sort_keys=True, ensure_ascii=False))
     return 0
 
 

package/scripts/_platforms.py

@@ -230,11 +230,6 @@ ALIASES: Dict[str, str] = {"youtube-shorts": "shorts", "yt-shorts": "shorts", "y
 PLATFORM_CHOICES: List[str] = sorted({n for n in PLATFORMS if PLATFORMS[n]["check"] == n} | set(ALIASES))
 
 
-def has_frame(name: str) -> bool:
-    """True when this destination has a frame, and therefore a safe zone to place text inside."""
-    return bool(PLATFORMS.get(resolve(name) or "", {}).get("frame"))
-
-
 def spec_of(name: str) -> Dict[str, Any]:
     """check.py's compliance row values for a destination."""
     return dict(PLATFORMS[name]["spec"])

package/scripts/background.py

@@ -19,7 +19,7 @@ import sys
 
 from _common.alpha import add_alpha_args, check_alpha_args, finish_chain, report as alpha_report, video_line
 from _common.emit import note
-from _common import STATE,  add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, parse_time, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE,  add_common, apply_common, die, draws_chroma, emit, ffmpeg_base, info, probe, rgb_chain_to_bt709, run, validate_color, video_args, X264_PRESETS, time_arg, fmt_secs
 
 
 def gradient_source(w: int, h: int, fps: float, c0: str, c1: str, angle: float) -> str:

package/scripts/caption.py

@@ -37,17 +37,16 @@ import json
 import os
 import re
 import sys
-import unicodedata
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
                         resolve as resolve_platform)
-from _ass_overlay import (EMOJI_SENTINEL, emoji_placeholder, ass_escape, ass_escape_markup,
+from _ass_overlay import (EMOJI_SENTINEL, emoji_placeholder, ass_escape_markup,
                           strip_srt_markup, reinsert_srt_markup, carry_srt_markup, srt_alignment)
 from _common.emit import refuse  # noqa: E402
 from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
-from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, label_chain, layer_base_chain, load_brand, overlay_format, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
+from _common import require_filter, emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, NO_SPACE_SCRIPTS, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, drawn_chain, layer_base_chain, load_brand, overlay_format, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, X264_PRESETS, read_text_or_die, fmt_secs, refuse_existing_outputs, guard_sidecar
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for

package/scripts/check.py

@@ -53,7 +53,7 @@ from _common.probe import (CHANGE_FLOOR, CHANGE_GRID, change_mask_tiles, change_
 from _common.emit import file_identity, own_length
 from _common.probe import PROBED_AUDIO
 from _common.probe import display_size as shown_size, shorter_than_a_loudness_block
-from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
+from _common import STATE, add_common, apply_common, die, emit, probe, require_tool, run_analysis, dry_run_input_pending
 
 # The one delivery table (scripts/_platforms.py): check.py's rows, export.py's presets and the
 # render.py templates all read it, so a platform's loudness spec is stated once. Only the

package/scripts/color.py

@@ -581,7 +581,13 @@ def main() -> int:
         else:
             vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
             sdr_path = "tonemap"
-            sdr_note = f"tone-mapped {v.get('hdr_format') or 'untagged input as PQ (--force)'} to SDR BT.709 with {args.tonemap}"
+            # the note names what hdr_to_sdr_chain read the source as: its own tags, PQ / BT.2020
+            # only where a tag is missing. Through 3.8.8 any non-HDR file was called "untagged
+            # input as PQ", a BT.709-tagged one included, which the chain linearised as BT.709 (A161)
+            read_as = v.get("hdr_format") or (
+                f"a non-HDR input read as transfer {v.get('color_transfer') or 'smpte2084 (untagged, taken as PQ)'}, "
+                f"primaries {v.get('color_primaries') or 'bt2020 (untagged)'} (--force)")
+            sdr_note = f"tone-mapped {read_as} to SDR BT.709 with {args.tonemap}"
         info(f"note: {sdr_note}")
         sdr_extra = {"sdr_path": sdr_path, "notes": [sdr_note]}
         output = args.output or default_output(args.input, "sdr")

package/scripts/crop.py

@@ -12,7 +12,8 @@ The rectangle must lie entirely inside the source frame after accounting for
 any display rotation, and --width/--height must be even (required for 4:2:0
 chroma subsampling, the pixel format every encoder here uses) -- given values
 are validated and refused, never silently rounded, since a caller-specified
-rectangle should do exactly what was asked or fail loudly.
+rectangle should do exactly what was asked or fail loudly. An odd --x/--y is
+taken as given (the crop starts on that pixel), not moved to the chroma grid.
 
 Examples:
   python3 crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920
@@ -63,7 +64,7 @@ def main() -> int:
 
     output = args.output or default_output(args.input, "crop")
     # exact=1: without it crop rounds an odd --x/--y down to the chroma grid of a 4:2:0 frame,
-    # and the rectangle written was one pixel left of / above the one asked for (A170's sibling)
+    # and the rectangle written was one pixel left of / above the one asked for (A170's sibling, A157)
     vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}:exact=1", "setsar=1"]
     if square_pixels(meta["video"]):
         vf.insert(0, square_pixels(meta["video"]))

package/scripts/cropdetect.py

@@ -33,7 +33,7 @@ import sys
 from collections import Counter
 from typing import Dict, List, Optional, Tuple
 
-from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames, frame_flow
+from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames
 from _common.emit import note, warn
 from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note
 

package/scripts/cut.py

@@ -65,7 +65,7 @@ from _common.probe import PROBED_AUDIO, PROBED_VIDEO, TS_EXTS, probed_maps, seve
 from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import output_timecode_args
-from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_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, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
+from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_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, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
 DROPPED_STREAMS: List[str] = []

package/scripts/export.py

@@ -43,6 +43,7 @@ import re
 import os
 import sys
 import tempfile
+from fractions import Fraction
 from pathlib import Path
 from typing import Dict, List, Optional
 
@@ -51,7 +52,7 @@ from _common import STATE, run_analysis, add_common, apply_common, bt709_label_f
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import PROBED_AUDIO, PROBED_VIDEO, probed_maps, square_pixels, square_pixels_note
-from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
+from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, subtitle_codec_for
 from _common.emit import file_identity, input_length, own_length
 from check import SPECS as PLATFORMS, measure_loudness
 from _common.probe import SILENT_PEAK_DBFS, shorter_than_a_loudness_block
@@ -202,7 +203,8 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
         note(f"--hw: --preset {args.preset} stays on {p['video'][p['video'].index('-c:v') + 1]}: one ffmpeg run writes "
              "the fill and the key as a pair, and VideoToolbox's ProRes encoder is not used for it")
     fill_chain = ",".join(vf + (["premultiply=inplace=1"] if args.alpha_mode == "premultiplied" else []) + ["format=yuv422p10le"])
-    key_chain = ",".join(vf + ["alphaextract", "format=yuv422p10le"])
+    # Alpha uses full range even when the source picture is tagged limited range.
+    key_chain = ",".join(vf + ["alphaextract", "scale=in_range=pc:out_range=tv", "format=yuv422p10le"])
     tc = ((meta.get("timecode") or {}).get("value"))
     tc_args = ["-timecode", tc] if tc else []
     cmd = cmd + ["-filter_complex", f"[0:{PROBED_VIDEO}]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
@@ -442,6 +444,32 @@ SIZE_MIN_VIDEO_KBPS = 100   # below this the picture is not worth delivering; re
 SIZE_MAX_VIDEO_KBPS = 400_000  # 400 Mb/s: above any delivery line, and libx264 refuses far larger values
 
 
+def _platform_rate_args(preset: str, meta: Dict) -> List[str]:
+    """A platform preset that keeps the source's frame rate (the youtube family) conforms a source
+    faster than the platform's fps_max to the source rate divided by the smallest whole number that
+    brings it within the limit (120 -> 60, 119.88 -> 59.94, 100 -> 50), so every frame of the
+    output is one of the source's own. Through 3.8.8 a 120 fps source kept 120 fps and the
+    platform's own check FAILed the export (audit A115). [] when the preset has no limit or the
+    source is within it (cfr_args() then decides, as before)."""
+    platform = PLATFORM_OF.get(preset)
+    fps_max = (PLATFORMS.get(platform) or {}).get("fps_max") if platform else None
+    v = meta.get("video") or {}
+    src = v.get("fps")
+    if not fps_max or not src or src <= fps_max + 0.01:
+        return []
+    try:
+        exact = Fraction(v.get("avg_frame_rate") or "0")
+    except (ValueError, ZeroDivisionError):
+        exact = Fraction(0)
+    if not exact or abs(float(exact) - src) > 0.01:
+        exact = Fraction(src).limit_denominator(1001)
+    n = math.ceil(float(exact) / (fps_max + 0.01))
+    rate = exact / n
+    note(f"source is {src:g} fps, above {platform}'s limit of {fps_max:g}: exported at {float(rate):.6g} fps, "
+         f"one source frame in {n}")
+    return ["-fps_mode", "cfr", "-r", str(rate.numerator) if rate.denominator == 1 else f"{rate.numerator}/{rate.denominator}"]
+
+
 def size_video_args(args, video: List[str], p: Dict, meta: Dict, has_audio: bool) -> List[str]:
     """--max-mb: the preset's x264 line with its CRF replaced by the bitrate that fits the size,
     for a two-pass encode. Refused where that cannot be done honestly: another codec, --crf, --hw,
@@ -669,7 +697,7 @@ def main() -> int:
         # a stream copy can't be frame-rate-conformed or retagged without decoding it — that would
         # no longer be a copy, and would silently mislabel colour the agent never actually looked at
         if "-r" not in video:
-            cmd += cfr_args(meta)
+            cmd += _platform_rate_args(args.preset, meta) or cfr_args(meta)
         if tag_bt709 and not video[video.index("-c:v") + 1].endswith("_videotoolbox"):
             cmd += bt709_tag_args(video[video.index("-c:v") + 1])
         if not p.get("intermediate"):
@@ -767,7 +795,13 @@ def main() -> int:
                 # 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())
+                # under --max-mb the sound is re-encoded at the bitrate the size budget was built on
+                # (the preset's); loudness.py's own 192k, raised to 256k/320k on an overshoot, put
+                # the file over the limit it had been encoded to meet (through 3.8.8, audit A112)
+                pinned = (["--audio-bitrate", p["audio"][p["audio"].index("-b:a") + 1]]
+                          if args.max_mb is not None and "-b:a" in p["audio"] else [])
+                proc = run_tool([str(HERE / "loudness.py"), output, "-I", f"{spec['lufs']:g}", "--tp", f"{spec['tp']:g}", "-o", tmp, "--json"]
+                                + pinned + child_args())
                 try:
                     child = json.loads(proc.stdout)
                 except ValueError:

package/scripts/fit.py

@@ -34,14 +34,13 @@ Examples:
   python3 fit.py input.mp4 --flip h                              # mirror horizontally
 """
 import argparse
-import math
 import sys
 from fractions import Fraction
 from typing import List
 
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, length_output_t, stream_starts
 from _common.timeline import exact_rate, output_timecode_args
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, default_output, die, ffmpeg_base, info, probe, run, run_keeping_subtitles, validate_color, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
 from _common.emit import input_length
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 
@@ -227,7 +226,9 @@ def main() -> int:
                 # after it (a B-frame HEVC source) and lose the frames before it, so the first
                 # picture would not be the one the start timecode below names
                 m = min(SEEK_MARGIN, round(start, 3))
-                pre_input += ["-ss", f"{start - m:.3f}"]
+                # a trim from the start seeks nowhere: no -ss, so the timeline stays where it is and
+                # a subtitle/data track is kept below (`-ss 0.000` dropped it, A158)
+                pre_input += ["-ss", f"{start - m:.3f}"] if round(start, 3) > 0 else []
                 # without sound the -t only counts frames (picture_output_t). Not from the centre:
                 # there the output's clock starts at the seek, between two frames, and the encoder
                 # rounds each frame to its own tick

package/scripts/freeze.py

@@ -20,7 +20,7 @@ import argparse
 import sys
 
 from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, silence_filter, stream_starts, tpad_length
-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
+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, time_arg, fmt_secs, run
 from _common.emit import input_length
 
 

package/scripts/graphics.py

@@ -38,11 +38,11 @@ from _common.emoji import emoji_missing_asset_note, emoji_mono_on_colour_note
 from _common.drawtext import shaping_refusal
 from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
-                     ffmpeg_base, info, layer_base_chain, load_brand, overlay_format, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
+                     ffmpeg_base, info, layer_base_chain, load_brand, overlay_format, probe, rgb_chain_to_bt709, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
-                     EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
+                     EMOJI_ASSET_HINT, text_width_em, wrap_text, WRAP_MODES,
                      SAFE_WIDTH_FRACTION, drawtext_draws_newline_glyph, is_multiline, _DRAWTEXT_PENDING)
 from _common.emit import note, warn
 from _common.alpha import (add_alpha_args, audio_line, check_alpha_args, decoder_args_for, default_ext, finish_chain,
@@ -429,7 +429,6 @@ def main(force_route: Optional[str] = None) -> int:
         el["text"] = text
         elements.append(el)
 
-    extra_inputs: List[str] = []
     fc: List[str] = []  # filter_complex chains (used by templates that need animated boxes)
     if 0 < min(W, H) < 64:  # 0x0 is a dry-run probe of an intermediate that does not exist yet
         die(f"the frame is {W}x{H}; the templates are sized from it and need at least 64 px on the short side")

package/scripts/insert.py

@@ -28,7 +28,7 @@ import math
 import sys
 
 from _common import still_input_args  # noqa: E402
-from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note
 from _common.probe import display_size, square_pixels, square_pixels_note
 

package/scripts/look.py

@@ -19,7 +19,7 @@ from typing import List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common import still_input_args  # noqa: E402
-from _common import STATE, require_tool, add_common, apply_common, default_font_file, die, emit, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_analysis, time_arg
+from _common import STATE, require_tool, add_common, apply_common, default_font_file, die, emit, escape_drawtext, ffmpeg_base, info, probe, run, run_analysis, time_arg
 from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
@@ -30,6 +30,8 @@ from _common.emit import input_length  # noqa: E402
 # --guides: broadcast safe areas as outlines, in fractions of the frame (a tile as much as a frame).
 # Action and title safe are SMPTE ST 2046-1's 93 % and 90 % of a 16:9 picture; the 4:3 centre cut
 # is the 4:3 window of a 16:9 frame with SD's own 90 % action / 80 % title safe inside it.
+# the extensions an -o is taken verbatim with (one picture); any other -o is a stem
+IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp")
 GUIDES = {"action": 0.93, "title": 0.90}
 GUIDE_43 = {"action": 0.90, "title": 0.80}
 GUIDE_COLOURS = {"action": "yellow", "title": "cyan", "4:3": "white"}
@@ -319,7 +321,7 @@ def main() -> int:
         csq = (square_pixels(cmeta.get("video")) + ",") if square_pixels(cmeta.get("video")) else ""
         for idx, t in enumerate(args.at):
             sec = time_arg(t, "--at", meta["video"].get("fps") if meta.get("video") else None)
-            if args.output and len(args.at) == 1:
+            if args.output and len(args.at) == 1 and Path(args.output).suffix.lower() in IMAGE_EXTS:
                 out = args.output  # one frame, one named image file: the caller's -o is the contract
             else:
                 # several frames, or -o given as a stem/prefix: an occurrence index keeps every
@@ -352,7 +354,7 @@ def main() -> int:
             sec = time_arg(t, "--at", meta["video"].get("fps") if meta.get("video") else None)
             if dur and sec > dur:
                 die(f"--at {t} is beyond the duration ({dur:.2f}s)")
-            if args.output and len(args.at) == 1 and Path(args.output).suffix.lower() in (".png", ".jpg", ".jpeg", ".webp"):
+            if args.output and len(args.at) == 1 and Path(args.output).suffix.lower() in IMAGE_EXTS:
                 out = args.output  # one frame, one named image file: the caller's -o is the contract
             else:
                 # several frames, or -o given as a stem/prefix without an image extension
@@ -382,7 +384,10 @@ def main() -> int:
             info(f"only {frames_avail} frame(s) available; sheet reduced to {cols}x{rows}")
         step = dur / n
         tile_w = max(2, (args.width // cols) // 2 * 2)
-        out = args.output or os.path.join(outdir, f"{stem}_sheet.png")
+        # -o without an image extension is a stem here too (<stem>_sheet.png), as for --at and
+        # --compare: given verbatim, ffmpeg could not choose a muxer for it (kind ffmpeg, A159)
+        out = (args.output if args.output and Path(args.output).suffix.lower() in IMAGE_EXTS
+               else os.path.join(outdir, f"{(args.output and Path(args.output).stem) or stem}_sheet.png"))
         # sample at the middle of each slice so the first/last tiles are not black lead-in/out frames
         # with only a handful of frames a mid-slice seek skips past them all: start at 0 instead
         seek = 0.0 if frames_avail < 4 else step / 2

package/scripts/loop.py

@@ -32,7 +32,7 @@ import os
 import sys
 import tempfile
 
-from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, parse_time, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, concat_list_line, add_common, aac_args, apply_common, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, refuse_output_is_input, require_filter, require_tool, run, video_args, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import warn
 from _common.decision import HELD_FRAMES_WARN_BYTES, av_trim, held_frames_bytes, length_output_t, stream_starts
 from _common.probe import decode_gray_frames, decode_pcm_mono

package/scripts/loudness.py

@@ -114,11 +114,6 @@ def loudnorm_mode(stats: dict, lufs: float, tp: float, lra: float) -> str:
 
 def _normalize(args, meta: dict, stats: dict, lufs: float, tp_max: float, output: str) -> dict:
     """One normalised file at `lufs` / `tp_max`, measured after: the keys emit() takes for it."""
-    af = (
-        f"loudnorm=I={lufs}:TP={tp_max}:LRA={args.lra}"
-        f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
-        f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
-    )
     sr = args.sample_rate or meta["audio"].get("sample_rate") or 48000
     ext = os.path.splitext(output)[1].lower()
     bitrate_pinned = args.audio_bitrate is not None

package/scripts/multicam.py

@@ -32,7 +32,7 @@ import os
 import sys
 from typing import Dict, List, Optional, Tuple
 
-from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, x264_args, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
+from _common import guard_sidecar, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, default_output, die, emit, ffmpeg_base, info, time_arg, probe, run, X264_PRESETS, fmt_secs, decode_pcm_mono, rms_envelope, STATE
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.decision import av_trim, conform_output_t, conform_to_length, rebase_project_paths
 from _common.probe import display_size, square_pixels, square_pixels_note

package/scripts/overlay.py

@@ -35,7 +35,7 @@ from typing import Any, Dict, List, Optional
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import still_input_args  # noqa: E402
-from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
+from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, layer_base_chain, matrix_chain, overlay_format, range_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, X264_PRESETS, time_arg, fmt_secs
 from _common.emit import note, warn
 from _common.color import is_rgb
 from _common.decision import length_output_t, window_expr, windowed_overlay_x

package/scripts/probe.py

@@ -15,10 +15,11 @@ Examples:
 points a stream copy can start at, and where cut.py --smart's re-encode around a cut ends.
 """
 import argparse
+import json
 import math
 import sys
 
-from _common import add_common, analyze_levels, apply_common, die, keyframe_times, print_json, probe, time_arg
+from _common import STATE, add_common, analyze_levels, apply_common, die, keyframe_times, print_json, probe, time_arg
 
 
 def keyframe_candidates(result: dict, times: list, window: float) -> list:
@@ -87,7 +88,17 @@ def main() -> int:
             cur = r
             for key in args.field.split("."):
                 cur = cur.get(key) if isinstance(cur, dict) else None
-            print(cur if cur is not None else "")
+            # a string as itself; anything else as JSON (true, null, {"codec": ...}), not Python's
+            # repr (True, None, {'codec': ...}), which no caller can parse (through 3.8.8, A123).
+            # Under --json (or --json-brief, which implies it) a missing field is null and a string
+            # is quoted: every line is JSON. Without either a missing field is an empty line, as it
+            # always was, so `[ -z "$(probe.py f --field x)" ]` keeps working
+            if isinstance(cur, str) and not STATE.json:
+                print(cur)
+            elif cur is None and not STATE.json:
+                print("")
+            else:
+                print(json.dumps(cur, ensure_ascii=False))
         return 0
 
     if args.compact:

package/scripts/proxy.py

@@ -5,7 +5,8 @@ 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 --quality (default 30 - well above any
+--scale factor, never wider than the source (a proxy is not upscaled) and
+never under 2px, 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
@@ -65,7 +66,15 @@ def main() -> int:
         note(square_pixels_note(meta["video"]))
     has_audio = bool(meta.get("audio")) and not args.no_audio
 
-    out_w = even(sw * args.scale) if args.scale is not None else even(args.width)
+    # A proxy is never wider than its source, and never under 2 px: through 3.8.8 the default
+    # --width 640 upscaled a smaller source, and a --scale that rounded to 0 became scale=0, which
+    # ffmpeg reads as "the input's width" (a full-size proxy, audit A162)
+    asked = even(sw * args.scale) if args.scale is not None else even(args.width)
+    ceiling = max(2, sw - sw % 2) if sw else asked
+    out_w = max(2, min(asked, ceiling))
+    if out_w != asked:
+        note(f"proxy width {out_w}px, not {asked}px: "
+             + (f"the source is {sw}px wide and a proxy is not upscaled" if asked > ceiling else "2px is the smallest width"))
     output = args.output or default_output(args.input, "proxy")
 
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", (square + "," if square else "") + f"scale={out_w}:-2"]

package/scripts/redact.py

@@ -113,7 +113,11 @@ def main() -> int:
             # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
             # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
             radius = max(1, min(args.blur_strength, min(args.width, args.height) // 2 - 1))
-            chroma = max(1, min(radius // 2, min(args.width, args.height) // 4 - 1))
+            # at least 1 wherever the chroma plane can hold it: radius // 2 alone was 0 at
+            # --blur-strength 1, which left colour-only detail readable (review of #521). (FFmpeg
+            # 7.1 refuses a chroma radius of 1 on a 2 px chroma plane, a 4 px wide region; 6.1
+            # took it.) 0 is only a plane too small to blur: the luma still is
+            chroma = max(0, min(max(1, radius // 2), (min(args.width, args.height) // 2 - 1) // 2))
             region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
         else:
             region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"

package/scripts/sphere.py

@@ -6,7 +6,8 @@ turning an equirectangular (or other spherical-projection) source into an
 ordinary flat video pointed at a chosen direction -- the same "look this way"
 operation a VR headset or a 360 video player's viewport does, baked into a
 real file. --yaw/--pitch/--roll aim the camera; --h-fov/--v-fov set how wide
-the view is.
+the view is (without --v-fov, the vertical view is the one that keeps the
+output's pixels square).
 
 This tool does not decide WHERE to point the camera -- there is no subject
 detection or tracking here, only the typed rotation/FOV you give it (see this
@@ -29,9 +30,11 @@ Examples:
   python3 sphere.py gopro_max.mp4 --input-projection fisheye --yaw -45 --pitch 10 -o angle.mp4
 """
 import argparse
+import math
 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, fmt_secs
+from _common.emit import note
 
 # v360's own AVOption names for the input projections real 360 cameras/exports actually
 # produce (ffmpeg -h filter=v360 documents 24 total; this is the subset a caller is likely
@@ -59,7 +62,9 @@ def main() -> int:
     aim.add_argument("--roll", type=float, default=0.0, help="tilt/roll rotation in degrees, -180..180 (default 0)")
     fov = ap.add_argument_group("field of view")
     fov.add_argument("--h-fov", type=float, default=90.0, help="output horizontal field of view in degrees, 1..170 (default 90)")
-    fov.add_argument("--v-fov", type=float, default=60.0, help="output vertical field of view in degrees, 1..170 (default 60)")
+    fov.add_argument("--v-fov", type=float, default=None,
+                     help="output vertical field of view in degrees, 1..170 (default: the one that keeps pixels square at "
+                          "--h-fov and --width/--height, 58.7 at the defaults)")
     out = ap.add_argument_group("output frame")
     out.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
     out.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
@@ -81,12 +86,27 @@ def main() -> int:
         die(f"--roll must be -180..180, got {args.roll}")
     if not 1 <= args.h_fov <= 170:
         die(f"--h-fov must be 1..170, got {args.h_fov}")
-    if not 1 <= args.v_fov <= 170:
+    if args.v_fov is not None and not 1 <= args.v_fov <= 170:
         die(f"--v-fov must be 1..170, got {args.v_fov}")
     if args.width <= 0 or args.height <= 0:
         die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
     if args.width % 2 or args.height % 2:
         die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+    # A rectilinear view has square pixels when tan(v/2) / tan(h/2) = H / W. Through 3.8.8 the
+    # default was a fixed 60 degrees, which at 90 x 1920x1080 squashed the view 2.6 % vertically
+    # (audit A163); the vertical FOV now follows from the other three unless it is given.
+    square_v = math.degrees(2 * math.atan(math.tan(math.radians(args.h_fov) / 2) * args.height / args.width))
+    if args.v_fov is None:
+        if not 1 <= square_v <= 170:
+            die(f"--h-fov {args.h_fov:g} at {args.width}x{args.height} needs a vertical field of view of {square_v:.1f} "
+                "degrees for square pixels, outside 1..170", hint="give --v-fov, or a lower --h-fov")
+        args.v_fov = round(square_v, 4)
+    else:
+        stretch = math.tan(math.radians(args.v_fov) / 2) / math.tan(math.radians(square_v) / 2)
+        if abs(stretch - 1) > 0.005:
+            note(f"--h-fov {args.h_fov:g} / --v-fov {args.v_fov:g} at {args.width}x{args.height} is not square-pixel: the view is "
+                 f"{'squashed' if stretch > 1 else 'stretched'} {abs(stretch - 1) * 100:.1f} % vertically "
+                 f"(--v-fov {square_v:.2f} keeps it square; omit --v-fov to get it)")
 
     meta = probe(args.input)
     if not meta.get("video"):

package/scripts/stabilize.py

@@ -29,7 +29,7 @@ from pathlib import Path
 
 from _common.probe import PROBED_VIDEO
 from _common.runner import ffmpeg_failure_extra, default_selection_maps, require_filter
-from _common import STATE, add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, escape_filter_path, ffmpeg_base, info, probe, require_tool, run, video_args, X264_PRESETS, run_analysis, dry_run_input_pending, fmt_secs, record_fallback, EVEN_SCALE
 
 
 def main() -> int:
@@ -96,7 +96,10 @@ def main() -> int:
                 die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}", kind="ffmpeg", **ffmpeg_failure_extra(proc.stderr))
 
         crop_mode = {"keep": 0, "black": 1}[args.crop]
-        transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
+        # optzoom=0: the zoom is --zoom and nothing else. vidstab's default (optzoom=1) adds its own
+        # "optimal" zoom on top, so --zoom 0 did not keep the original framing and --crop black
+        # rarely had an edge to fill (through 3.8.8, audit A156)
+        transform_vf = f"{even}vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=0"
         if args.tripod:
             # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
             # camera path makes no sense once every frame is locked to one fixed reference.

package/scripts/sync.py

@@ -27,15 +27,13 @@ Examples:
   python3 sync.py cam.mp4 recorder.wav --fix-drift --replace-audio   # long takes: fix clock drift too
 """
 import argparse
-import cmath
-import json
 import math
 import os
 import sys
 from typing import Dict, List
 
 from _common.runner import fail_if_classified
-from _common import STATE, video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, x264_args, decode_pcm_mono, rms_envelope
+from _common import STATE, video_args, add_common, apply_common, emit, aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, run, decode_pcm_mono, rms_envelope
 from _common.emit import record_skip, warn
 from _common.decision import SEEK_MARGIN, frame_rate, grid_at_or_after, length_output_t, silence_filter, stream_starts
 from _common.timeline import output_timecode_args

package/scripts/verify.py

@@ -18,7 +18,6 @@ import argparse
 import contextlib
 import io
 import json
-import os
 import subprocess
 import sys
 import tempfile
@@ -26,10 +25,12 @@ import time
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from _common import STATE, add_common, apply_common, die, emit, guard_sidecar, info, probe
+from _common import STATE, add_common, apply_common, die, emit, guard_sidecar, info, probe, refuse_output_is_input, MEDIA_EXT as _MEDIA_EXT
 
 HERE = Path(__file__).resolve().parent
-MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac", ".aac"}
+# _common's one list less the stills, as batch.py walks a folder: verify kept a list of its own,
+# and a folder walk skipped .ts, .3gp, .wmv, .gif, .ogg, .opus, .aif/.aiff, .caf and .wma (#467 A218)
+MEDIA_EXT = {e for e in _MEDIA_EXT if e not in (".png", ".jpg", ".jpeg", ".webp")}
 
 
 def unique_stems(files: List[Path]) -> Dict[Path, str]:
@@ -39,18 +40,31 @@ def unique_stems(files: List[Path]) -> Dict[Path, str]:
     resolve to the identical output prefix. Each file's own steps still ran correctly in isolation,
     but with --keep the second file's outputs silently overwrote the first file's on disk, and the
     report showed PASS for both without ever flagging the collision (same bug class already fixed
-    in batch.py). Disambiguate every colliding stem with a stable per-collision index instead."""
+    in batch.py). Disambiguate every colliding stem with a stable per-collision index instead.
+
+    A stem is compared case-folded (clip.mp4 and Clip.MOV share one name on a case-insensitive
+    disk), and an indexed name skips any stem already taken, a file's own included: through 3.8.8
+    two clip.mp4 and a clip_1.mp4 gave "clip_1" twice (audit A121)."""
     counts: Dict[str, int] = {}
     for f in files:
-        counts[f.stem] = counts.get(f.stem, 0) + 1
+        counts[f.stem.casefold()] = counts.get(f.stem.casefold(), 0) + 1
+    taken = {f.stem.casefold() for f in files if counts[f.stem.casefold()] == 1}
     seen: Dict[str, int] = {}
     stems: Dict[Path, str] = {}
     for f in files:
-        if counts[f.stem] > 1:
-            seen[f.stem] = seen.get(f.stem, 0) + 1
-            stems[f] = f"{f.stem}_{seen[f.stem]}"
-        else:
+        key = f.stem.casefold()
+        if counts[key] == 1:
             stems[f] = f.stem
+            continue
+        n = seen.get(key, 0)
+        while True:
+            n += 1
+            name = f"{f.stem}_{n}"
+            if name.casefold() not in taken:
+                break
+        seen[key] = n
+        taken.add(name.casefold())
+        stems[f] = name
     return stems
 
 
@@ -96,6 +110,20 @@ def _probe_capturing(path: str) -> "Tuple[Optional[Dict[str, Any]], Dict[str, An
         STATE.json = was_json
 
 
+# The shared flags given to verify.py that every step receives as well (set in main())
+FORWARD: Dict[str, bool] = {"overwrite": False, "fast": False}
+
+
+def _forwarded(argv: List[str]) -> List[str]:
+    """--overwrite and --fast as the caller gave them to verify.py: through 3.8.8 neither reached
+    a step, so a rerun into the same --out failed every step on its own earlier output (audit
+    A119). The steps' --timeout is verify's own per-step limit (step()'s `timeout`)."""
+    out = ["--overwrite"] if FORWARD["overwrite"] else []
+    if FORWARD["fast"] and "--fast" not in argv:
+        out.append("--fast")
+    return out
+
+
 def step(name: str, argv: List[str], timeout: float) -> Dict:
     """Run one step and keep what its tool said: `ok` (it completed), and on a failure the tool's
     own `kind`, `reason` and `message` (its --json failure document), `error` being that message
@@ -113,7 +141,7 @@ def step(name: str, argv: List[str], timeout: float) -> Dict:
             r.update(kind="verification", reason="hdr_lost", message=r["error"])
         return r
     try:
-        proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:] + ["--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+        proc = subprocess.run([sys.executable, str(HERE / argv[0])] + argv[1:] + _forwarded(argv) + ["--json"], stdout=subprocess.PIPE, stderr=subprocess.PIPE,
                               text=True, encoding="utf-8", errors="replace", timeout=timeout or None)
     except subprocess.TimeoutExpired:
         msg = f"timeout after {timeout:.0f}s"
@@ -146,7 +174,7 @@ def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("paths", nargs="+", help="media files and/or folders")
     ap.add_argument("--out", help="directory for outputs (default: temp dir, deleted unless --keep)")
-    ap.add_argument("--keep", action="store_true", help="keep the outputs")
+    ap.add_argument("--keep", action="store_true", help="keep the outputs (without --out: in a new folder, named as out_dir and on stderr)")
     ap.add_argument("--quick", action="store_true", help="probe, copy cut, fit, caption, export only")
     ap.add_argument("--seconds", type=float, default=6.0, help="length of the test cut taken from each file (default 6)")
     ap.add_argument("--timeout", type=float, default=600.0, help="per-step timeout in seconds (default 600; 0 = no limit, as everywhere else)")
@@ -168,6 +196,7 @@ def main() -> int:
         # fault ("9 of 11 verification steps failed") rather than the flag's
         die(f"--seconds must be more than 0 (the length of the test cut), got {args.seconds:g}")
     files = collect(args.paths)
+    FORWARD.update(overwrite=STATE.overwrite, fast=STATE.fast)
     tmp = None
     if args.out:
         # made first, so a --report inside a new --out folder passes the guard below (#413 review)
@@ -177,20 +206,27 @@ def main() -> int:
         # a file this run writes itself (#408): not one of the media it verifies (a folder's
         # files included), nor an existing file without --overwrite
         guard_sidecar(args.report, *args.paths, *map(str, files))
-    if not args.out:
+    if not args.out and args.keep:
+        # --keep without --out: a folder of its own that outlives the run, named in the document
+        # (`out_dir`) and on stderr; through 3.8.8 it was the temporary directory, deleted at exit
+        # whatever --keep said, and never named (audit A120)
+        outdir = Path(tempfile.mkdtemp(prefix="ffskill_verify_"))
+    elif not args.out:
         tmp = tempfile.TemporaryDirectory(prefix="ffskill_verify_")
         outdir = Path(tmp.name)
+    kept_dir = None if tmp else str(outdir)
 
     stem_for = unique_stems(files)
-    results = []
+    # every file's plan is made before any step runs, so the names all of them will write are
+    # checked against every input first (below)
+    jobs: List[Tuple[Path, Dict, List[Tuple[str, List[str]]], Optional[Path]]] = []
     for f in files:
-        info(f"=== {f}")
         entry: Dict = {"file": str(f), "steps": [], "skipped": []}
         meta, failure = _probe_capturing(str(f))
         if meta is None:
             entry["steps"].append(dict({"step": "probe", "ok": False, "seconds": 0, "error": _cell(failure.get("message", ""))}, **failure))
             entry["skipped"].append({"step": "*", "reason": "input_unreadable", "message": "no other step runs on a file probe cannot read"})
-            results.append(entry)
+            jobs.append((f, entry, [], None))
             continue
         entry["probe"] = {k: meta.get(k) for k in ("duration", "format")}
         entry["probe"]["video"] = {k: (meta.get("video") or {}).get(k) for k in ("codec", "width", "height", "fps", "pix_fmt", "hdr_format", "rotation", "variable_frame_rate_suspected")}
@@ -202,7 +238,8 @@ def main() -> int:
         cut = f"{stem}_cut.mp4"
         seg_end = min(dur, args.seconds) if dur else args.seconds
         fast = ["--fast"]
-        plan = []
+        plan: List[Tuple[str, List[str]]] = []
+        cues: Optional[Path] = None
         skipped: List[Dict[str, str]] = entry["skipped"]
 
         def skip(step_name: str, reason: str, message: str) -> None:
@@ -212,7 +249,6 @@ def main() -> int:
             plan.append(("cut accurate", ["cut.py", str(f), "--start", "0", "--end", f"{seg_end:.2f}", "--accurate", "-o", f"{stem}_acc.mp4"] + fast))
             plan.append(("fit 9:16", ["fit.py", cut, "--aspect", "9:16", "--width", "720", "-o", f"{stem}_fit.mp4"] + fast))
             cues = outdir / f"{stem_for[f]}_cues.txt"
-            cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")
             plan.append(("caption", ["caption.py", cut, "--text", str(cues), "--animate", "pop", "--karaoke", "-o", f"{stem}_cap.mp4"] + fast))
             if not args.quick:
                 plan.append(("overlay text", ["overlay.py", cut, "--text", "verify", "--position", "top-left", "-o", f"{stem}_ovl.mp4"] + fast))
@@ -245,6 +281,30 @@ def main() -> int:
         else:
             for n in ("loudness measure", "silence list", "audio downmix"):
                 skip(n, "quick", "--quick runs probe, copy cut, fit, caption and export only")
+        jobs.append((f, entry, plan, cues))
+
+    # A name verify generates can be another input's (clip.mp4's cut is clip_cut.mp4, which can be
+    # a file of the same folder): each step checks its output against its own input only, so with
+    # --overwrite that input was replaced and its own steps then read the replacement. Every name
+    # the run will write -- step outputs, caption's sidecars, the cue file -- against every input,
+    # through a link or another case of the name included, before the first is written.
+    every_input = [str(f) for f in files]
+    for f, _entry, plan, cues in jobs:
+        written = [("cue file", str(cues))] if cues else []
+        for name, argv in plan:
+            if "-o" in argv:
+                out = argv[argv.index("-o") + 1]
+                written.append((name, out))
+                if argv[0] == "caption.py":
+                    written += [(name, str(Path(out).with_suffix(ext))) for ext in (".srt", ".ass")]
+        for name, out in written:
+            refuse_output_is_input(out, *every_input, why=f"it is where verify writes the {name!r} step's output for {str(f)!r}")
+
+    results = []
+    for f, entry, plan, cues in jobs:
+        info(f"=== {f}")
+        if cues:
+            cues.write_text("0:00-0:02 Verification caption\n0:02-0:04 Second | line\n", encoding="utf-8")
         for name, argv in plan:
             r = step(name, argv, args.timeout)
             entry["steps"].append(r)
@@ -275,14 +335,16 @@ def main() -> int:
         info(f"wrote {args.report}")
     if not args.json:
         print(report)
-    if tmp and not args.keep:
+    if tmp:
         tmp.cleanup()
+    if kept_dir:
+        info(f"step outputs kept in {kept_dir}")
     notes = (["--dry-run is ignored by verify.py: its steps ran and wrote their outputs"] if ignored_dry_run else [])
     if failed:
         die(f"{failed} of {total} verification steps failed", kind="verification", output=None, dry_run=STATE.dry_run,
-            report=args.report, files=results, failed=failed, total=total, **({"notes": notes} if notes else {}))
+            report=args.report, files=results, failed=failed, total=total, out_dir=kept_dir, **({"notes": notes} if notes else {}))
     if args.json:
-        emit(None, report=args.report, files=results, failed=failed, total=total, **({"notes": notes} if notes else {}))
+        emit(None, report=args.report, files=results, failed=failed, total=total, out_dir=kept_dir, **({"notes": notes} if notes else {}))
     return 0