Skip to content

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.

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.md
index 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.3
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 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 on
success**, so a failed run never costs the caller the file that was there (FFmpeg 5.x truncates
the 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 process
spawns; 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-hands
checklist.
+
+
+## 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.md
index 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.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
diff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.py
index 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.py
index 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.py
index 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 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
diff --git a/scripts/caption.py b/scripts/caption.py
index a325bc5..6522ffb 100755
--- a/scripts/caption.py
+++ b/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
diff --git a/scripts/render.py b/scripts/render.py
index 41e2a0b..7b7f6ea 100755
--- a/scripts/render.py
+++ b/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):
diff --git a/scripts/sync.py b/scripts/sync.py
index 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, 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
diff --git a/scripts/waveform.py b/scripts/waveform.py
index 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 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())
diff --git a/tests/_fixtures.py b/tests/_fixtures.py
index 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.py
index 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.py
index 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.py
index 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 read
STATE -- emit(ctx=...) wrote an empty plan while reporting one, and die(ctx=...) let the
diff --git a/tests/test_picture.py b/tests/test_picture.py
index 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)."""