ffmpeg-skill 2.2.2 → 2.2.4

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.2.2`) | any release |
+| `skill.version` | the npm / package.json version (`2.2.4`) | 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`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.2.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.2.4", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -492,6 +492,12 @@ Per-tool keys added in 1.18.0, all additive:
 | `sources` | `sync.py` | `[{path, offset_s, confidence, drift_ppm}]`, one entry per SOURCE. Present for every run, including the original single-SOURCE shape (where it mirrors the top-level `second`/`offset_seconds`/`confidence` additively). With 2+ SOURCEs it is the *only* per-source shape: there is no top-level `second`/`offset_seconds` because there is no single pair to put there |
 | `switch_mode`, `min_shot` | `multicam.py --switch energy` | `"energy"` and the `--min-shot` value used (default 1.5s), alongside the existing `cuts` (`[[start, end, camera], ...]`) which already carries the camera index for `--edl`'s companion cut list |
 
+Per-tool keys added after 2.2.2, all additive:
+
+| key | tool | what it holds |
+|---|---|---|
+| `sdr_path`, `notes` | `color.py --to-sdr` | `sdr_path` is `"tonemap"` for PQ / HLG / Dolby Vision input (and `--force` on an untagged file) or `"gamut"` for BT.2020 primaries on an SDR transfer, which is converted to BT.709 without a tone map (`--tonemap`/`--peak`/`--desat` do not apply); `notes` says which path was taken and why |
+
 `check.py` also gains an informational `subtitles` row on **every** platform:
 `PASS` when every soft subtitle stream carries a language tag, `WARN` when one
 does not (or when there are none). Like `channels` and `chapters` it is never

package/package.json

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

package/references/scripts.md

@@ -338,8 +338,10 @@ sticker template and `--srt`/`--text` burns captions by running caption.py
 afterwards -- both as second processes, so neither of those code paths is
 re-implemented here. `--image` must be a readable local file: a URL is refused
 (`kind: input`), nothing is fetched, and the skill never invents cover art --
-give an image or a colour. Without any of these flags the command line is
-byte-identical to 1.15's. Every run's result carries an `audiogram` object (style,
+give an image or a colour. The title and caption stages receive `--overwrite`, `--timeout`,
+`--fast` and `--dry-run`, and a failed stage reports that tool's own error kind; a missing
+`--srt`/`--text` file is refused (`kind: input`) before anything is encoded. Without any of
+these flags the command line is byte-identical to 1.15's. Every run's result carries an `audiogram` object (style,
 background, image, position, vis_height, platform, captions, title, stages,
 verified). `render.py --template audiogram` is the one-call form; it is
 deliberately not part of `--template all`.
@@ -573,7 +575,11 @@ frame, rate or xfade offsets that rest on a pending input's unmeasured placehold
 Normalises every clip to one frame size, fps, `yuv420p`, 48 kHz and one
 channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`;
 silent track generated for clips without audio), then chains `xfade` +
-`acrossfade`. Output length = sum of clips − transition × (n−1). Clips must be
+`acrossfade`. With a transition each clip has one length for picture and sound
+-- the video stream's, or the audio's when it runs more than a frame longer --
+and the shorter stream is padded (silence / last frame held), so every clip's
+sound stays with its picture. Output length = sum of clip lengths −
+transition × (n−1); `verified` checks the output's video-stream length against it. Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
 A subtitle/data track in the source is not carried into the retimed/concatenated
 output; the result says so with `dropped_non_av_streams: true`.
@@ -1049,6 +1055,13 @@ caption.py INPUT --srt FILE[:LANG] | --ass FILE | --text CUES.txt [--write-srt O
            [--emoji auto|color|png|mono|none] [--emoji-assets DIR] [--emoji-scale 1.0] [--emoji-max 60] [-o OUT]
 caption.py --text CUES.txt --write-srt OUT.srt        # generate the SRT only
 ```
+**Side files and `--overwrite` (2.2.4).** The files caption.py writes besides the
+video -- the `.srt` from `--text`/`--transcribe` (or `--write-srt`), the generated
+`.ass` (or `--write-ass`), `<output>_adjusted.srt`, `<output>_offset.ass` -- are
+refused like the video when they already exist, all named together, before speech
+recognition and before the first write, dry runs included; `--overwrite` replaces
+them. A hand-corrected transcript next to the output is never replaced silently.
+
 **Caption margins (1.17.2).** `--margin` is the **vertical** distance from the
 edge, in ASS units against the 288-line script grid (default 30; with
 `--platform` it becomes that destination's `safe.top`/`safe.bottom`, e.g. 22 %
@@ -1384,6 +1397,9 @@ threshold ducks on quieter speech, a shorter release brings the bed back faster.
 `--json`'s `audio` block reports the settings the run actually used.
 `--effects FILE` mixes a third track (sound effects, atmos) at
 `--effects-volume` and is never ducked — effects are cut to the picture.
+Every `--music` / `--effects` / `--replace` file is checked before ffmpeg runs (under
+`--dry-run` too): missing, empty, unreadable or with no audio stream, all of them are named in
+one refusal (`kind: input`, `problems: [{flag, path, reason}]`).
 `--stereo-widen 0..1` widens the stereo image (`extrastereo=m=1+2*amount`) and
 needs a real stereo source: it scales the side signal (L−R), so a mono track
 duplicated to two channels has nothing to scale. A 1-channel input is refused

package/scripts/_common/__init__.py

@@ -52,7 +52,7 @@ for _stream in (sys.stdout, sys.stderr):
 # demos/ or evals/ has ever reached for through `_common`.
 
 from _common.runner import (
-    add_common, apply_common, _check_existing_output, _check_no_overwrite_input, _check_output_path, child_args,
+    add_common, apply_common, _check_existing_output, refuse_existing_outputs, _check_no_overwrite_input, _check_output_path, child_args,
     child_limit, _CHILDREN, _cleanup_partial_output, _cmdline, CODECS, Context, DEFAULT_TIMEOUT,
     _DRAWTEXT_PENDING, _DRAWTEXT_TMPDIR, _drawtext_tmpdir, dry_run_input_pending, _ENCODERS, _env_timeout,
     ERROR_CODE, ERROR_RETRYABLE, EVEN_SCALE, _execute, _fail, ffmpeg_base, ffmpeg_encoders, _FFMPEG_VERSION,
@@ -179,7 +179,7 @@ __all__ = [
     "aac_args", "add_common", "add_pad_fill_args", "ADVANCE_EM", "analyze_levels", "apply_common", "detect_scenes", "detect_silences", "SCORE_RE", "SIL_RE", "_aspect_string",
     "audio_codec_for", "AUDIO_CODECS", "BIDI_SCRIPTS", "_bit_depth", "brand_caption_style", "BRAND_DEFAULTS",
     "brand_states_font", "_brief", "_BRIEF_DROP", "_brief_summary", "bt709_tag_args", "cfr_args", "_char_em",
-    "char_script", "_check_existing_output", "_check_no_overwrite_input", "_check_output_path", "child_args",
+    "char_script", "_check_existing_output", "refuse_existing_outputs", "_check_no_overwrite_input", "_check_output_path", "child_args",
     "child_limit", "_CHILDREN", "_cleanup_partial_output", "_cmdline", "CODECS", "color_hex", "_COLOR_TOKEN_RE",
     "concat_list_line", "Context", "_CURRENT_CTX", "db_to_linear", "decode_pcm_mono", "description_block", "_evidence_rank", "fmt_chapter_time", "propose_chapters",
     "filler_spans", "FILLER_WORDS", "FILLER_AMBIGUOUS", "FILLER_DISCOURSE_MARKERS",

package/scripts/_common/probe.py

@@ -283,6 +283,8 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "color_range": video.get("color_range"),
             "rotation": rotation,
             "nb_frames": _to_int(video.get("nb_frames")),
+            # the stream's own length (a container's also counts audio priming and a longer track)
+            "duration": _to_float(video.get("duration")),
             "bitrate": _to_int(video.get("bit_rate")),
         }
     if audio:
@@ -292,6 +294,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "channel_layout": audio.get("channel_layout"),
             "sample_rate": _to_int(audio.get("sample_rate")),
             "bitrate": _to_int(audio.get("bit_rate")),
+            "duration": _to_float(audio.get("duration")),
         }
         # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
         out["audio_streams"] = [{

package/scripts/_common/runner.py

@@ -542,21 +542,39 @@ def _check_existing_output(cmd: Sequence[str]) -> None:
     output = cmd[-1]
     if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):
         return
-    try:
-        exists = os.path.isfile(output)
-        real = os.path.realpath(output)
-    except OSError:
-        return
-    if not exists or real in STATE.written:
-        return
-    try:
-        st = os.stat(output)
-        STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)
-    except OSError:
-        pass
-    if STATE.overwrite:
+    refuse_existing_outputs([output])
+
+
+def refuse_existing_outputs(paths: Sequence[str]) -> None:
+    """_check_existing_output() for every file a run will write, named together, before the
+    first of them is written. A tool whose outputs are not all ffmpeg's last argument (caption.py's
+    .srt/.ass sidecars) calls this up front so a hand-edited sidecar is refused like the video
+    is, and a dry run predicts the same refusal."""
+    existing: List[str] = []
+    for output in paths:
+        if not output:
+            continue
+        try:
+            exists = os.path.isfile(output)
+            real = os.path.realpath(output)
+        except OSError:
+            continue
+        if not exists or real in STATE.written:
+            continue
+        try:
+            st = os.stat(output)
+            STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)
+        except OSError:
+            pass
+        if output not in existing:
+            existing.append(output)
+    if not existing or STATE.overwrite:
         return
-    die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path",
+    if len(existing) == 1:
+        die(f"refusing to overwrite existing output {existing[0]!r}: pass --overwrite to replace it, or choose another -o path",
+            kind="input", hint="pass --overwrite, or choose another -o path")
+    die("refusing to overwrite existing outputs " + ", ".join(repr(p) for p in existing)
+        + ": pass --overwrite to replace them, or choose another -o path",
         kind="input", hint="pass --overwrite, or choose another -o path")
 
 

package/scripts/_contract.py

@@ -443,6 +443,11 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
         extra = {"measured": {"type": "object", "description": "the loudnorm measurement of the input (input_i, input_tp, input_lra, input_thresh, target_offset); with --measure-only it is the whole result"},
                  "targets": {"type": "object", "description": "the requested lufs / tp / lra"},
                  "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"}}
+    elif name == "color":
+        extra = {"dropped_non_av_streams": {"type": "boolean"},
+                 "sdr_path": {"enum": ["tonemap", "gamut"], "description": "--to-sdr only: tonemap for PQ / HLG / Dolby Vision (and --force on an untagged file); gamut for BT.2020 primaries on an SDR transfer, converted to BT.709 without a tone map"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "--to-sdr only: which path was taken and why"},
+                 "measurements": {"type": "object", "description": "--correct only: signalstats levels of input and output"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},

package/scripts/audio.py

@@ -20,11 +20,12 @@ Examples:
   python3 audio.py talk.wav --compress --comp-threshold -20 --comp-ratio 4 --limit --limit-ceiling -1 -o talk_dyn.wav
 """
 import argparse
+import os
 import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
-from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs
+from _common import STATE, add_common, dry_run_input_pending, require_tool, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs
 
 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"
 
@@ -93,6 +94,41 @@ def dynamics_filter(name: str, args: argparse.Namespace) -> str:
     return name + ("=" + ":".join(opts) if opts else "")
 
 
+def preflight_beds(args: argparse.Namespace) -> List[Dict[str, Any]]:
+    """Every problem with every --replace / --music / --effects file, found before anything runs:
+    missing, a directory, empty, unreadable, or readable but with no audio stream (a picture-only
+    clip given as a bed used to reach ffmpeg's `[1:a:0]` and fail there, as kind ffmpeg, one file
+    at a time). Under --dry-run a file that does not exist yet is an earlier stage's output and is
+    left to the plan, as join.py's preflight does; a real file is checked under --dry-run too."""
+    problems: List[Dict[str, Any]] = []
+    beds = [(f, v) for f, v in (("--replace", args.replace), ("--music", args.music),
+                                ("--effects", args.effects)) if v]
+    if not beds:
+        return problems
+    ffprobe = require_tool("ffprobe")
+    for flag, path in beds:
+        if dry_run_input_pending(path):
+            continue
+        reason = None
+        if not os.path.exists(path):
+            reason = "missing"
+        elif os.path.isdir(path):
+            reason = "a directory, not a file"
+        elif os.path.getsize(path) == 0:
+            reason = "empty (0 bytes)"
+        else:
+            proc = run([ffprobe, "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", path],
+                       quiet=True, check=False)
+            kinds = {line.strip() for line in (proc.stdout or "").splitlines() if line.strip()}
+            if proc.returncode != 0 or not kinds:
+                reason = "unreadable: " + ((proc.stderr or "").strip().splitlines() or ["no streams"])[-1]
+            elif "audio" not in kinds:
+                reason = "no audio stream"
+        if reason:
+            problems.append({"flag": flag, "path": path, "reason": reason})
+    return problems
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -179,6 +215,13 @@ def main() -> int:
     if args.stereo_widen is not None and not (0.0 <= args.stereo_widen <= 1.0):
         die(f"--stereo-widen must be 0..1 (0 = untouched, 1 = maximum), got {args.stereo_widen:g}")
 
+    problems = preflight_beds(args)
+    if problems:
+        die(f"{len(problems)} of the extra audio files cannot be mixed: "
+            + "; ".join(f"{p['flag']} {p['path']}: {p['reason']}" for p in problems),
+            kind="input", problems=problems,
+            hint="each --music / --effects / --replace file must be a readable file with an audio stream")
+
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
     has_video = bool(meta.get("video"))
@@ -209,7 +252,6 @@ def main() -> int:
     main_src = f"0:a:{args.audio_stream}"
     idx = 1
     if args.replace:
-        probe(args.replace)
         inputs += ["-i", args.replace]
         main_src = f"{idx}:a:0"
         idx += 1
@@ -251,7 +293,6 @@ def main() -> int:
     last = "main"
 
     if args.music:
-        probe(args.music)
         if args.music_loop:
             inputs += ["-stream_loop", "-1", "-i", args.music]
         else:
@@ -276,7 +317,6 @@ def main() -> int:
     if args.effects:
         # A third bed, mixed in at its own level and deliberately never ducked: effects are cut
         # to the picture, so dipping them under speech would move them off their own frames.
-        probe(args.effects)
         inputs += ["-i", args.effects]
         e = f"{idx}:a:0"
         idx += 1

package/scripts/caption.py

@@ -44,7 +44,7 @@ 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
-from _common import 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, load_brand, 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
+from _common import 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, load_brand, 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
 # 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
@@ -1155,9 +1155,38 @@ def main() -> int:
         die(f"{len(missing_srt)} SRT file(s) not found: " + ", ".join(m["path"] for m in missing_srt),
             kind="input", problems=missing_srt)
     srt_path = args.srt
+    if args.transcribe and not args.input:
+        die("--transcribe needs the input video")
+    # 2.2.4: every file this run writes -- the video AND the .srt/.ass sidecars -- is checked
+    # against --overwrite here, before speech recognition and before the first write, dry runs
+    # included. Through 2.2.3 only ffmpeg's last argument was: a hand-corrected transcript or ASS
+    # next to the output was replaced on a re-run, even one ffmpeg's check then refused.
+    # Side files whose existence depends on the cues (an _adjusted.srt, an emoji-forced ASS) are
+    # checked again where they are written, still before that write.
+    claimed: set = set()
+
+    def claim(paths) -> None:
+        todo = [p for p in paths if p and os.path.realpath(p) not in claimed]
+        refuse_existing_outputs(todo)
+        claimed.update(os.path.realpath(p) for p in todo)
+
+    planned_out = args.output or (default_output(args.input, "captioned") if args.input else None)
+    up_front: List[str] = []
+    if args.transcribe:
+        up_front.append(args.write_srt or os.path.splitext(planned_out)[0] + ".srt")
+    elif args.text:
+        up_front.append(args.write_srt or (os.path.splitext(planned_out)[0] + ".srt" if args.input
+                                           else os.path.splitext(args.text)[0] + ".srt"))
+    if args.input:
+        if (args.animate != "none" or args.karaoke) and not args.ass:
+            up_front.append(args.write_ass or os.path.splitext(planned_out)[0] + ".ass")
+        if args.ass and args.offset and os.path.exists(args.ass):
+            up_front.append(os.path.splitext(planned_out)[0] + "_offset.ass")
+        # -o naming the input itself keeps its own, more specific refusal (_check_no_overwrite_input)
+        if os.path.realpath(planned_out) != os.path.realpath(args.input):
+            up_front.append(planned_out)
+    claim(up_front)
     if args.transcribe:
-        if not args.input:
-            die("--transcribe needs the input video")
         # the sidecar goes next to the output like the --text one, not into the source folder
         # where it silently replaced a hand-written <input>.srt (review 5)
         srt_path = args.write_srt or os.path.splitext(args.output or default_output(args.input, "captioned"))[0] + ".srt"
@@ -1165,8 +1194,6 @@ def main() -> int:
             cues = []
             info(f"[dry-run] would transcribe {args.input} and write {srt_path}")
         else:
-            if os.path.exists(srt_path) and not getattr(args, "overwrite", False):
-                info(f"warning: {srt_path} already exists and will be replaced by the transcript (pass --overwrite to confirm)")
             cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)
             args._word_timings = whisper_word_timings(srt_path)
             cues, changed = lay_out(cues)
@@ -1211,6 +1238,7 @@ def main() -> int:
         adjusted, changed = lay_out(parse_srt(srt_path))
         if changed:
             new_srt = os.path.splitext(output)[0] + "_adjusted.srt"
+            claim([new_srt])
             if STATE.dry_run:
                 info(f"[dry-run] would write {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
             else:
@@ -1393,6 +1421,7 @@ def main() -> int:
         if args.karaoke and not getattr(args, "_word_timings", None):
             args._word_timings = whisper_word_timings(srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
+        claim([ass_path])
         w, h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
             w, h = h, w

package/scripts/color.py

@@ -169,12 +169,36 @@ def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str
     return ",".join(chain)
 
 
+def bt2020_sdr_to_bt709_chain(meta: dict) -> str:
+    """Gamut conversion only, for BT.2020 primaries on an SDR transfer (probe: `bt2020_or_hdr`
+    true, `hdr_signal` false). Such a file is already display-referred SDR: linearising it with
+    its own transfer, mapping the primaries to BT.709 and re-applying the BT.709 transfer keeps
+    white at white and grey at grey. The tone map the HDR chain adds would treat 100 % SDR white
+    as a fraction of a 1000-nit peak and darken the picture (white Y 235 -> 151, grey 126 -> 90)."""
+    v = meta["video"]
+    trc = v.get("color_transfer") or "bt709"
+    space = v.get("color_space") or "bt2020nc"
+    return ",".join([
+        f"zscale=tin={trc}:pin=bt2020:min={space}:rin={v.get('color_range') or 'tv'}:t=linear",
+        "format=gbrpf32le",
+        "zscale=p=bt709",
+        "zscale=t=bt709:m=bt709:r=tv",
+        "format=yuv420p",
+    ])
+
+
+def is_bt2020_sdr(v: dict) -> bool:
+    """BT.2020 primaries on a non-HDR transfer and no Dolby Vision: gamut-only --to-sdr."""
+    return bool(v.get("bt2020_or_hdr")) and not v.get("hdr_signal") and not v.get("dolby_vision") \
+        and v.get("color_transfer") not in ("smpte2084", "arib-std-b67")
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
     ap.add_argument("-o", "--output", help="output file (default: <name>_sdr / _lut / _retag)")
     mode = ap.add_mutually_exclusive_group(required=True)
-    mode.add_argument("--to-sdr", action="store_true", help="tone-map HDR (PQ/HLG/BT.2020) to SDR BT.709")
+    mode.add_argument("--to-sdr", action="store_true", help="convert to SDR BT.709: tone-map HDR (PQ/HLG/Dolby Vision); BT.2020 primaries on an SDR transfer get a gamut conversion only, no tone map")
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
@@ -183,7 +207,7 @@ def main() -> int:
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
     ap.add_argument("--lut-strength", type=float, default=1.0, help="blend LUT result with the original, 0..1 (default 1)")
-    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is not tagged as HDR (treat as PQ)")
+    ap.add_argument("--force", action="store_true", help="run --to-sdr even if the file is tagged neither HDR nor BT.2020 (tone-mapped as PQ; a BT.2020 SDR file never needs it)")
     ap.add_argument("--exposure", type=float, default=CORRECTION["exposure"][0], help="--correct: exposure in stops, -3..3 (default 0)")
     ap.add_argument("--contrast", type=float, default=CORRECTION["contrast"][0], help="--correct: contrast, 0..2, 1=unchanged (default 1)")
     ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
@@ -278,10 +302,21 @@ def main() -> int:
         return 0
 
     measurements = None
+    sdr_extra: dict = {}
     if args.to_sdr:
         if not v.get("bt2020_or_hdr") and not args.force:
             die(f"{args.input} is not tagged as HDR (transfer={v.get('color_transfer')}, primaries={v.get('color_primaries')}). Use --force to tone-map anyway.")
-        vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+        if is_bt2020_sdr(v):
+            vf = bt2020_sdr_to_bt709_chain(meta)
+            sdr_path = "gamut"
+            note = (f"BT.2020 primaries on an SDR transfer ({v.get('color_transfer')}): converted the gamut to BT.709 "
+                    f"without a tone map (--tonemap/--peak/--desat do not apply)")
+        else:
+            vf = hdr_to_sdr_chain(meta, args.tonemap, args.peak, args.desat)
+            sdr_path = "tonemap"
+            note = f"tone-mapped {v.get('hdr_format') or 'untagged input as PQ (--force)'} to SDR BT.709 with {args.tonemap}"
+        info(f"note: {note}")
+        sdr_extra = {"sdr_path": sdr_path, "notes": [note]}
         output = args.output or default_output(args.input, "sdr")
         tag = "sdr"
     elif args.correct:
@@ -323,7 +358,7 @@ def main() -> int:
     r = probe(output, role="output")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
-    extra = {"dropped_non_av_streams": dropped_streams}
+    extra = {"dropped_non_av_streams": dropped_streams, **sdr_extra}
     if measurements is not None:
         measurements["output"] = analyze_levels(output)
         extra["measurements"] = measurements

package/scripts/join.py

@@ -63,6 +63,20 @@ def unpending_length(durs: List[float], d: float) -> Optional[float]:
     return round(sum(durs) - d * (len(durs) - 1), 3)
 
 
+def clip_length(meta: Dict[str, Any], fps: float) -> float:
+    """The one length a clip holds in a crossfaded join, for its picture and its sound alike: the
+    video stream's, or the audio stream's when the sound runs more than a frame past the picture
+    (narration is never cut; an AAC tail adds no frame). The container duration (audio priming,
+    a longer track) is only the fallback when a stream length is unknown (a pending input)."""
+    v = (meta.get("video") or {}).get("duration")
+    a = (meta.get("audio") or {}).get("duration")
+    if not v:
+        return meta.get("duration") or 0.0
+    if a and fps and a > v + 1.0 / fps:
+        return a
+    return v
+
+
 def expected_text(expected: Optional[float]) -> str:
     """unpending_length() as the stderr summary line puts it."""
     return f"expected ~{expected:.3f}s" if expected is not None else "expected length unknown until the pending inputs exist"
@@ -293,7 +307,10 @@ def main() -> int:
     w, h = w - (w % 2), h - (h % 2)
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
-    for p, dur in zip(args.inputs, durs):
+    # a crossfaded join gives each clip one length for both streams, so the offsets that place
+    # every picture also place its sound; the plain cut (concat) keeps the streams paired itself
+    lens = [clip_length(m, fps) for m in metas] if d else durs
+    for p, dur in zip(args.inputs, lens):
         if d and dur <= d * 2 and not STATE.dry_run:
             die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
 
@@ -347,14 +364,22 @@ def main() -> int:
         chain = "".join(f"[v{i}][a{i}]" for i in range(n))
         parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
     else:
-        vprev, aprev = "v0", "a0"
+        # pad the shorter stream to the clip's length: the audio with silence, the picture by
+        # holding its last frame, then cut both there -- each xfade and acrossfade then starts
+        # at the same clip boundary instead of the audio chain drifting by every clip's gap
+        for i in range(n):
+            vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
+            hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
+            parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
+            parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
+        vprev, aprev = "vp0", "ap0"
         offset = 0.0
         for i in range(1, n):
-            offset += durs[i - 1] - d
+            offset += lens[i - 1] - d
             vout = f"vx{i}" if i < n - 1 else "vout"
             aout = f"ax{i}" if i < n - 1 else "aout"
-            parts.append(f"[{vprev}][v{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
-            parts.append(f"[{aprev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
+            parts.append(f"[{aprev}][ap{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
             vprev, aprev = vout, aout
 
     # A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
@@ -367,12 +392,26 @@ def main() -> int:
                            "by its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
+    if d:
+        # the fps filter already made the picture constant-rate and xfade places every frame: FFmpeg
+        # 5.1's default cfr output mode still duplicated the last one to meet the AAC tail (a 51-frame
+        # dissolve came out 52), which newer builds no longer do -- pass the frames through as built
+        cmd += ["-fps_mode", "passthrough"]
     cmd += video_args(hdr_meta or metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
-    expected = unpending_length(durs, d)
+    expected = unpending_length(lens, d)
     r = probe(output, role="output")
-    info(f"wrote {output} ({fmt_secs(r['duration'])}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
+    # the picture is what the offsets place: measure the video stream, not the container (whose
+    # length also counts the AAC tail), against the length the clips add up to
+    measured = (r.get("video") or {}).get("duration") or r.get("duration")
+    verification = []
+    if expected is not None and measured is not None and not STATE.dry_run:
+        tol = max(1.5 / fps, 0.05)
+        verification.append({"step": "duration", "ok": abs(measured - expected) <= tol,
+                             "measured": round(measured, 3), "expected": expected, "tolerance": round(tol, 3)})
+    info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     emit(output, mode="video", **reported(), clips=n, transition=args.transition, expected_duration=expected,
+         verification=verification,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
     return 0
 

package/scripts/render.py

@@ -64,7 +64,7 @@ from typing import Any, Dict, List, Optional, Sequence
 
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
-from _common import STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version
+from _common import STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version
 import subprocess
 from _contract import CONTRACT_VERSION
 from batch import file_key
@@ -1010,14 +1010,21 @@ def main() -> int:
             problems.append({"index": i, "path": src, "reason": "a directory, not a file"})
         elif os.path.getsize(src) == 0:
             problems.append({"index": i, "path": src, "reason": "empty (0 bytes)"})
+        elif not STATE.dry_run:
+            # 2.2.4: readable, too -- one ffprobe per source, nothing decoded, the same test
+            # join.py's preflight makes. Before, a real run probed the sources one by one and
+            # stopped at the first unreadable file; the dry run already named every one via join.
+            proc = run([require_tool("ffprobe"), "-v", "error", "-show_entries", "stream=codec_type",
+                        "-of", "csv=p=0", src], quiet=True, check=False)
+            kinds = {line.strip() for line in (proc.stdout or "").splitlines() if line.strip()}
+            if proc.returncode != 0 or not kinds & {"audio", "video"}:
+                first = ((proc.stderr or "").strip().splitlines() or ["no audio or video stream"])[-1]
+                problems.append({"index": i, "path": src, "reason": f"unreadable: {first}"})
     if problems:
         die(f"{len(problems)} of {len(clips)} clip sources unusable: "
             + "; ".join(f"clip {p['index']}: {p['reason']}: {p['path']}" for p in problems),
             kind="input", problems=problems,
             hint="fix or remove these clips in the project; nothing was cut")
-    if not STATE.dry_run:
-        for c in clips:
-            probe(rel(c["src"]))  # an unreadable source stops the run before any clip is cut
 
     parts: List[str] = []
     for i, c in enumerate(clips):

package/scripts/sync.py

@@ -186,7 +186,11 @@ def measure_offset(ref_path: str, oth_path: str, start: float, seconds: float, s
     ref = envelope(ref_s, step)
     oth = envelope(oth_s, step)
     if len(ref) < 10 or len(oth) < 10:
-        die("not enough audio to analyse")
+        # name the file (or both): sync.py and multicam.py measure several sources, and a bare
+        # "not enough audio" left the caller to guess which one was too short
+        short = [p for p, env in ((ref_path, ref), (oth_path, oth)) if len(env) < 10]
+        die(f"not enough audio to analyse in {' and '.join(short)} "
+            f"(needs at least {10 * step_ms / 1000:g} s of audio from {start:g} s)", kind="input")
     max_lag = int(max_offset * SR / step)
     lag, score = cross_correlate(ref, oth, max_lag)
     offset = lag * step / SR

package/scripts/waveform.py

@@ -30,14 +30,14 @@ invented: give an image or a colour.
   python3 waveform.py ep.m4a --image cover.png --srt ep.srt --title "Episode 12" -o ep.mp4
 """
 import argparse
+import json
 import os
-import subprocess
 import sys
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common import (add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base,
                      info, load_brand, pad_filters, probe, run, STATE, validate_color, video_args, X264_PRESETS,
-                     fmt_secs)
+                     fmt_secs, child_args, run_tool)
 
 WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
 
@@ -114,6 +114,11 @@ def main() -> int:
         die(f"--vis-height must be between 0 and 1, got {args.vis_height:g}")
     if args.srt and args.text:
         die("--srt and --text exclude each other (both name the cues to burn)")
+    # caption.py would refuse a missing cue file too, but only after the visualisation had been
+    # encoded: check it here, before any encode, and name the flag the caller gave
+    for flag, path in (("--srt", args.srt), ("--text", args.text)):
+        if path and not os.path.isfile(path):
+            die(f"{flag} file not found: {path}", kind="input")
 
     if args.width <= 0 or args.height <= 0:
         die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
@@ -193,30 +198,40 @@ def main() -> int:
     if meta.get("duration"):
         cmd += ["-t", f"{float(meta['duration']):.3f}"]
     cmd += ["-shortest", render]
-    run(cmd)
+    stem, ext = os.path.splitext(output)
+    intermediates = [p for p in (render, stem + "_titled" + ext) if p != output]
+    try:
+        run(cmd)
 
-    stages = ["waveform"]
-    current = render
-    if args.title:
-        stem, ext = os.path.splitext(output)
-        titled = stem + "_titled" + ext if (args.srt or args.text) else output
-        _child("graphics.py", [current, "--template", "sticker", "--text", args.title,
-                               "--position", "top-left", "-o", titled]
-               + (["--brand", args.brand] if args.brand else []))
-        stages.append("title")
-        current = titled
-    if args.srt or args.text:
-        _child("caption.py", [current] + (["--srt", args.srt] if args.srt else ["--text", args.text])
-               + (["--platform", args.platform] if args.platform else []) + ["-o", output])
-        stages.append("captions")
-        current = output
-    if current != output and not STATE.dry_run:
-        os.replace(current, output)
-        current = output
-    # the intermediates exist only to keep each tool's own code path the only one there is
-    for temp in (render, os.path.splitext(output)[0] + "_titled" + os.path.splitext(output)[1]):
-        if temp != output and os.path.exists(temp) and not STATE.dry_run:
-            os.remove(temp)
+        stages = ["waveform"]
+        current = render
+        if args.title:
+            titled = stem + "_titled" + ext if (args.srt or args.text) else output
+            # a dry run rendered no _vis file for graphics.py to probe, so its default --end (the
+            # clip's end) came out 0 and the plan failed: give it the source's duration, which
+            # is what -t caps the render at. A real run is unchanged.
+            end = (["--end", f"{float(meta['duration']):.3f}"]
+                   if STATE.dry_run and meta.get("duration") else [])
+            _child("graphics.py", [current, "--template", "sticker", "--text", args.title,
+                                   "--position", "top-left"] + end + ["-o", titled]
+                   + (["--brand", args.brand] if args.brand else []))
+            stages.append("title")
+            current = titled
+        if args.srt or args.text:
+            _child("caption.py", [current] + (["--srt", args.srt] if args.srt else ["--text", args.text])
+                   + (["--platform", args.platform] if args.platform else []) + ["-o", output])
+            stages.append("captions")
+            current = output
+        if current != output and not STATE.dry_run:
+            os.replace(current, output)
+            current = output
+    finally:
+        # the intermediates exist only to keep each tool's own code path the only one there is;
+        # a failed stage removes them too, not only a finished chain
+        if not STATE.dry_run:
+            for temp in intermediates:
+                if os.path.exists(temp):
+                    os.remove(temp)
 
     result = probe(output, role="output")
     v = result["video"] or {}
@@ -268,16 +283,24 @@ def main() -> int:
 
 def _child(script_name: str, argv: "list") -> None:
     """Run one of this skill's own tools as a second process, so the code path it owns (the ASS
-    generator, the drawtext template) stays the only one there is."""
+    generator, the drawtext template) stays the only one there is. The shared flags (--overwrite,
+    --timeout, --fast, --dry-run) reach it through child_args(), as render.py's stages get them,
+    and a failure is re-raised with the child's own kind, exit code and hint."""
     here = os.path.dirname(os.path.abspath(__file__))
-    cmd = [sys.executable, os.path.join(here, script_name)] + [str(a) for a in argv]
-    if STATE.dry_run:
-        cmd.append("--dry-run")
-    info("-> " + " ".join(os.path.basename(c) if c.endswith(".py") else str(c) for c in cmd[1:]))
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace")
+    cmd = [os.path.join(here, script_name)] + [str(a) for a in argv] + child_args() + ["--json"]
+    info("-> " + " ".join(os.path.basename(c) if c.endswith(".py") else str(c) for c in cmd[:-1]))
+    proc = run_tool(cmd)
     if proc.returncode != 0:
-        die(f"{script_name} failed:\n{(proc.stderr or proc.stdout).strip()[-800:]}", kind="ffmpeg")
-
+        try:
+            doc = json.loads(proc.stdout.strip() or "{}")
+        except ValueError:
+            doc = {}
+        if not isinstance(doc, dict):
+            doc = {}
+        err = doc.get("error") or {}
+        extra = {"hint": err["hint"]} if err.get("hint") else {}
+        die(f"{script_name} failed: {err.get('message') or (proc.stderr.strip().splitlines() or ['?'])[-1][:300]}",
+            code=int(doc.get("exit_code") or 1), kind=err.get("kind") or "input", stage=script_name, **extra)
 
 if __name__ == "__main__":
     sys.exit(main())