ffmpeg-skill 3.8.5 → 3.8.6

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 (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.8.5`) | any release |
+| `skill.version` | the npm / package.json version (`3.8.6`) | 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 +149,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.5", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.8.6", "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"},
@@ -984,7 +984,8 @@ row or column), `non_av_streams_dropped` (with the
 first attempt's error beside `dropped_non_av_streams`), `measurement_input_pending` (skipped: a
 dry-run measurement of an earlier stage's output), `ffmpeg_list_unreadable` (`ffmpeg -encoders` or
 `-bsfs` could not be read; what needed it names the read failure, not a missing encoder) and
-`timeout_env_invalid` (an `FFMPEG_SKILL_TIMEOUT` that is not a number, or is negative);
+`timeout_env_invalid` (an `FFMPEG_SKILL_TIMEOUT` that is not a number, read as the 1800 s default, or is
+negative or above 500000 s, read as 0, no limit; a negative or too-long `--timeout` is refused instead, `kind: input`);
 `av1_encoder_libaom` and `crf_clamped`; `font_substituted` (with `font_used`); `drift_correction_skipped`
 (with `drift_skipped_reason`); `cropdetect_windows_failed` (with `windows_failed`);
 `ass_lines_unshifted` / `ass_lines_malformed`; `timeline_parse_failed`; and every `warning:` line a

package/mcp/server.py

@@ -136,8 +136,9 @@ def timeout_from_call(args: Dict[str, Any]) -> float:
 
     Structured `timeout` is the canonical key. A raw `argv` list ignores every other key, so
     `--timeout` has to be read from that list: `--timeout 0` otherwise left the ceiling at 4x
-    the 1800 s default while the child itself ran with no limit. A negative value is 0, matching
-    apply_common (0 means no limit)."""
+    the 1800 s default while the child itself ran with no limit. A negative value is 0 here (no
+    outer ceiling): the child refuses a negative --timeout itself, at once, as it refuses one too
+    long to wait for, which child_limit() gives no ceiling either."""
     if isinstance(args.get("argv"), list):
         parsed = _timeout_in_argv([str(a) for a in args["argv"]])
         if parsed is None:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.8.5",
+  "version": "3.8.6",
   "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": [

package/references/flags.md

@@ -9,7 +9,7 @@ Scripts live in `scripts/` next to SKILL.md; run them with `python3 <skill-dir>/
 
 ## Shared flags
 
-Shared flags (every script): `--dry-run`; `--json` (output path, its probe, the commands run); `--json-brief` (status/output/verified + a `summary`); `--fast` (preview quality); `--progress` (%/ETA); `--timeout SECONDS` (`kind: timeout`, default 1800; `0` for hour-long encodes); `--overwrite` (step 7); `--plan FILE` (a dry run `render.py FILE` runs later; refuses a changed input). Re-encoding tools also take `--hw` (Apple Silicon GPU, big files; `FFMPEG_SKILL_HW=1` = default, not export), `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264 (`cut.py`: HEVC source stays HEVC, `--no-keep-hevc` x264), HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).
+Shared flags (every script): `--dry-run`; `--json` (output path, its probe, the commands run); `--json-brief` (status/output/verified + a `summary`); `--fast` (preview quality); `--progress` (%/ETA); `--timeout SECONDS` (`kind: timeout`, default 1800; `0` for hour-long encodes; below 0 or above 500000 is refused); `--overwrite` (step 7); `--plan FILE` (a dry run `render.py FILE` runs later; refuses a changed input). Re-encoding tools also take `--hw` (Apple Silicon GPU, big files; `FFMPEG_SKILL_HW=1` = default, not export), `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264 (`cut.py`: HEVC source stays HEVC, `--no-keep-hevc` x264), HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).
 
 ## What `--dry-run` runs
 

package/references/scripts.md

@@ -359,7 +359,9 @@ scope-ratio film in a 16:9 frame) "detects" the same way as accidental
 bars; look at the frame before cropping it away. `windows` / `windows_failed`
 say how many windows were sampled and how many ffmpeg could not decode (those
 are skipped, with a `cropdetect_windows_failed` warning; all of them failing is
-a `kind: ffmpeg` failure).
+a `kind: ffmpeg` failure). `--limit` is a fraction of the top pixel code, 0..1;
+`--limit 1` is written to FFmpeg as that top code (255 for an 8-bit source), since
+FFmpeg reads a bare `1` as code 1.
 
 `--motion-centre` (1.18) reports the motion centroid once per second, sampled
 across the same windows: `motion_centre: [{time, x, y, x_frac, y_frac, motion}]`,
@@ -1103,7 +1105,9 @@ render result carries the caption stage's own block as `caption`.
 
 Under `--dry-run` a pack prints every child's planned commands and its table reads `planned`
 with no size or duration: nothing was encoded, so nothing is reported as verified. `--chapters`
-reaches a pack's audio destination like it does the single-template form.
+reaches a pack's audio destination like it does the single-template form. `--stop-after`,
+`--cache`, `--from`, `--work`, `--keep` and `--export-timeline` apply to one render and are
+refused with a pack; `--audit-log` is handed to every destination.
 
 Each template's frame, duration limit, loudness target and safe zones come from the one delivery
 table (`scripts/_platforms.py`). Safe zones are the fraction of the frame the app's own UI covers;
@@ -1134,13 +1138,15 @@ whose destinations did not all pass exits non-zero with the per-destination rows
 `audiogram` (1.16) is the one-call form of the podcast-to-video job: an `audiogram` stage runs
 **first** (it makes the picture the rest of the chain works on, through `waveform.py --image`),
 then captions, loudness, export and check. It needs `--image` (a local file) or a `background`
-colour in the project — this skill fetches nothing and invents no cover art — and it is
+colour in the project — this skill fetches nothing and invents no cover art; `--template
+audiogram` without `--image` is refused before anything runs, and a project with an `audiogram`
+and more than one clip is refused (it is drawn from one audio source) — and it is
 deliberately **not** part of `--template all`, whose destinations all assume a source that
 already has a picture.
 
 ### scenes.py — scene changes and highlight candidates
 ```
-scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15]] [--edl picks.txt] [--sheet scenes.png] [--json]
+scenes.py INPUT [--threshold 10] [--min-scene 1] [--highlights N [--target SECONDS] [--max-scene 15] [--edl picks.txt]] [--sheet scenes.png] [--json]
 scenes.py INPUT --beats [--beat-step 0.01] [--beat-range 60-200] [--min-confidence 0.5] [--json]   # INPUT may be audio-only
 scenes.py INPUT [--shots] [--audio-peaks] [--speech] [--json]
 ```
@@ -1326,7 +1332,10 @@ batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--jobs N|auto]
 `batch.json` holds either `steps` (a list of script argv with `{in}`/`{out}`
 placeholders, chained) or `project` (a render project applied per file).
 Outputs land in `output_dir` with `suffix`; a content-hash cache skips files
-already done with the same recipe. Use `--dry-run` to preview the plan.
+already done with the same recipe. Use `--dry-run` to preview the plan. The recipe's
+keys are `glob`, `steps`, `project`, `clip_key`, `output_dir`, `suffix` and `ext`; any
+other key is refused before an item runs, with the nearest valid name when one is close, else
+with the list of valid keys.
 A recipe that runs `cut.py` rolls its calls up: each of those `results` rows carries
 `cut_reencoded` (each call's `reencoded`) and `cut_reencode_reasons` (each
 `reencode_reason` its calls named, once per call),
@@ -1807,7 +1816,9 @@ toggleable streams and copies the video and audio bit for bit. The suffix splits
 on the last colon, and only when the tail is a BCP-47-shaped code *and* the whole
 token is not itself a file on disk, so `C:\subs\en.srt` and a file named
 `a:b.srt` are never mangled; a single `--srt` with no suffix still takes
-`--language`. `--track-title` names a track (repeated in `--srt` order;
+`--language`. `--offset` shifts every added track (each later one as a
+`<output>_trackN.srt` copy); `--max-lines` and `--min-duration` lay out the first
+`--srt` only, and a note says so when they changed it. `--track-title` names a track (repeated in `--srt` order;
 otherwise a frozen display-name table, and a code the table does not know gets
 the code itself — never a guessed or translated name), `--default-track LANG`
 marks one for auto-selection. Every other new track is explicitly marked *not*
@@ -2049,7 +2060,7 @@ completing with the old tags.
 
 ### audio.py — clean-up, music, ducking, layout
 ```
-audio.py INPUT [--voice [light|medium|strong] | --denoise [--denoise-strength 25]] [--gain dB]
+audio.py INPUT [--voice [light|medium|strong]] [--denoise [--denoise-strength 25]] [--gain dB]
          [--music FILE [--music-volume -14] [--duck [--duck-amount 12] [--duck-threshold -26.02]
           [--duck-attack 20] [--duck-release 400]] [--music-loop]]
          [--effects FILE [--effects-volume -14]] [--stereo-widen 0..1]
@@ -2076,6 +2087,13 @@ alone), `medium` for a normal talking head, `strong` for phone/laptop audio.
 stop at −1 dBFS: `medium` (the default, and the chain a bare `--voice` gets) can
 clip a hot source, since its make-up gain has nothing above it — normalise
 afterwards with `loudness.py`, or use `strong`, which measures quieter and safer.
+`--voice` with `--denoise` runs the level's chain with `afftdn=nf=-N:tn=1` at
+`--denoise-strength`: `light`, which has no denoise of its own, gets it after the
+highpass, and `medium`/`strong` run their own denoise stage at that strength
+(25 by default, the chain they have without `--denoise`). A parameter of a switch
+that is off is refused, as the `--duck-*` flags are: `--denoise-strength` without
+`--denoise`, `--music-volume`, `--music-fade-out` or `--music-loop` without `--music`,
+`--effects-volume` without `--effects` (a value equal to the default is not seen as given).
 `--duck` uses a sidechain compressor keyed by the speech so music dips under
 dialogue and swells in pauses:
 `sidechaincompress=threshold=0.05:ratio=<amount/3, min 2>:attack=20:release=400:makeup=1`

package/scripts/_common/decision.py

@@ -70,9 +70,14 @@ def aspect_ratio(value: Any) -> Optional[Fraction]:
     if len(parts) != 2:
         return None
     try:
-        return Fraction(int(parts[0]), int(parts[1]))
+        w, h = int(parts[0]), int(parts[1])
+        ratio = Fraction(w, h)
     except (ValueError, ZeroDivisionError):
         return None
+    # a negative side (`-16:9`, `16:-9`) is no aspect anyone means: frame_size() made a negative
+    # frame of it, which fit.py's pad refused inside ffmpeg (kind ffmpeg) and the timeline wrote.
+    # Each side is looked at, not the ratio: `-16:-9` is a positive fraction
+    return None if w < 0 or h < 0 else ratio
 
 
 def _even(n: float) -> int:

package/scripts/_common/runner.py

@@ -70,6 +70,14 @@ DEFAULT_TIMEOUT = 1800.0
 
 PROBE_TIMEOUT = 120.0
 
+# The largest per-call limit a run accepts (A8). subprocess's communicate() waits in poll(), whose
+# timeout is a C int of milliseconds: past 2147483.647 s (24.8 days) it raised OverflowError after
+# the child had started, so the tool died with a traceback while its ffmpeg ran on (measured on
+# Linux with Python 3.11: `--timeout 1e8` and `1e300` both did). The outer ceiling a run_tool()
+# child gets is 4x the per-call limit plus 60 s (child_limit()), so the per-call limit stops well
+# below a quarter of that: 500000 s, about 5.8 days. 0 is "no limit" and is what a longer job passes.
+MAX_TIMEOUT = 500000.0
+
 
 def _env_timeout() -> float:
     return _read_env_timeout()[0]
@@ -91,6 +99,11 @@ def _read_env_timeout() -> "Tuple[float, Optional[str]]":
         return DEFAULT_TIMEOUT, f"FFMPEG_SKILL_TIMEOUT={raw!r} is not a number of seconds; using the default {DEFAULT_TIMEOUT:g} s"
     if value < 0:
         return 0.0, f"FFMPEG_SKILL_TIMEOUT={raw!r} is negative; read as 0, which means no time limit"
+    if value > MAX_TIMEOUT:
+        # inf, 1e300: longer than a wait can be on this platform, which was an OverflowError
+        # traceback once the first child had started
+        return 0.0, (f"FFMPEG_SKILL_TIMEOUT={raw!r} is longer than a run can wait for here ({MAX_TIMEOUT:.0f} s); "
+                     "read as 0, which means no time limit")
     return value, None
 
 
@@ -500,7 +513,13 @@ def apply_common(args: "argparse.Namespace") -> None:
         out = getattr(args, "output", None)
         guard_sidecar(STATE.plan, *inputs, siblings=(out,) if isinstance(out, str) else ())
     if getattr(args, "timeout", None) is not None:
-        STATE.timeout = max(0.0, float(args.timeout))
+        # a negative --timeout used to be read as 0 without a word, which removed every limit the
+        # caller thought it had tightened, and one past MAX_TIMEOUT was an OverflowError traceback
+        # after ffmpeg had started (the MCP call reported a failure while the tool wrote its output)
+        if not 0 <= float(args.timeout) <= MAX_TIMEOUT:
+            die(f"--timeout must be 0 (no limit) or a number of seconds up to {MAX_TIMEOUT:.0f}, got {float(args.timeout):g}",
+                hint="--timeout 0 runs without a time limit")
+        STATE.timeout = float(args.timeout)
     else:
         env_limit, env_problem = _read_env_timeout()
         if env_problem:
@@ -2012,7 +2031,12 @@ def child_limit(per_call: Optional[float] = None) -> Optional[float]:
     fires first on a healthy run, and it is the only thing that ends a child hung for a reason
     that is not ffmpeg (a stuck import, a wedged pipe). None when the per-call limit is 0."""
     limit = STATE.timeout if per_call is None else per_call
-    return (limit * 4 + 60) if limit else None
+    if not limit or limit != limit or limit > MAX_TIMEOUT:
+        # 0 is "no limit". A per-call value no run can wait for (nan, inf, 1e300 from an MCP
+        # `timeout`) has no ceiling either: the child refuses that --timeout itself, at once, and
+        # communicate(timeout=4e300) would raise OverflowError with the child already running
+        return None
+    return limit * 4 + 60
 
 
 def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None,

package/scripts/_contract.py

@@ -477,7 +477,7 @@ DIAGNOSTIC_CODES = {
     "measurement_input_pending": ("skipped", "--dry-run: a measurement skipped because its input is an earlier stage's output that does not exist yet; {path}"),
     "non_av_streams_dropped": ("fallbacks", "the subtitle/data streams could not be copied, so the encode ran again without them (dropped_non_av_streams: true); {output, returncode, error: the first attempt's last stderr lines}; export.py adds dropped: the stream types this retry leaves out (data alone first, then subtitle too)"),
     "ffmpeg_list_unreadable": ("warnings", "`ffmpeg -encoders` / `-bsfs` could not be read; what needs the list says so instead of 'the build lacks it'; {list, tool, error}"),
-    "timeout_env_invalid": ("warnings", "FFMPEG_SKILL_TIMEOUT was not a number (the default was used) or was negative (read as 0, no limit); {value, timeout}"),
+    "timeout_env_invalid": ("warnings", "FFMPEG_SKILL_TIMEOUT was not a number (the default was used), or was negative or above 500000 s (read as 0, no limit); {value, timeout}"),
     # encoder decisions
     "av1_encoder_libaom": ("fallbacks", "--codec av1 on a build without libsvtav1: libaom-av1 encoded instead; {wanted, used}"),
     "crf_clamped": ("warnings", "the CRF handed to the encoder was above its maximum and was capped (the HEVC HDR line adds 2); {encoder, requested, asked, used}"),

package/scripts/audio.py

@@ -34,7 +34,8 @@ from _common.decision import conform_filter, conform_to_length
 
 # --downmix: ITU-R BS.775 fold-down, renormalised by pan's '<' (see main()).
 DOWNMIX_PAN = "pan=stereo|FL<FL+0.707*FC+0.707*BL+0.707*SL|FR<FR+0.707*FC+0.707*BR+0.707*SR"
-VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
+VOICE_DENOISE = "afftdn=nf=-25:tn=1"  # the denoise stage of the medium and strong chains
+VOICE_CHAIN = f"highpass=f=80,deesser=i=0.4,{VOICE_DENOISE},acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
 # --voice [light|medium|strong] (1.13). "medium" is the chain --voice has always produced, so a
 # bare --voice (and every existing call and MCP request) is byte-identical to before. "light"
@@ -48,6 +49,23 @@ VOICE_LEVELS = {
     "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled:latency=1",
 }
 
+
+
+def voice_chain(level: str, denoise_strength: "float | None") -> str:
+    """The --voice chain, with --denoise in it when asked (A136). `light` has no denoise of its
+    own, so --voice light --denoise used to drop the denoise without a word: it goes after the
+    highpass, where the other levels have theirs. `medium` and `strong` already denoise at
+    nf=-25; with --denoise that stage runs at --denoise-strength (25 by default, so the chain
+    --voice medium --denoise has always produced is unchanged)."""
+    chain = VOICE_LEVELS[level]
+    if denoise_strength is None:
+        return chain
+    stage = f"afftdn=nf=-{denoise_strength:g}:tn=1"
+    if VOICE_DENOISE in chain:
+        return chain.replace(VOICE_DENOISE, stage)
+    return chain.replace("highpass=f=80,", f"highpass=f=80,{stage},", 1)
+
+
 # The sidechain threshold the music bed has used since 1.4 is the linear 0.05 that ffmpeg's
 # sidechaincompress takes; -26.0206 dBFS is that same number in the unit the flag speaks, so the
 # default command line is unchanged to the byte while the value is now sayable.
@@ -349,6 +367,24 @@ def main() -> int:
         die(f"--duck is off but {duck_params[0]} was given; add --duck")
     if args.duck and not args.music:
         die("--duck ducks the music bed under the main track, but no --music was given; add --music FILE")
+    # A141: the same rule for the other parameters of a switch that is off. Each was accepted and
+    # did nothing: --music-fade-out 2 without --music faded nothing, --denoise-strength 40 without
+    # --denoise (also under --voice, whose own denoise stayed at 25) removed nothing more
+    bed_params = [flag for flag, name in (("--music-volume", "music_volume"), ("--music-fade-out", "music_fade_out"))
+                  if getattr(args, name) != ap.get_default(name)] + (["--music-loop"] if args.music_loop else [])
+    if not args.music and bed_params:
+        die(f"--music is off but {bed_params[0]} was given; add --music FILE")
+    if not args.effects and args.effects_volume != ap.get_default("effects_volume"):
+        die("--effects is off but --effects-volume was given; add --effects FILE")
+    if not args.denoise and args.denoise_strength != ap.get_default("denoise_strength"):
+        die("--denoise is off but --denoise-strength was given; add --denoise"
+            + (f" (--voice {args.voice} then denoises at that strength)" if args.voice else ""))
+    # afftdn's nf accepts -80..-20 only; 10..19.99 used to pass here and then fail inside ffmpeg.
+    if args.denoise and not 20 <= args.denoise_strength <= 60:
+        die(f"--denoise-strength must be 20..60 (afftdn noise floor in dB below full scale), got {args.denoise_strength:g}")
+    for flag, value in (("--fade-in", args.fade_in), ("--fade-out", args.fade_out), ("--music-fade-out", args.music_fade_out)):
+        if value < 0:  # a negative length reached afade, which refused it (kind ffmpeg)
+            die(f"{flag} must be 0 or more seconds, got {value:g}")
 
     for flag, value, lo, hi in (("--duck-amount", args.duck_amount, 0.0, 60.0),
                                 ("--duck-threshold", args.duck_threshold, -60.0, 0.0),
@@ -451,11 +487,8 @@ def main() -> int:
         # 5.1 while the run said verified.
         fx.append(DOWNMIX_PAN)
     if args.voice:
-        fx.append(VOICE_LEVELS[args.voice])
+        fx.append(voice_chain(args.voice, args.denoise_strength if args.denoise else None))
     elif args.denoise:
-        # afftdn's nf accepts -80..-20 only; 10..19.99 used to pass here and then fail inside ffmpeg.
-        if not 20 <= args.denoise_strength <= 60:
-            die(f"--denoise-strength must be 20..60 (afftdn noise floor in dB below full scale), got {args.denoise_strength:g}")
         fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
     if args.gain:
         fx.append(f"volume={args.gain:g}dB")

package/scripts/batch.py

@@ -23,6 +23,7 @@ Examples:
   python3 batch.py ~/Footage --recipe batch.json --watch 30     # poll the folder every 30 s
 """
 import argparse
+import difflib
 import hashlib
 import json
 import os
@@ -237,12 +238,21 @@ def intermediate_ext(src: Path) -> str:
 
 # the recipe keys the run reads as a string: a path, a glob, a file-name part
 RECIPE_STRINGS = ("glob", "project", "output_dir", "suffix", "ext")
+# every key a recipe may carry; anything else is refused, as render.py refuses a project's
+RECIPE_KEYS = RECIPE_STRINGS + ("clip_key", "steps")
 
 
 def check_recipe_types(recipe: Dict[str, Any]) -> None:
     """Refuse a recipe value of the wrong JSON type before anything runs (A18): a number where a
     path or glob goes, an absolute glob (pathlib refuses it), a step that is not a list. Each was
     a traceback, or a failure of every item naming the step's first character."""
+    for key in recipe:
+        # A104: a misspelled key ("ouput_dir", "sufix", "globs") was not read, so the batch ran
+        # with that key's default: other files, another folder, another name
+        if key not in RECIPE_KEYS:
+            near = difflib.get_close_matches(str(key), RECIPE_KEYS, n=1, cutoff=0.6)
+            die(f"recipe: unknown key {key!r}" + (f" (did you mean {near[0]!r}?)" if near
+                else f" (valid keys: {', '.join(sorted(RECIPE_KEYS))})"), kind="input")
     for key in RECIPE_STRINGS:
         value = recipe.get(key)
         if value is not None and not isinstance(value, str):

package/scripts/caption.py

@@ -1151,6 +1151,14 @@ def main() -> int:
              f"clear of the app's own UI)")
     if args.margin is None:
         args.margin = 30
+    if args.ass and (args.animate not in (None, "none") or args.karaoke):
+        # A74: both are drawn by the ASS this tool writes from cues; a caller's own --ass is burned
+        # as it stands, so the flag was accepted and nothing moved (a brand's caption.animate or
+        # caption.karaoke is a default for generated captions and is not a request here)
+        asked = "--animate " + args.animate if args.animate not in (None, "none") else "--karaoke"
+        die(f"{asked} is drawn by the ASS this tool generates from --srt, --text or --transcribe; --ass burns "
+            "the file as it is, with the animation and karaoke its own tags give it",
+            hint=f"drop {asked.split()[0]}, or pass the cues as --srt/--text and let this tool write the ASS")
     # a brand's caption.animate is a burn-in default; over --mode mux (soft subtitles) it used
     # to be applied anyway and then refused as "animation is burn only" -- ignore it there
     args.animate = args.animate or (bcap.get("animate", "none") if args.brand and args.mode != "mux" else "none")
@@ -1183,6 +1191,10 @@ def main() -> int:
             "above the size it is a floor for", kind="input")
     if args.min_duration < 0:
         die("--min-duration cannot be negative")
+    if args.gap < 0:
+        # A72: each auto-timed cue started before the one above it ended, and the first start
+        # below 0 was clamped: the cues overlapped on screen
+        die(f"--gap must be 0 or more seconds, got {args.gap:g}")
 
     meta = None
     if args.input:
@@ -1340,6 +1352,14 @@ def main() -> int:
     if missing_srt and not STATE.dry_run:
         die(f"{len(missing_srt)} SRT file(s) not found: " + ", ".join(m["path"] for m in missing_srt),
             kind="input", problems=missing_srt)
+    if args.offset and args.mode == "mux":
+        # --offset shifts every --srt track (A61); one it would leave with no cue is refused here,
+        # before the first file of this run is written (the first track's empty copy used to reach
+        # ffmpeg, which failed on it as kind ffmpeg and left the copy behind)
+        for p, _l in srt_tracks:
+            if os.path.exists(p) and not any(e + args.offset > 0 for _s, e, _t in parse_srt(p)):
+                die(f"--offset {args.offset:+g} moves every cue of {p} before 0: the track would be empty",
+                    kind="input")
     srt_path = args.srt
     if args.transcribe and not args.input:
         die("--transcribe needs the input video")
@@ -1419,6 +1439,11 @@ def main() -> int:
     if args.text:
         cues = parse_text_cues(args.text, args.auto_seconds, args.gap, fps_for_tc)
         cues, _ = lay_out(cues)
+        if not cues:
+            # --offset dropped every cue (one that ends at or before 0 goes): an empty SRT was
+            # written, and with a frame rate known the report below indexed the empty list
+            die(f"--offset {args.offset:+g} moves every cue of {args.text} before 0: no cue would be left",
+                kind="input")
         if args.write_srt:
             srt_path = args.write_srt
         elif args.input:
@@ -1540,7 +1565,27 @@ def main() -> int:
                 die(f"SRT file not found: {path}")
         for n in range(1, len(added)):
             path, lang = added[n]
-            if os.path.exists(path) and not srt_timings_shared_grammar(path):
+            pending = not os.path.exists(path)  # a dry run's pending track: an earlier step writes it
+            if pending and not args.offset:
+                continue
+            if args.offset:
+                # A61: --offset moved the first --srt only, so the other languages stayed where
+                # they were against the sound. Every added track is shifted by the same rule
+                # (a cue that ends at or before 0 is dropped, a start below 0 is clamped). A
+                # pending track's copy is planned under the same name, so the planned command
+                # reads the file the real run reads; only its cues wait for the file
+                copy = f"{os.path.splitext(output)[0]}_track{n}.srt"
+                claim([(copy, f"shifted SRT {n}")])
+                if not pending and not STATE.dry_run:
+                    moved = [(max(0.0, s + args.offset), e + args.offset, t) for s, e, t in parse_srt(path)
+                             if e + args.offset > 0]  # never empty: refused before the first write, above
+                    write_srt(moved, copy)
+                    info(f"wrote {copy} ({len(moved)} cues of {os.path.basename(path)} shifted by {args.offset:+g} s)")
+                side_notes.append(f"subtitle track {n} is {copy}, a copy of {os.path.basename(path)} shifted by "
+                                  f"--offset {args.offset:+g} s like the first track"
+                                  + ("; re-run this command without --dry-run to produce it" if STATE.dry_run else ""))
+                added[n] = (copy, lang)
+            elif not srt_timings_shared_grammar(path):
                 # the same rule as the first track (#414): ffmpeg is given what parse_srt() reads
                 copy = f"{os.path.splitext(output)[0]}_track{n}.srt"
                 claim([(copy, f"normalised SRT {n}")])
@@ -1550,6 +1595,11 @@ def main() -> int:
                 side_notes.append(f"subtitle track {n} is {copy}, a copy of {os.path.basename(path)} with its timings "
                                   "rewritten as hh:mm:ss,mmm, which ffmpeg reads as this tool does")
                 added[n] = (copy, lang)
+        if len(added) > 1 and any(caption_stats.get(k) for k in ("wrapped", "split", "extended")):
+            # --max-lines and --min-duration lay out the first --srt, the track the size fit is
+            # made for; the others keep their own line breaks and durations, and the result says so
+            side_notes.append(f"--max-lines/--min-duration laid out the first --srt only: the other {len(added) - 1} "
+                              "added track(s) keep the line breaks and cue lengths of their own files")
         titles = list(args.track_title or [])
         mp4_family = Path(output).suffix.lower() in (".mp4", ".m4v", ".mov")
         dropped_titles: List[str] = []

package/scripts/color.py

@@ -464,6 +464,12 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    # A165: a peak of 0 or below and a negative desaturation reached zscale/tonemap, which refused
+    # them as an ffmpeg failure (kind ffmpeg, as if the build were at fault)
+    if args.peak <= 0:
+        die(f"--peak must be more than 0 nits, got {args.peak:g}")
+    if args.desat < 0:
+        die(f"--desat must be 0 or more, got {args.desat:g}")
 
     meta = probe(args.input)
     if not meta.get("video"):

package/scripts/cropdetect.py

@@ -156,7 +156,12 @@ def main() -> int:
     duration = meta.get("duration") or 0.0
 
     failed: List[Dict] = []
-    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration, failed,
+    # A164: cropdetect reads a limit below 1 as a fraction of the top code and 1 or more as the
+    # code itself, so --limit 1, the top of the documented 0..1 range, was read as code 1 (nearly
+    # nothing is black) where 0.999 reads as nearly everything. The top of the range is written
+    # as the top code of the source's bit depth (255 for 8 bits, 1023 for 10).
+    limit = args.limit if args.limit < 1 else float((1 << int(meta["video"].get("bit_depth") or 8)) - 1)
+    rects = detect(args.input, args.seconds, args.samples, limit, args.round_to, duration, failed,
                    square_pixels(meta["video"]))
     # windows_failed: a window ffmpeg could not decode was skipped without a word, so a
     # crop measured on one window of five read as well-founded as one measured on all five

package/scripts/cut.py

@@ -1518,6 +1518,11 @@ def main() -> int:
             die(f"--remove needs the input's duration, which {args.input} does not report"
                 + (" yet (it is an earlier step's output)" if dry_run_input_pending(args.input) else ""))
         args.segments = ",".join(f"{s:.6f}-{e:.6f}" for s, e in keep_ranges_after_removing(parse_segments(args.remove, fps, clamp=True), total, fps))
+    elif args.segments and (args.end or args.duration or args.start is not None):
+        # A50: the single-range flags were accepted beside --segments and not read, where --remove
+        # refuses the same combination
+        die("--segments names every range to keep: it does not combine with --start, --end or --duration "
+            "(give the one range as --segments A-B, or drop --segments)")
     if args.segments:
         segments = parse_segments(args.segments, fps)
     else:

package/scripts/fit.py

@@ -109,6 +109,11 @@ def main() -> int:
 
     if args.fps is not None and args.fps <= 0:
         die(f"--fps must be positive, got {args.fps:g}")
+    for flag, value in (("--width", args.width), ("--height", args.height)):
+        # A165: 0 read as "not given" (the side was sized from the other one, or the run was
+        # "nothing to do") and a negative size reached ffmpeg's pad as kind ffmpeg
+        if value is not None and value < 1:
+            die(f"{flag} must be a positive number of pixels, got {value}")
     if not args.duration and not args.aspect and not args.width and not args.height and not args.fps and not args.rotate and not args.flip:
         die("nothing to do: give --duration, --aspect, --width/--height, --rotate/--flip and/or --fps")
     if not 0.0 <= args.crop_x <= 1.0:

package/scripts/graphics.py

@@ -137,6 +137,12 @@ def main(force_route: Optional[str] = None) -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    # A176: --from -1 divided by zero (a traceback, no JSON); --from -3 built an empty filter
+    # graph and --scale 0 or below a 0-px or negative box, both refused by ffmpeg (kind ffmpeg)
+    if args.count_from < 0:
+        die(f"--from must be 0 or more (the number the countdown starts at), got {args.count_from}")
+    if args.scale <= 0:
+        die(f"--scale must be more than 0 (a size multiplier; 1 is the template's own size), got {args.scale:g}")
     # 2.2.6: whitespace-only text is no text -- stripped before the "needs --title" checks, which
     # used to pass on "  " and burn an empty bar
     for _attr in ("name", "title", "subtitle", "text", "top", "bottom"):

package/scripts/look.py

@@ -220,6 +220,9 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
+    if args.width < 2:
+        # a width of 0 or below wrote a sheet two pixels a tile, or a still at the source's size
+        die(f"--width must be at least 2 px, got {args.width}")
     dur = meta.get("duration") or 0.0
     stem = Path(args.input).stem
     outdir = str(Path(args.output).parent) if args.output else str(Path(args.input).parent)
@@ -363,6 +366,10 @@ def main() -> int:
             cols, rows = (int(x) for x in args.tiles.lower().split("x"))
         except ValueError:
             die("--tiles must look like 4x3")
+        if cols < 1 or rows < 1:
+            # A21: 0 columns or rows divided the length by zero (a traceback, no JSON) and a
+            # negative count reached ffmpeg's tile filter (kind ffmpeg)
+            die(f"--tiles must be COLSxROWS with both at least 1 (like 4x3), got {args.tiles}")
         n = cols * rows
         dur = input_length(meta)  # the sheet is spread over the length: none stated is refused with the way out (#491)
         if not dur:

package/scripts/loudness.py

@@ -288,6 +288,14 @@ def main() -> int:
     # parsed before anything is measured, and an explicitly empty --versions ('' or ',') is refused
     # by parse_versions rather than read as "not given", which wrote one default file instead
     plan = parse_versions(args.versions) if args.versions is not None else None
+    # A124/A185: loudnorm's own ranges, checked here as --versions checks its items. Outside them
+    # the measurement pass failed inside ffmpeg (kind ffmpeg, with a page of stderr)
+    for flag, value, lo, hi, unit in (("-I/--lufs", args.lufs, -70.0, -5.0, "LUFS"), ("--tp", args.tp, -9.0, 0.0, "dBTP"),
+                                      ("--lra", args.lra, 1.0, 50.0, "LU")):
+        if not lo <= value <= hi:
+            die(f"{flag} must be {lo:g}..{hi:g} {unit} (loudnorm's range), got {value:g}")
+    if args.sample_rate is not None and args.sample_rate <= 0:
+        die(f"--sample-rate must be a positive number of Hz, got {args.sample_rate}")
     if plan is not None and args.output:
         die("--versions writes one file per target, named <name>_loudnorm_<target>.<ext>; it does not take -o")
 

package/scripts/metadata.py

@@ -215,6 +215,9 @@ def main() -> int:
         die(f"--min-chapter must be > 0, got {args.min_chapter:g}")
     if args.max_chapters < 0:
         die(f"--max-chapters must be >= 0 (0 = no cap), got {args.max_chapters}")
+    if args.silence_min < 0:
+        # A185: a negative length reached silencedetect, which refused it (kind ffmpeg)
+        die(f"--silence-min must be 0 or more seconds, got {args.silence_min:g}")
     tags = {k: getattr(args, k) for k in TAG_KEYS if getattr(args, k) is not None}
     if not args.chapters and not args.clear_chapters and not args.auto_chapters and not tags:
         die("nothing to write: give --chapters FILE, --auto-chapters, --clear-chapters and/or --title/--artist/...")

package/scripts/overlay.py

@@ -298,7 +298,7 @@ def main() -> int:
         args.image = brand["logo"]
         if args.position == ap.get_default("position"):
             args.position = brand.get("logo_position", "top-right")
-        if not args.scale and not args.scale_percent:
+        if args.scale is None and args.scale_percent is None:  # a given 0 is refused below, not replaced
             args.scale = int(brand.get("logo_scale", 160))
         if args.opacity == 1.0:
             args.opacity = float(brand.get("logo_opacity", 1.0))
@@ -402,6 +402,18 @@ def main() -> int:
             hint="give a --start inside the clip")
     if not 0 <= args.opacity <= 1:
         die("--opacity must be within 0..1")
+    # A190: a size of 0 or below drew nothing (--font-size -10 completed, verified: true, with no
+    # text in the picture; --scale -1 is ffmpeg's "keep the size") and a negative fade was no fade
+    if args.font_size < 1:
+        die(f"--font-size must be at least 1 px, got {args.font_size}")
+    if args.scale is not None and args.scale < 1:
+        die(f"--scale must be a positive width in px, got {args.scale}")
+    if args.scale_percent is not None and args.scale_percent <= 0:
+        die(f"--scale-percent must be more than 0, got {args.scale_percent:g}")
+    if args.fade < 0:
+        die(f"--fade must be 0 or more seconds, got {args.fade:g}")
+    if args.border < 0:
+        die(f"--border must be 0 or more px, got {args.border}")
     if args.chromakey and not args.video:
         die("--chromakey needs --video")
     if args.chromakey:
@@ -417,6 +429,11 @@ def main() -> int:
         die("--place needs --video")
     if args.place and (args.start or args.end or args.fade):
         die("--place sets when each piece shows: drop --start / --end / --fade")
+    if args.video and args.fade:
+        # A171: the fade is built for an image, logo or text layer; a video layer was composited
+        # with a hard edge and the result said nothing
+        die(f"--fade {args.fade:g} fades an image, logo or text layer; a video layer (--video) is shown "
+            "from --start to --end without a fade", hint="drop --fade for the video layer")
 
     output = args.output or default_output(args.input, "overlay", default_ext(alpha_codec) if alpha_codec else None)
     enable = enable_expr(start, end)

package/scripts/render.py

@@ -275,6 +275,15 @@ def template_project(name: str, args) -> Dict[str, Any]:
                        ("--brand", args.brand), ("--chapters", args.chapters), ("--image", args.image)):
         if path and not os.path.isfile(path):
             die(f"{flag}: file not found: {path}")
+    audiogram = tpl.get("audiogram")
+    if isinstance(audiogram, dict) and "$IMAGE" in audiogram.values() and not args.image and not args.write_project:
+        # A89: without --image the whole audiogram block was dropped as an unfilled placeholder,
+        # so the dry run planned a render with no picture and the real one failed at the export
+        # ("input has no video stream"). --write-project still writes the project to edit.
+        die(f"--template {name} draws the sound over a still picture and needs --image FILE "
+            "(a local file: nothing is fetched and no cover art is invented)",
+            hint='for a plain colour behind the waveform, write the project with --write-project and give it '
+                 '"audiogram": {"background": COLOUR}')
     proj, _ = fill_template(tpl, values)
     if args.fit:
         proj.setdefault("frame", {})["fit"] = args.fit
@@ -364,6 +373,8 @@ def render_pack(names: List[str], args) -> int:
                             ("--intermediate-preset", args.intermediate_preset)):
             if value:
                 argv += option_args(flag, value)
+        if STATE.audit_log:
+            argv += option_args("--audit-log", STATE.audit_log)  # every destination's records, in the one file asked for
         info(f"→ pack: {name}")
         proc = run_tool(argv + child_args() + ["--json"])
         try:
@@ -445,7 +456,7 @@ def check_keys(obj: Any, schema: str, label: str) -> None:
             else f" (valid keys: {', '.join(sorted(valid))})"))
 
 
-def check_overlay(ov: Any, label: str) -> None:
+def check_overlay(ov: Any, label: str, rendered: bool = True) -> None:
     """#326: a video layer is one kind of overlay, as overlay.py's --image/--text/--logo/--video
     are one mutually exclusive choice, and the chromakey* keys only act on it. A logo, image and
     text in one entry still draw the first of them, as before; only a combination with the new
@@ -461,6 +472,12 @@ def check_overlay(ov: Any, label: str) -> None:
         keyed = [k for k in ("chromakey", "chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
         if keyed:
             die(f"{label}: {keyed[0]} keys a colour out of a video layer and needs \"video\" (overlay.py --chromakey needs --video)")
+    if rendered and ov.get("video") and ov.get("fade"):
+        # A171: overlay.py --video has no fade; the layer was composited with a hard edge. Only a
+        # run that composites the layer refuses it: an export or a preview that stops before the
+        # overlays never read the entry, and completed
+        die(f"{label}: fade fades an image, logo or text layer; a video layer is shown from start to end "
+            "without one (drop \"fade\" from this entry)", kind="input")
     if ov.get("chromakey") is None:
         tuned = [k for k in ("chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
         if tuned:
@@ -598,7 +615,8 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
         for i, item in enumerate(items if isinstance(items, list) else []):
             check_keys(item, f"{name}[]", f"{name}[{i}]")
             if name == "overlays":
-                check_overlay(item, f"overlays[{i}]")
+                check_overlay(item, f"overlays[{i}]",
+                              rendered=not timeline and _reaches(READ_AT["overlays"], stop_after))
             if name != "clips":
                 continue
             # every clip stage starts from rel(c["src"]): without one it was a KeyError traceback
@@ -616,7 +634,29 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
                 # the render reads a clip's snap only on a clip it cuts (in/out), the export never
                 if not timeline and (item.get("in") is not None or item.get("out") is not None):
                     require_object(item["snap"], f"clips[{i}].snap")
+                    # A93: only the project's own snap.to was checked, so a clip's "beat" (or an
+                    # unsupported grid) was read as "not beats" and the cut rendered unsnapped
+                    check_snap_to(item["snap"], f"clips[{i}].snap")
                 check_keys(item["snap"], "snap", f"clips[{i}].snap")
+    if not timeline and "audiogram" in read and proj.get("audiogram") and isinstance(clips, list) and len(clips) > 1:
+        # A92: the audiogram stage draws the first clip's sound and the render carries on from
+        # that one file: every other clip was cut and then left out of the output without a word
+        die(f"audiogram: an audiogram is drawn from one audio source, and this project has {len(clips)} clips "
+            "(only the first would be in the output); join them first (join.py) and name the joined file as the one clip")
+    chapters = proj.get("chapters")
+    if chapters and not isinstance(chapters, (str, list)):
+        # A94: a number or an object was handed to metadata.py as a file name by the last stage,
+        # after the whole render ("chapters file not found: .../5"). false and 0 are "no chapters",
+        # as the stage's own `if ch:` reads them, and stay that
+        die(f'chapters: must be a chapters file path or a list of {{"at": TIME, "title": STR}}, got '
+            f"{type(chapters).__name__} {chapters!r:.60}")
+
+
+def check_snap_to(snap: Any, label: str) -> None:
+    """Refuse a snap grid other than beats, for the project's `snap` and for a clip's own."""
+    if isinstance(snap, dict) and str(snap.get("to") or "") not in ("", "none", "beats"):
+        die(f'{label}.to: only "beats" (or "none") is a beat grid this skill can measure, got '
+            f'{snap.get("to")!r}', kind="input")
 
 
 _LAST_DOC: Dict[str, Any] = {}   # the JSON document the most recent sh() child printed
@@ -1298,6 +1338,13 @@ def main() -> int:
         if len(names) > 1:
             if args.write_project:
                 die("--write-project writes one project; name a single template")
+            # A85: a pack runs one full render per destination and handed none of these to them,
+            # so --stop-after did not stop, --cache was not read and --work/--keep kept nothing
+            for flag, value in (("--stop-after", args.stop_after), ("--cache", args.cache), ("--from", args.from_stage),
+                                ("--work", args.work), ("--keep", args.keep), ("--export-timeline", args.export_timeline)):
+                if value:
+                    die(f"{flag} applies to one render, and --template {args.template} is a pack of {len(names)} "
+                        f"({', '.join(names)}), each a full render of its own: name a single template to use {flag}")
             return render_pack(names, args)
         proj: Dict[str, Any] = template_project(names[0], args)
         base = Path.cwd()
@@ -1444,9 +1491,7 @@ def main() -> int:
     # so a project that does not name "snap" builds the command line 1.16 built.
     snap_spec = proj.get("snap") or {}
     snap_reports: List[Dict[str, Any]] = []
-    if snap_spec and str(snap_spec.get("to") or "") not in ("", "none", "beats"):
-        die(f'snap.to: only "beats" (or "none") is a beat grid this skill can measure, got '
-            f'{snap_spec.get("to")!r}', kind="input")
+    check_snap_to(snap_spec, "snap")
 
     # ---- clips
     # 2.2.1: every clip source is checked before the first one is cut, and every problem is named

package/scripts/scenes.py

@@ -146,6 +146,20 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if args.highlights < 0:
+        die(f"--highlights must be 0 or more (the number of ranges to propose), got {args.highlights}")
+    if not args.highlights:
+        # A145: these shape or write the --highlights picks; without it they were accepted and
+        # nothing was written (--edl FILE completed with no file)
+        for flag, given in (("--edl", args.edl is not None), ("--target", args.target is not None),
+                            ("--max-scene", args.max_scene != ap.get_default("max_scene"))):
+            if given:
+                die(f"{flag} applies to the ranges --highlights proposes, and --highlights was not given; "
+                    "add --highlights N")
+    if args.target is not None and args.target <= 0:
+        die(f"--target must be more than 0 seconds, got {args.target:g}")
+    if args.max_scene <= 0:
+        die(f"--max-scene must be more than 0 seconds, got {args.max_scene:g}")
     if args.highlights:  # the EDL is written only with --highlights
         guard_sidecar(args.edl, args.input, siblings=(args.sheet,))
 

package/scripts/sequence.py

@@ -96,6 +96,10 @@ def main() -> int:
 
     if args.fps <= 0:
         die("--fps must be > 0")
+    for flag, value in (("--width", args.width), ("--height", args.height)):
+        # A109: 0 read as "not given" and a negative size reached ffmpeg (kind ffmpeg)
+        if value is not None and value < 1:
+            die(f"{flag} must be a positive number of pixels, got {value}")
     try:
         rate = exact_rate(args.fps)  # 29.97 is 30000/1001, as every other tool reads it
     except TimelineError as exc:

package/scripts/silence.py

@@ -627,6 +627,9 @@ def main() -> int:
     if not math.isfinite(args.margin) or args.margin < 0:
         # nan made inside_margin() drop every silence and re-encode the whole file unchanged
         die(f"--margin must be a finite number of seconds, 0 or more (got {args.margin:g})", kind="input")
+    if args.min_silence < 0:
+        # A52: a negative length reached silencedetect, which refused it (kind ffmpeg)
+        die(f"--min-silence must be 0 or more seconds, got {args.min_silence:g}", kind="input")
     for flag, value in (("--margin-lead", args.margin_lead), ("--margin-tail", args.margin_tail)):
         if value is not None and (not math.isfinite(value) or value < 0):
             die(f"{flag} must be a finite number of seconds, 0 or more (got {value:g})", kind="input")

package/scripts/sync.py

@@ -299,6 +299,12 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    # A190: with a search range of 0 or below no lag is tried, and the run reported an offset
+    # (0.012 s at confidence 0) for a correlation it never made
+    if args.max_offset <= 0:
+        die(f"--max-offset must be more than 0 seconds (the largest offset searched), got {args.max_offset:g}")
+    if args.analyze_seconds <= 0:
+        die(f"--analyze-seconds must be more than 0 seconds, got {args.analyze_seconds:g}")
     if args.analyze_seconds > 900:
         die(f"--analyze-seconds {args.analyze_seconds:g}: the window is decoded into memory; 900 s is the ceiling")
     args.sources = [args.second] + list(args.more_sources)

package/scripts/verify.py

@@ -163,6 +163,10 @@ def main() -> int:
         STATE.dry_run = False
         info("--dry-run is ignored by verify.py: its steps run and write their outputs")
 
+    if args.seconds <= 0:
+        # A190: every step was handed a cut of no length and failed, which read as the tools'
+        # 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)
     tmp = None
     if args.out:

package/scripts/waveform.py

@@ -10,9 +10,10 @@ generated fresh, there is no source picture involved.
 --style waveform draws the amplitude over time; --style spectrum draws a
 frequency-over-time heatmap instead, which reads more information out of
 dense mixes at the cost of being less immediately readable to a general
-audience. Both accept --width/--height and --color; waveform additionally
-takes --waveform-mode (how each sample is drawn) and --split-channels
-(stereo drawn as two separate lanes instead of summed to one).
+audience. Both accept --width/--height and --split-channels (stereo drawn as
+two separate lanes instead of summed to one); waveform additionally takes
+--color and --waveform-mode (how each sample is drawn). The spectrum is drawn
+in showspectrum's own colour map, so --color with --style spectrum is refused.
 
 Examples:
   python3 waveform.py podcast.wav -o waveform.mp4
@@ -54,7 +55,7 @@ def main() -> int:
     ap.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
     ap.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
     ap.add_argument("--fps", type=float, default=25.0, help="output frame rate (default 25)")
-    ap.add_argument("--color", default="lime", help="channel colour(s), pipe-separated per channel, e.g. 'lime' or 'cyan|magenta' (default lime)")
+    ap.add_argument("--color", default="lime", help="--style waveform only: channel colour(s), pipe-separated per channel, e.g. 'lime' or 'cyan|magenta' (default lime)")
     ap.add_argument("--background", default="black", help="background colour (default black)")
     ap.add_argument("--waveform-mode", choices=WAVEFORM_MODES, default="line", help="--style waveform only: how each sample is drawn (default line)")
     ap.add_argument("--split-channels", action="store_true", help="draw each channel in its own lane instead of summing to one")
@@ -97,6 +98,14 @@ def main() -> int:
         args.width, args.height = frame["w"], frame["h"]
         args.fps = float(PLATFORMS[args.platform].get("fps") or args.fps)
         info(f"--platform {args.platform}: {args.width}x{args.height} @ {args.fps:g}fps")
+    if args.style == "spectrum" and args.color != ap.get_default("color"):
+        # A144: showspectrum takes no colour, so the flag was accepted and the heatmap drawn in
+        # its own colour map (a brand's primary colour is a default and is not refused)
+        die(f"--color {args.color} colours the waveform's channels; --style spectrum is drawn in showspectrum's own "
+            "colour map and takes no colour", hint="drop --color, or use --style waveform")
+    if args.style == "spectrum" and args.waveform_mode != ap.get_default("waveform_mode"):
+        die(f"--waveform-mode {args.waveform_mode} is how --style waveform draws each sample; --style spectrum has no "
+            "such mode", hint="drop --waveform-mode, or use --style waveform")
     brand = load_brand(args.brand) if args.brand else None
     if brand:
         bc = brand.get("colors") or {}