Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
fix: caption never overwrites sidecars silently; waveform, audio, sync and render name every bad input (#292)
Shogo Kajiyamac542aa06da6e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f0aa020..971f3b4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,26 @@## Unreleased-(nothing yet)+- **caption.py: an existing `.srt`/`.ass` side file is refused without `--overwrite`**, like the+ video. Through 2.2.3 only ffmpeg's output was checked: `--transcribe` warned and then replaced+ a hand-corrected transcript, and `--text`, `--write-srt` alone, the generated/`--write-ass`+ ASS, `_adjusted.srt` and `_offset.ass` were overwritten without a word -- even by a run that+ was then refused for the existing video. Every file the run will write is now checked up+ front (kind `input`, each existing one named), before speech recognition starts and before+ the first write; the dry run predicts the same refusal. New `_common.refuse_existing_outputs()`.+- **waveform.py: `--title` and `--srt`/`--text` stages get the shared flags.** graphics.py and+ caption.py are now launched with `--overwrite`, `--timeout`, `--fast` and `--dry-run`+ forwarded (as render.py's stages are), so a second run with `--overwrite` no longer fails in+ the caption or title stage. A failed stage keeps the child's own kind and hint instead of+ always `kind: ffmpeg`; the `_vis`/`_titled` intermediates are removed on failure too; a+ missing `--srt`/`--text` file is `kind: input` before anything is encoded; and+ `--title --dry-run` completes.+- **audio.py:** `--music`, `--effects` and `--replace` files that are missing, empty, unreadable+ or have no audio stream are refused together in one `kind: input` failure with+ `problems: [{flag, path, reason}]`, before ffmpeg runs (dry run included).+- **render.py:** a real run names every unreadable clip source in its preflight refusal, not+ only the first one.+- **sync.py / multicam.py:** "not enough audio to analyse" now names the file.## 2.2.3diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 43d546c..d54f596 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -95,6 +95,13 @@ exists. When a decision changes, edit the entry in the same PR.copy-then-re-encode fallbacks) is never someone else's file. Code:`_common._check_existing_output()`. Test:`test_existing_output_is_refused_without_overwrite_and_never_for_its_own_files`.+ Side files count as outputs (2.2.4): caption.py checks the video and every `.srt`/`.ass` it+ will write (`--text`/`--transcribe`/`--write-srt`, generated or `--write-ass` ASS,+ `_offset.ass`) together before speech recognition and the first write; an `_adjusted.srt` or+ emoji-forced ASS, known only once the cues are laid out, is checked where it is written, still+ before that write. Through 2.2.3 a hand-corrected transcript was replaced on a re-run. Code:+ `_common.refuse_existing_outputs()`. Test:+ `test_caption_sidecars_are_refused_like_the_video_without_overwrite`.- **An existing output is written through a hidden sibling temp file and replaced only onsuccess**, so a failed run never costs the caller the file that was there (FFmpeg 5.x truncatesthe output before a filter error). The temp name `.<stem>.ffskill-<pid><ext>` is expected in the@@ -380,6 +387,16 @@ files by `test_docs_tool_count_matches_the_real_tool_list`. Do not re-propose it`graphics.py --template sticker` and `--srt`/`--text` runs `caption.py` on the rendered file,rather than adding drawtext or an ASS path here. One code path per job is worth two processspawns; the alternative is a second subtitle renderer that drifts from the first.+Since 2.2.4 they are launched as `render.py` launches its stages: `run_tool()` with+`child_args()` and `--json`, so `--overwrite`, `--timeout`, `--fast` and `--dry-run` reach+them, and a failed stage is re-raised with the child's own kind, exit code and hint (a private+launcher had forwarded only `--dry-run` and called every failure `kind: ffmpeg`). The `_vis` /+`_titled` intermediates are removed on the failure path too, and a missing `--srt`/`--text`+is refused before the visualisation is encoded. Under `--dry-run` only, `--title` passes+graphics.py an explicit `--end` (the source's duration) because the `_vis` file it would probe+was never written; a real run's commands are unchanged. Tests:+`test_waveform_srt_and_title_rerun_with_overwrite`, `test_waveform_title_dry_run_completes`,+`test_waveform_missing_srt_is_input_before_any_encode`.**`--auto-chapters` lives in `metadata.py`, and the detectors moved into `_common`.**`metadata.py` already owns the chapter format, the `-c copy` graph and the written-vs-asked-for@@ -706,3 +723,18 @@ not a new file format this tool would have to maintain.rates, so a project mixing source rates reads back there with gaps the file does not have(the file's offsets are rational seconds). The editor round trip is on #143's real-handschecklist.+++## 2.2.4 — the first bad input, named++- **Every bad extra input is refused together, before ffmpeg runs.** The same rule 2.2.0/2.2.1+ gave `join.py` and `render.py`: `audio.py` checks every `--replace` / `--music` / `--effects`+ file (missing, empty, unreadable, or no audio stream) and names all of them in one+ `kind: input` refusal with `problems: [{flag, path, reason}]`, under `--dry-run` too (a file+ that does not exist yet stays pending, as in join.py). `render.py`'s real run now adds the+ ffprobe readability check to its clip-source preflight, so every unreadable source is named at+ once, as its dry run already did through join; the dry run itself is unchanged. `sync.py` and+ `multicam.py` name the file that is too short to analyse. No success path's command line+ changed. Tests: `test_audio_beds_without_audio_are_refused_together`,+ `test_render_real_run_names_every_unreadable_clip_source`, `test_sync_too_short_names_the_file`,+ `test_multicam_too_short_names_the_file`.diff --git a/references/scripts.md b/references/scripts.mdindex 7fd1ac9..67787be 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -338,8 +338,10 @@ sticker template and `--srt`/`--text` burns captions by running caption.pyafterwards -- both as second processes, so neither of those code paths isre-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 isdeliberately 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 theedge, 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`) andneeds a real stereo source: it scales the side signal (L−R), so a mono trackduplicated to two channels has nothing to scale. A 1-channel input is refuseddiff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.pyindex a5a7053..6bf8d2c 100644--- a/scripts/_common/__init__.py+++ b/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",diff --git a/scripts/_common/runner.py b/scripts/_common/runner.pyindex d08b145..d2786aa 100644--- a/scripts/_common/runner.py+++ b/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")diff --git a/scripts/audio.py b/scripts/audio.pyindex 8b6d9f4..0d0f699 100755--- a/scripts/audio.py+++ b/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 osimport sysfrom pathlib import Pathfrom 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_secsVOICE_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.0has_video = bool(meta.get("video"))@@ -209,7 +252,6 @@ def main() -> int:main_src = f"0:a:{args.audio_stream}"idx = 1if 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 += 1diff --git a/scripts/caption.py b/scripts/caption.pyindex a325bc5..6522ffb 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -44,7 +44,7 @@ from typing import Any, Dict, List, Optional, Tuplefrom _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, wdiff --git a/scripts/render.py b/scripts/render.pyindex 41e2a0b..7b7f6ea 100755--- a/scripts/render.py+++ b/scripts/render.py@@ -64,7 +64,7 @@ from typing import Any, Dict, List, Optional, Sequencefrom export import PRESETS, PLATFORM_OFfrom _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_versionimport subprocessfrom _contract import CONTRACT_VERSIONfrom 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 cutparts: List[str] = []for i, c in enumerate(clips):diff --git a/scripts/sync.py b/scripts/sync.pyindex a1204e8..484793d 100755--- a/scripts/sync.py+++ b/scripts/sync.py@@ -186,7 +186,11 @@ def measure_offset(ref_path: str, oth_path: str, start: float, seconds: float, sref = 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 / SRdiff --git a/scripts/waveform.py b/scripts/waveform.pyindex 547fe6b..d96d37f 100644--- a/scripts/waveform.py+++ b/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 jsonimport os-import subprocessimport sysfrom _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platformfrom _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())diff --git a/tests/_fixtures.py b/tests/_fixtures.pyindex 328aeaa..1de4ffc 100644--- a/tests/_fixtures.py+++ b/tests/_fixtures.py@@ -59,7 +59,9 @@ def script(name, *args, **kw):# three tests), so since 2.0 refuses an existing output the helper gives the consent. What the# refusal itself does is pinned by test_contract.py's own helper, which never adds the flag.# render.py and batch.py name their outputs in the project / recipe file, not with -o.- names_output = "-o" in args or "--output" in args or name in ("render.py", "batch.py")+ # caption.py's --write-srt/--write-ass sidecars are outputs too since 2.2.4.+ names_output = ("-o" in args or "--output" in args or "--write-srt" in args or "--write-ass" in args+ or name in ("render.py", "batch.py"))if names_output and "--overwrite" not in args and "--help" not in args:args = args + ("--overwrite",)return sh(sys.executable, SCRIPTS / name, *args, **kw)diff --git a/tests/test_analysis.py b/tests/test_analysis.pyindex f4bb1e7..cc23971 100644--- a/tests/test_analysis.py+++ b/tests/test_analysis.py@@ -741,6 +741,15 @@ class AnalysisTests(MediaFixtures):self.assertIn(key, data)+ def test_sync_too_short_names_the_file(self):+ blip = OUT / "sync_blip.wav"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=d=0.1", blip)+ proc = script("sync.py", self.src, blip, "--json", expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertIn("not enough audio to analyse", doc["error"]["message"])+ self.assertIn(str(blip), doc["error"]["message"])++class ProposeChaptersTests(unittest.TestCase):"""1.16: the pure half of metadata.py --auto-chapters. No media, no subprocess."""diff --git a/tests/test_audio.py b/tests/test_audio.pyindex 185f135..192d9dd 100644--- a/tests/test_audio.py+++ b/tests/test_audio.py@@ -602,5 +602,72 @@ class AudiogramTests(MediaFixtures):self.assertNotIn("audiogram", render.expand_templates("all"))+ # ------------------------------------------------ 2.2.4: the chained stages and their inputs+ def test_waveform_srt_and_title_rerun_with_overwrite(self):+ """The sub-steps used to get only --dry-run: a second run with --overwrite failed in+ caption.py/graphics.py ("refusing to overwrite") and was reported as kind ffmpeg."""+ srt = OUT / "wf_rerun.srt"+ srt.write_text("1\n00:00:00,000 --> 00:00:01,500\nHello\n", encoding="utf-8")+ for name, extra in (("wf_rerun_srt.mp4", ("--srt", srt)), ("wf_rerun_title.mp4", ("--title", "Ep 1"))):+ out = OUT / name+ for _ in range(2):+ doc = json.loads(script("waveform.py", self.mic, "--width", "320", "--height", "180",+ *extra, "--overwrite", "--json", "-o", out).stdout)+ self.assertEqual(doc["status"], "completed")+ stem = str(out)[:-4]+ self.assertFalse(Path(stem + "_vis.mp4").exists())+ self.assertFalse(Path(stem + "_titled.mp4").exists())++ def test_waveform_missing_srt_is_input_before_any_encode(self):+ out = OUT / "wf_nosrt.mp4"+ proc = script("waveform.py", self.mic, "--srt", OUT / "no_such_cues.srt", "--json", "-o", out,+ expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["error"]["kind"], "input")+ self.assertIn("no_such_cues.srt", doc["error"]["message"])+ self.assertEqual(doc["commands"], [], "nothing was encoded")+ self.assertFalse((OUT / "wf_nosrt_vis.mp4").exists())++ def test_waveform_failed_caption_stage_keeps_child_kind_and_cleans_up(self):+ """A caption stage that fails re-raises caption.py's own kind (here: an existing output+ without --overwrite is an input refusal), and the _vis intermediate is removed."""+ srt = OUT / "wf_fail.srt"+ srt.write_text("1\n00:00:00,000 --> 00:00:01,000\nHi\n", encoding="utf-8")+ out = OUT / "wf_fail.mp4"+ out.write_bytes(b"x")+ proc = sh(sys.executable, SCRIPTS / "waveform.py", self.mic, "--width", "320", "--height", "180",+ "--srt", srt, "--json", "-o", out, expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertNotEqual(doc["error"]["kind"], "ffmpeg")+ self.assertFalse((OUT / "wf_fail_vis.mp4").exists())++ def test_waveform_title_dry_run_completes(self):+ doc = json.loads(script("waveform.py", self.mic, "--title", "Ep 1", "--dry-run", "--json",+ "-o", OUT / "wf_title_dry.mp4").stdout)+ self.assertEqual(doc["status"], "completed")+ self.assertEqual(doc["audiogram"]["stages"], ["waveform", "title"])++ def test_audio_beds_without_audio_are_refused_together(self):+ """--music / --effects files with no audio stream: one input refusal naming both, before+ ffmpeg runs -- the dry run included."""+ pics = []+ for n in ("a", "b"):+ p = OUT / f"bed_noaudio_{n}.mp4"+ if not p.exists():+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",+ "-i", "testsrc=d=1:s=160x120", "-c:v", "libx264", p)+ pics.append(p)+ for dry in ((), ("--dry-run",)):+ proc = script("audio.py", self.src, "--music", pics[0], "--effects", pics[1], "--json",+ "-o", OUT / "bed_noaudio_out.mp4", *dry, expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["error"]["kind"], "input")+ self.assertEqual([(p["flag"], p["reason"]) for p in doc["problems"]],+ [("--music", "no audio stream"), ("--effects", "no audio stream")])+ self.assertIn(str(pics[0]), doc["error"]["message"])+ self.assertIn(str(pics[1]), doc["error"]["message"])+ self.assertEqual(doc["commands"], [])++if __name__ == "__main__":unittest.main(verbosity=2)diff --git a/tests/test_orchestration.py b/tests/test_orchestration.pyindex bfffc47..610609c 100644--- a/tests/test_orchestration.py+++ b/tests/test_orchestration.py@@ -707,6 +707,31 @@ class OrchestrationTests(MediaFixtures):[(1, "missing"), (2, "empty (0 bytes)"), (3, "missing")])self.assertIn("3 of 4 clip sources unusable", proc.stderr)+ def test_render_real_run_names_every_unreadable_clip_source(self):+ """2.2.4: the real run probed sources one at a time and stopped at the first unreadable+ one; it now names every one in the same refusal as the missing/empty ones."""+ bad = []+ for n in ("a", "b"):+ p = OUT / f"render_unreadable_{n}.mp4"+ p.write_bytes(b"not a video at all")+ bad.append(p)+ body = {"clips": [{"src": "source.mp4"}, {"src": str(bad[0])}, {"src": str(bad[1])}]}+ proc = script("render.py", self._proj("render_unreadable.json", body), "--json", expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["error"]["kind"], "input")+ self.assertEqual([p["index"] for p in doc["problems"]], [1, 2])+ self.assertTrue(all(p["reason"].startswith("unreadable") for p in doc["problems"]))+ self.assertIn("2 of 3 clip sources unusable", proc.stderr)++ def test_multicam_too_short_names_the_file(self):+ blip = OUT / "mc_blip.wav"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "sine=d=0.1", blip)+ proc = script("multicam.py", self.src, blip, "--offsets-only", "--json", expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertIn("not enough audio to analyse", doc["error"]["message"])+ self.assertIn(str(blip), doc["error"]["message"])++def test_emit_and_die_use_the_ctx_they_were_given_for_the_plan(self):"""Review 9: run()/emit()/die() took ctx= but write_plan() and the atexit hook still readSTATE -- emit(ctx=...) wrote an empty plan while reporting one, and die(ctx=...) let thediff --git a/tests/test_picture.py b/tests/test_picture.pyindex dcc39eb..ef1a1ef 100644--- a/tests/test_picture.py+++ b/tests/test_picture.py@@ -1666,6 +1666,71 @@ class PictureTests(MediaFixtures):self.assertIn("no local speech-to-text engine", proc.stderr)self.assertIn("whisper", proc.stderr)+ def test_caption_sidecars_are_refused_like_the_video_without_overwrite(self):+ """caption.py's .srt/.ass sidecars go through the --overwrite check the video does, before+ speech recognition and the first write, dry runs included. Through 2.2.3 a hand-corrected+ final.srt was replaced on a re-run with the same -o, even by a run ffmpeg then refused."""+ def raw(name, *a, **kw): # script() adds --overwrite whenever -o is given+ return sh(sys.executable, SCRIPTS / name, *a, **kw)++ d = OUT / "cap_sidecar_overwrite"+ if d.exists():+ shutil.rmtree(d)+ d.mkdir(parents=True)+ cues = d / "cues.txt"+ cues.write_text("0-1.5 Hello there\n1.5-3 Second line\n", encoding="utf-8")+ out, srt, ass = d / "final.mp4", d / "final.srt", d / "final.ass"+ hand = "1\n00:00:00,000 --> 00:00:01,000\nHAND EDITED\n"++ def reset():+ for p in (out, ass):+ if p.exists():+ p.unlink()+ srt.write_text(hand, encoding="utf-8")++ # --text burning into a new video: the existing final.srt alone is enough to refuse+ reset()+ proc = raw("caption.py", self.src, "--text", cues, "-o", out, "--json", expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["error"]["kind"], "input")+ self.assertIn("refusing to overwrite", doc["error"]["message"])+ self.assertIn("final.srt", doc["error"]["message"])+ self.assertEqual(srt.read_text(encoding="utf-8"), hand, "a refused run leaves the hand edit alone")+ self.assertFalse(out.exists(), "refused before ffmpeg ran")+ # the dry run predicts the same refusal and writes nothing+ dry = raw("caption.py", self.src, "--text", cues, "-o", out, "--dry-run", "--json", expect_fail=True)+ self.assertIn("refusing to overwrite", json.loads(dry.stdout)["error"]["message"])+ # both sidecars and the video are named together+ out.write_bytes(b"x")+ ass.write_text("hand ass", encoding="utf-8")+ proc = raw("caption.py", self.src, "--text", cues, "--animate", "pop", "-o", out, "--json", expect_fail=True)+ msg = json.loads(proc.stdout)["error"]["message"]+ for name in ("final.srt", "final.ass", "final.mp4"):+ self.assertIn(name, msg)+ self.assertEqual(ass.read_text(encoding="utf-8"), "hand ass")+ self.assertEqual(srt.read_text(encoding="utf-8"), hand)+ # text-only mode (--write-srt, no video)+ reset()+ proc = raw("caption.py", "--text", cues, "--write-srt", srt, "--json", expect_fail=True)+ self.assertIn("refusing to overwrite", json.loads(proc.stdout)["error"]["message"])+ self.assertEqual(srt.read_text(encoding="utf-8"), hand)+ # --transcribe is refused before any recognition starts (with or without an engine+ # installed: the refusal, not the engine's absence, is the answer)+ proc = raw("caption.py", self.src, "--transcribe", "-o", out, "--json", expect_fail=True)+ doc = json.loads(proc.stdout)+ self.assertIn("refusing to overwrite", doc["error"]["message"])+ self.assertNotIn("speech-to-text", proc.stderr)+ self.assertEqual(doc.get("commands") or [], [])+ self.assertEqual(srt.read_text(encoding="utf-8"), hand)+ # --overwrite is the consent: the sidecar is replaced+ script("caption.py", "--text", cues, "--write-srt", srt, "--overwrite")+ self.assertIn("Hello there", srt.read_text(encoding="utf-8-sig"))+ reset()+ script("caption.py", self.src, "--text", cues, "-o", out, "--overwrite", "--fast")+ self.assertIn("Hello there", srt.read_text(encoding="utf-8-sig"))+ self.assertTrue(out.exists())+ shutil.rmtree(d)+def test_overlay_fade_without_start_end_fades_in_only(self):"""--fade without --end fades in at 0 and stays; the fade-out belongs to --end (eval 6,e03-logo: every "fade in at the start" run had to caveat an unasked-for fade-out)."""