ffmpeg-skill 2.2.3 → 2.2.5

package/README.md

@@ -259,7 +259,7 @@ These are the rules the skill file gives the agent and the code enforces.
 |---|---|
 | `render.py` | Render a whole edit from a declarative `project.json` (clips, transitions, captions, overlays including the social sticker/hook/meme graphics, music and stem levels, loudness, export, chapter markers, check); `--init`, `--dry-run`, `--stop-after`, `--cache DIR`/`--from STAGE` (reuse the stages that did not change); the captions block takes the fit-size policy (`fit_size`, `min_size`, `fit_size_scope`) and the run reports the caption stage's counts as `caption`; `--template NAME INPUT` renders a shipped delivery template (`--template all` writes the whole social pack plus its table); `--export-timeline edit.fcpxml\|.edl\|.otio` (2.1) writes the cut as an editor timeline for Final Cut, DaVinci Resolve or Premiere instead of rendering it — clips, speed, dissolves, the music bed and chapter markers carry over, and `not_exported` names what stays behind |
 | `batch.py` | Apply a step recipe or a project to a folder with a content-hash cache; `--watch`; `--jobs N` processes several files at once under one shared `--timeout` |
-| `multicam.py` | Align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list; `--switch energy` auto-cuts to whichever camera is loudest/talking instead of a hand-built list, with `--min-shot` (minimum shot length) and `--edl` (write the cut list) |
+| `multicam.py` | Align any number of cameras and recorders by audio (with drift correction) and cut between them from a switch list; `--switch energy` auto-cuts to whichever camera is loudest/talking instead of a hand-built list, with `--min-shot` (minimum shot length) and `--edl` (write a plain START-END cut list, not a CMX EDL; for Premiere/Resolve use `--write-project` then `render.py --export-timeline`) |
 | `verify.py` | Run the toolchain on real device files and report PASS / FAIL per step |
 
 Not tools, but part of the surface: `mcp/server.py` (the MCP transport) and `scripts/_contract.py` (`contract --json`, `doctor`). Per-flag reference for every tool: [references/scripts.md](references/scripts.md).

package/SKILL.md

@@ -5,11 +5,11 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. This file is enough to do a job: the table below routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much to read as this file; open one only for a question you have: `references/scripts.md` (every flag of all 42 scripts), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end). MCP: `tools/list` shows only the core 12 by default; the other 42 (per this table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. This file is enough to do a job: the table below routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as this one; open one only for a question you have: `references/scripts.md` (every flag of all 42 scripts), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end). MCP: `tools/list` shows only the core 12 by default; the other 42 (per this table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.
 
 Shared flags, on every script: `--dry-run`; `--json` (output path, a probe of the output, the commands run); `--json-brief` (status/output/verified plus a `summary`; prefer on writing steps); `--fast` (preview quality); `--progress`; `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (step 7); `--plan FILE` (the dry run as a plan `render.py FILE` runs later; refuses if an input changed). Re-encoding tools also take `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264, HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).
 
-Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) may still run ffmpeg/ffprobe — they just skip the artifact and side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per-tool: `contract --json`'s `dry_run` field.
+Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) may still run ffmpeg/ffprobe, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per tool: `contract --json` `dry_run`.
 
 ## Workflow (always follow this order)
 
@@ -96,7 +96,7 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 | "add subtitles from this SRT", "burn in captions" | `caption.py input.mp4 --srt subs.srt` |
 | "caption it with these lines" (text with times) | `caption.py input.mp4 --text cues.txt` |
 | "keep the subtitles toggleable", "mux in an SRT" | `caption.py input.mp4 --srt subs.srt --mode mux`; repeat `--srt file:lang` for several languages, `.mkv` for more than two |
-| "the captions are tiny / three lines on a Short", "don't chop the sentence" | `caption.py` shrinks the size until the cue fits `--max-lines` before splitting it (`--fit-size off` for 1.16 behaviour, `--min-size` sets the floor). Keep the template's `--max-lines` (2 on a vertical) and let the size drop; raising it to dodge a shrink stacks two words per line. A word still wider than the column at the floor is sliced at the edge (hyphen preferred), never rewritten, automatic; `broken_inside_word` in the JSON counts it |
+| "the captions are tiny / three lines on a Short", "don't chop the sentence" | `caption.py` shrinks the size until the cue fits `--max-lines` before splitting it (`--fit-size off` = 1.16 behaviour, `--min-size` the floor). Keep the template's `--max-lines` (2 on a vertical) and let the size drop; raising it to dodge a shrink stacks two words per line. A word still wider than the column at the floor is sliced at the edge (hyphen preferred), never rewritten, automatic; `broken_inside_word` in the JSON counts it |
 | "transcribe it and caption it" | `caption.py input.mp4 --transcribe --animate pop --karaoke` (needs a local whisper; else `--text`) |
 | "TikTok-style captions with the words popping" | `caption.py input.mp4 --text cues.txt --animate pop --karaoke` |
 | "our logo top-right", "a watermark" | `overlay.py input.mp4 --image logo.png --position top-right --scale 200` |
@@ -139,9 +139,9 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 | "stitch these clips", "add a crossfade" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` (TTS parts: `--list parts.txt`, `--on-missing skip`) |
 | "several changes to one edit", 3+ steps | `render.py --init project.json`, edit, `render.py project.json` |
 | "I changed one stage, don't redo the rest" | `render.py project.json --cache DIR` — identical stages reused (`--from STAGE` starts there) |
-| "open it in Premiere / Resolve / Final Cut" | `render.py project.json --export-timeline edit.fcpxml\|.edl\|.otio` — the cut as a timeline, nothing rendered; read `not_exported` |
+| "open it in Premiere / Resolve / Final Cut" | `render.py project.json --export-timeline edit.fcpxml\|.edl\|.otio` — renders nothing; read `not_exported`; no project? `--write-project` |
 | "do this to every file in the folder", "use all the cores" | `batch.py FOLDER --recipe batch.json --jobs auto` (steps or a render project; cached) |
-| "three cameras, cut between them" | `multicam.py camA.mp4 camB.mp4 camC.mp4 --switch "0-20:0,20-40:1,40-60:2"` (manual) or `--switch energy` (auto-cuts to the loudest camera, `--min-shot`, `--edl`) |
+| "three cameras, cut between them" | `multicam.py camA.mp4 camB.mp4 camC.mp4 --switch "0-20:0,20-40:1,40-60:2"` (manual) or `--switch energy` (`--min-shot`); `--edl` = cut list; editor: `--write-project p.json` → `--export-timeline` |
 | "what's in this file", "how long is it" | `probe.py input.mp4` |
 | "show me what it looks like", "are the captions readable" | `look.py output.mp4 --tiles 3x2`, then view the PNG |
 | "what would you run?", "don't render yet" | any script with `--dry-run` |

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.3`) | any release |
+| `skill.version` | the npm / package.json version (`2.2.5`) | 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.3", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.2.5", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.2.3",
+  "version": "2.2.5",
   "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`.
@@ -1053,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 %
@@ -1388,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/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/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/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())