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.

feat: join.py --list checks every segment first; --on-missing skip (#286)

Shogo Kajiyama989bb116e2a0
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index e22c20a..85ae8f6 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ffmpeg-skill",
"description": "Local FFmpeg video/audio editing for coding agents: 42 tools with a machine-readable contract, capability detection, probe-first / verify-last workflow. No cloud, no API keys.",
- "version": "2.1.0",
+ "version": "2.2.0",
"author": {
"name": "kajisho5",
"url": "https://github.com/kajisho5"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b43308f..413c297 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,17 @@
## Unreleased
-(nothing yet)
+## 2.2.0
+
+### Added
+
+- `join.py --list parts.txt` joins the segments a TTS or render step wrote, one path per line
+ (relative to the list; `#` comments and ffmpeg's `file 'x.wav'` lines accepted). Every input
+ is now checked before anything runs, and a missing, empty or unreadable one is named together
+ with every other problem in a single refusal (`kind: input`, `problems[]`) instead of being
+ found one rerun at a time; `--on-missing skip` joins the rest and lists what it left out under
+ the new `skipped` key. An empty list is refused as such. Asked for by a user whose VPS short-video
+ pipeline crashed when one TTS line failed and emptied its concat list.
## 2.1.0
diff --git a/README.md b/README.md
index 7e265d9..2a4064f 100644
--- a/README.md
+++ b/README.md
@@ -203,7 +203,7 @@ These are the rules the skill file gives the agent and the code enforces.
| Tool | What it does |
|---|---|
| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio; reports `precision`; `--snap beats` moves the in/out points onto a measured beat, or refuses when there is no measurable pulse |
-| `join.py` | Concatenate clips with xfade transitions, normalising size, fps, sample rate and channel layout (the widest clip's, or `--channels`); audio-only inputs are joined as audio |
+| `join.py` | Concatenate clips with xfade transitions, normalising size, fps, sample rate and channel layout (the widest clip's, or `--channels`); audio-only inputs are joined as audio; `--list parts.txt` reads generated segments (TTS lines) and checks every one first — missing, empty or unreadable parts are all named in one refusal, or skipped and reported with `--on-missing skip` |
| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list; `--filler` also removes filler words, but only where a speech engine timed them; `--speech-aware` keeps a breath inside a sentence and cuts only at sentence-boundary pauses, composing with `--filler` through the same `keep_ranges()` |
| `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad, crop or `--fit blur`'s blurred, darkened fill, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps |
| `crop.py` | Crop to an exact pixel rectangle (`--x --y --width --height`) — distinct from `fit.py --fit crop`, which crops to an aspect ratio it computes itself |
diff --git a/SKILL.md b/SKILL.md
index d228f05..92848a2 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -21,7 +21,7 @@ Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `chec
5. **Check the deliverable.** Before reporting, run `check.py OUTPUT --platform X` for the destination named (a template run already does). Format rows (codec, pixel format, size, true peak, colour tags, VFR) are safe to fix. Judgement rows change content: duration (cut loses material), aspect (crop loses edges), fps (drops motion), loudness (ambience must not be boosted) — fix only when the request implies the answer, else state the choice and its cost. Mention WARNs; do not chase them.
6. **Verify the output.** Confirm duration, resolution, fps and audio match the request, from the writing tool's `--json`/`--json-brief` probe or `probe.py`, and report those numbers ("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo"). A step is done only when the script exited 0 and the output probes as expected: a non-zero exit, a missing or empty file, or a probe that contradicts the request is a failure reported with the script's error message.
7. **Keep the user's originals.** Never overwrite the source; write new files next to input or where asked. An existing output path is refused (`kind: input`); `--overwrite` is the one way to say "yes, replace it".
-8. **Look at the picture.** Whenever the picture changed (captions, overlays, graphics, crop/pad, resize, colour, transitions, a `join.py` scaling a clip to the first clip's frame, `color.py --to-sdr`) run `look.py OUTPUT --tiles 3x2` (or `--at T` for one frame) and view the PNG; the full 4x3 sheet is for whole-clip layout jobs. Not finished until `Look:` names that PNG — a probe cannot see a caption on someone's face. Audio-only jobs write `Look: not needed`. What to look for splits like `check.py`'s rows in step 5:
+8. **Look at the picture.** Whenever the picture changed (captions, overlays, graphics, crop/pad, resize, colour, transitions, a `join.py` scaling a clip to the first clip's frame, `color.py --to-sdr`) run `look.py OUTPUT --tiles 3x2` (or `--at T` for one frame) and view the PNG (4x3 for whole-clip layout). Not finished until `Look:` names that PNG — a probe cannot see a caption on a face. Audio-only: `Look: not needed`. What to look for splits like `check.py`'s rows in step 5:
- **Mechanical (this skill's own job to verify and report):** the specified text/logo is at the specified position, subtitles appear at the specified timestamps, dimensions are even. Letterboxing from `fit.py --fit pad` is the *correct* result of that mode, never a defect to flag.
- **Judgement (report it, don't silently pass or fail):** whether a subject or face is cut off, text sits over a face, colours look washed out, a transition lands. These need deciding what the subject *is*, which belongs to the calling agent — say what you see in one line and let them judge it.
With no vision capability, write `Look: PATH (pixels not inspected; agent has no image view)` — never claim a picture was inspected when it wasn't, without stalling for a capability that isn't there.
@@ -136,7 +136,7 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
| "add chapters", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (`TIME TITLE` per line; streams copied; in a project: `"chapters"`). `--auto-chapters` proposes them from measured pauses/scene cuts (`Chapter N`) |
| "set the title / artist / comment" | `metadata.py episode.mp4 --title "Episode 12" --artist "Studio"` |
| "put these videos in a 4x2 grid" | `grid.py t1.mp4 ... t8.mp4 --cols 4 --rows 2` |
-| "stitch these clips", "add a crossfade" | `join.py a.mp4 b.mp4 c.mp4 --transition fade --duration 0.5` |
+| "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` |
diff --git a/docs/contract.md b/docs/contract.md
index 0d05113..1e845ea 100644
--- a/docs/contract.md
+++ b/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.1.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.2.0`) | 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.1.0", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "2.2.0", "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"},
diff --git a/docs/roadmap.md b/docs/roadmap.md
index c02bcd2..27a4024 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -17,7 +17,9 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p
- **planned** — not released. Nothing below a *planned* heading exists in any published version;
the feature lines are the intent, not a description of the code.
-The released version today is **2.1.0** — `render.py --export-timeline` hands the cut to an
+The released version today is **2.2.0** — `join.py --list` checks every TTS/render segment
+before joining and names every missing or broken one at once (`--on-missing skip` joins the
+rest). 2.1.0: `render.py --export-timeline` hands the cut to an
editor as FCPXML, CMX 3600 EDL or OpenTimelineIO (clips, speed, dissolves, music bed, chapter
markers; everything else listed as `not_exported`), plus the eval-24 follow-up that stops
`export.py` calling a BT.2020 SDR source HDR. 2.0.0 made the five changes 1.10.0 announced
diff --git a/package.json b/package.json
index 8bb18eb..c9d038d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "2.1.0",
+ "version": "2.2.0",
"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",
diff --git a/references/scripts.md b/references/scripts.md
index 1a83b1c..1b4202e 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -554,7 +554,16 @@ writes the resulting cut list exactly as it does today.
```
join.py CLIP1 CLIP2 [...] [--transition fade|dissolve|wipeleft|slideleft|fadeblack|fadewhite|circleopen|none]
[--duration 0.5] [--width W --height H] [--fps N] [--fit pad|crop] [-o OUT]
-```
+join.py --list parts.txt [--on-missing fail|skip] [...]
+```
+`--list FILE` (2.2) reads the clips from a file, one per line in order, paths relative to the
+file (blank lines and `#` comments ignored; ffmpeg's `file 'x.wav'` lines accepted), for the
+segments a TTS or render step wrote. Every input -- listed or given as arguments -- is checked
+before anything runs: missing, empty (0 bytes) or unreadable as media. By default all of them
+are named in one refusal (`kind: input`, `problems: [{index, path, reason}]`, nothing encoded);
+`--on-missing skip` joins the usable ones and reports the rest under `skipped` (always present,
+`[]` when nothing was). A list with no entries is refused as such, and a skip that leaves fewer
+than two inputs is refused rather than "joining" one file.
Normalises every clip to one frame size, fps, `yuv420p`, 48 kHz and one
channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`;
silent track generated for clips without audio), then chains `xfade` +
diff --git a/scripts/_contract.py b/scripts/_contract.py
index fa81aee..61b1300 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -453,7 +453,8 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
elif name == "join":
extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"}, "expected_duration": {"type": "number"},
"sample_rate": {"type": "integer", "description": "audio mode only"}, "channels": {"type": "integer", "description": "audio mode only"},
- "video": {"type": "boolean", "description": "false in audio mode: the output has no video stream"}}
+ "video": {"type": "boolean", "description": "false in audio mode: the output has no video stream"},
+ "skipped": {"type": "array", "description": "inputs --on-missing skip left out: [{index, path, reason}] ([] when none were)"}}
elif name == "audio":
extra = {"video": {"type": "boolean", "description": "true when the input's video stream was copied; false for an audio output extension (extraction)"},
"audio_stream": {"type": "integer", "description": "which input audio stream was processed (--audio-stream)"},
diff --git a/scripts/join.py b/scripts/join.py
index 1c05a92..9bc361f 100755
--- a/scripts/join.py
+++ b/scripts/join.py
@@ -18,16 +18,25 @@ Examples:
python3 join.py a.mov b.mp4 --transition none --width 1920 --height 1080 --fps 30
python3 join.py intro.wav talk.m4a outro.wav -o episode.flac # audio join, 0.5 s crossfade
python3 join.py part1.wav part2.wav --transition none -o full.wav # butt join, sample rate of part1
+ python3 join.py --list parts.txt --transition none -o voice.wav # the segments a TTS step wrote, in order
+ python3 join.py --list parts.txt --on-missing skip -o voice.wav # join what is there, report the rest
+
+Every input is checked before anything is joined: a missing, empty or unreadable segment is
+refused with every problem named at once (kind input), never discovered one run at a time.
+--on-missing skip joins the usable segments instead and lists the others under `skipped`.
"""
import argparse
+import os
import sys
-from typing import List
+from typing import Any, Dict, List
-from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, validate_color, X264_PRESETS, fmt_secs
+from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
"circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
LAYOUTS = {1: "mono", 2: "stereo", 6: "5.1", 8: "7.1"}
+# inputs --on-missing skip dropped, reported in the success document (empty when nothing was)
+STATE_SKIPPED: List[Dict[str, Any]] = []
def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
@@ -77,14 +86,74 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
die(f"{output} is {a.get('sample_rate')} Hz {a.get('channels')} ch, expected {rate} Hz {channels} ch")
info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{expected:.3f}s, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
+ ("crossfade" if d else "butt join") + ")")
- emit(output, mode="audio", clips=n, transition=args.transition if d else "none", expected_duration=round(expected, 3),
+ emit(output, mode="audio", skipped=list(STATE_SKIPPED), clips=n, transition=args.transition if d else "none", expected_duration=round(expected, 3),
sample_rate=rate, channels=channels, video=False)
return 0
+def read_list(path: str) -> List[str]:
+ """--list FILE: one segment per line, in order, relative to the list file's own folder.
+ Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
+ (`file 'part 01.wav'`) is accepted, so a list written for `ffmpeg -f concat` works as is."""
+ try:
+ text = open(path, encoding="utf-8").read()
+ except OSError as exc:
+ die(f"cannot read --list {path}: {exc}")
+ base = os.path.dirname(os.path.abspath(path))
+ entries: List[str] = []
+ for line in text.splitlines():
+ line = line.strip()
+ if not line or line.startswith("#"):
+ continue
+ if line.startswith("file "):
+ line = line[5:].strip()
+ if len(line) >= 2 and line[0] == line[-1] and line[0] in "'\"":
+ line = line[1:-1].replace("'\\''", "'")
+ entries.append(line if os.path.isabs(line) else os.path.join(base, line))
+ if not entries:
+ # the failure this exists for: an upstream step produced nothing, and the join must
+ # say so plainly rather than hand ffmpeg an empty concat and die somewhere later
+ die(f"--list {path} names no segments (empty, or only blank lines and comments)",
+ hint="check the step that writes the list: it produced no files")
+ return entries
+
+
+def preflight(paths: List[str]) -> List[Dict[str, Any]]:
+ """Every problem with every input, found before anything runs: missing, empty (0 bytes,
+ the usual trace of a TTS or download step that failed after creating its file), or not
+ readable as media. One ffprobe per file; nothing is decoded. Under --dry-run a file that
+ does not exist yet is not a problem: in a planned pipeline it is an earlier step's output."""
+ ffprobe = require_tool("ffprobe")
+ problems: List[Dict[str, Any]] = []
+ for i, p in enumerate(paths):
+ if not os.path.exists(p):
+ if STATE.dry_run:
+ continue # a dry-run pipeline plans on outputs earlier steps have not written yet
+ problems.append({"index": i, "path": p, "reason": "missing"})
+ continue
+ if os.path.isdir(p):
+ problems.append({"index": i, "path": p, "reason": "a directory, not a file"})
+ continue
+ if os.path.getsize(p) == 0:
+ problems.append({"index": i, "path": p, "reason": "empty (0 bytes)"})
+ continue
+ proc = run([ffprobe, "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", p],
+ 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": p, "reason": f"unreadable: {first}"})
+ return problems
+
+
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
- ap.add_argument("inputs", nargs="+", help="two or more clips in order")
+ ap.add_argument("inputs", nargs="*", help="two or more clips in order (or --list FILE)")
+ ap.add_argument("--list", metavar="FILE", help="read the clips from FILE, one per line in order (paths relative to FILE; "
+ "ffmpeg concat lines `file 'x.wav'` also accepted); an empty list is refused")
+ ap.add_argument("--on-missing", choices=["fail", "skip"], default="fail",
+ help="a missing, empty or unreadable input: fail (default; every problem named at once) or skip "
+ "(join the rest; each skipped input is reported under `skipped`)")
ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
ap.add_argument("--duration", type=float, default=0.5, help="transition length in seconds (default 0.5)")
@@ -104,8 +173,29 @@ def main() -> int:
if args.fps is not None and args.fps <= 0:
die(f"--fps must be positive, got {args.fps:g}")
+ if args.list:
+ if args.inputs:
+ die("give the clips either as arguments or with --list, not both")
+ args.inputs = read_list(args.list)
+ if not args.inputs:
+ die("give at least two clips (or --list FILE)")
+ skipped: List[Dict[str, Any]] = []
+ problems = preflight(args.inputs)
+ if problems and args.on_missing == "fail":
+ listing = "; ".join(f"#{p['index'] + 1} {p['path']}: {p['reason']}" for p in problems)
+ die(f"{len(problems)} of {len(args.inputs)} inputs cannot be joined: {listing}",
+ hint="fix or regenerate them, or pass --on-missing skip to join the rest", problems=problems)
+ if problems:
+ bad = {p["index"] for p in problems}
+ skipped = problems
+ args.inputs = [p for i, p in enumerate(args.inputs) if i not in bad]
+ for p in problems:
+ info(f"skipping #{p['index'] + 1} {p['path']}: {p['reason']}")
+ STATE_SKIPPED[:] = skipped
if len(args.inputs) < 2:
- die("give at least two clips")
+ die("give at least two clips" if not skipped else
+ f"only {len(args.inputs)} usable input(s) left after skipping {len(skipped)}; nothing to join",
+ skipped=skipped)
validate_color(args.pad_color, "--pad-color")
metas = [probe(p) for p in args.inputs]
if all(not m.get("video") for m in metas):
@@ -206,7 +296,7 @@ def main() -> int:
expected = sum(durs) - d * (n - 1)
r = probe(output, role="output")
info(f"wrote {output} ({fmt_secs(r['duration'])}, expected ~{expected:.3f}s, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
- emit(output, mode="video", clips=n, transition=args.transition, expected_duration=round(expected, 3),
+ emit(output, mode="video", skipped=list(STATE_SKIPPED), clips=n, transition=args.transition, expected_duration=round(expected, 3),
dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
return 0
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index 13877b3..c4c3e23 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -567,6 +567,8 @@
"height",
"inputs",
"json_brief",
+ "list",
+ "on_missing",
"output",
"overwrite",
"pad_color",
diff --git a/tests/test_editing.py b/tests/test_editing.py
index d0fa10b..8c41960 100644
--- a/tests/test_editing.py
+++ b/tests/test_editing.py
@@ -929,6 +929,49 @@ class EditingTests(MediaFixtures):
self.assertFalse(any("eq=brightness" in c for c in hdr_plan["commands"]),
"an HDR source must not be dimmed by an SDR-shaped eq")
+ def test_join_list_checks_every_segment_before_joining(self):
+ """Reported by a user generating shorts on a VPS: TTS writes one audio file per line,
+ a concat step joins them, and one failed TTS call left a gap that emptied the list and
+ crashed the whole run. `--list` reads the segments, and every missing, empty or
+ unreadable one is named in a single refusal (kind input, nothing run) instead of being
+ found one rerun at a time; `--on-missing skip` joins the rest and reports what it left out."""
+ d = OUT / "join_list"
+ d.mkdir(exist_ok=True)
+ for i in (1, 2, 4):
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+ "-i", f"sine=frequency={300 * i}:sample_rate=24000", "-t", "1.5", d / f"line{i}.wav")
+ (d / "line5.wav").write_bytes(b"") # a TTS call that created its file and then failed
+ (d / "line6.wav").write_bytes(b"not audio") # a download that saved an error page
+ (d / "parts.txt").write_text("line1.wav\n# the TTS step's own comment\n\nline2.wav\nline3.wav\n"
+ "file 'line4.wav'\nline5.wav\nline6.wav\n", encoding="utf-8")
+ proc = script("join.py", "--list", d / "parts.txt", "--transition", "none", "--json",
+ "-o", d / "voice_fail.wav", expect_fail=True)
+ doc = json.loads(proc.stdout)
+ self.assertEqual((doc["error"]["kind"], doc["commands"]), ("input", []))
+ self.assertEqual([(p["index"], Path(p["path"]).name) for p in doc["problems"]],
+ [(2, "line3.wav"), (4, "line5.wav"), (5, "line6.wav")], "every problem, in list order")
+ self.assertEqual([p["reason"].split(":")[0] for p in doc["problems"]], ["missing", "empty (0 bytes)", "unreadable"])
+ self.assertIn("--on-missing skip", doc["error"]["hint"])
+ self.assertFalse((d / "voice_fail.wav").exists())
+ doc = json.loads(script("join.py", "--list", d / "parts.txt", "--transition", "none", "--on-missing", "skip",
+ "--json", "-o", d / "voice.wav").stdout)
+ self.assertEqual((doc["status"], doc["clips"], doc["verified"]), ("completed", 3, True))
+ self.assertAlmostEqual(doc["probe"]["duration"], 4.5, delta=0.05)
+ self.assertEqual([Path(p["path"]).name for p in doc["skipped"]], ["line3.wav", "line5.wav", "line6.wav"])
+ # the crash itself: an upstream step wrote an empty list
+ (d / "empty.txt").write_text("\n# nothing\n", encoding="utf-8")
+ proc = script("join.py", "--list", d / "empty.txt", "-o", d / "x.wav", "--json", expect_fail=True)
+ self.assertIn("names no segments", json.loads(proc.stdout)["error"]["message"])
+ # skipping everything but one leaves nothing to join
+ (d / "one.txt").write_text("line1.wav\nline3.wav\n", encoding="utf-8")
+ proc = script("join.py", "--list", d / "one.txt", "--on-missing", "skip", "-o", d / "y.wav", "--json", expect_fail=True)
+ self.assertEqual([Path(p["path"]).name for p in json.loads(proc.stdout)["skipped"]], ["line3.wav"])
+ script("join.py", d / "line1.wav", "--list", d / "parts.txt", "-o", d / "z.wav", expect_fail=True)
+ # a clean join reports an empty skipped list, not a missing key
+ doc = json.loads(script("join.py", d / "line1.wav", d / "line2.wav", "--transition", "none",
+ "--json", "-o", d / "clean.wav").stdout)
+ self.assertEqual(doc["skipped"], [])
+
def test_join_audio_only_inputs(self):
"""WAV + M4A + MP3 of different rates and channel counts join as audio; video containers and mixed inputs are refused."""
st = OUT / "j_stereo44.m4a"