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): silent entries carry at/end; --allow-silent marks a planned pause (#300)

Shogo Kajiyamaf0727a16ff15
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 985e43e..5a963a0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
## Unreleased
+- feat(join): each `silent` entry carries `at`/`end`, where that input sits in the output (seconds, transition overlap included), and `--allow-silent N[,N]` (1-based) marks a planned pause: always joined, listed with `intended: true`, no warning or note, whatever `--on-silent` says.
(nothing yet)
## 2.3.2
diff --git a/docs/contract.md b/docs/contract.md
index bac249b..101c44e 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -521,7 +521,7 @@ Per-tool keys added after 2.2.2, all additive:
| key | tool | what it holds |
|---|---|---|
| `sdr_path`, `notes` | `color.py --to-sdr` | `sdr_path` is `"tonemap"` for PQ / HLG / Dolby Vision input (and `--force` on an untagged file) or `"gamut"` for BT.2020 primaries on an SDR transfer, which is converted to BT.709 without a tone map (`--tonemap`/`--peak`/`--desat` do not apply); `notes` says which path was taken and why |
-| `silent` | `join.py` (every run) | `[{index, path, peak_db}]`: inputs whose whole-file audio peak (volumedetect) is at or below `--silence-threshold` (default -50 dBFS) and that `--on-silent warn` (default) joined anyway, with a `notes` line; `[]` otherwise. `--on-silent fail` names them in the `kind: input` refusal's `problems` (reason `silent (peak -91.0 dBFS)`), `skip` lists them under `skipped`. An input with no audio stream is never silent; `verified` is unaffected |
+| `silent` | `join.py` (every run) | `[{index, path, peak_db, at, end}]`: inputs whose whole-file audio peak (volumedetect) is at or below `--silence-threshold` (default -50 dBFS) and that `--on-silent warn` (default) joined anyway, with a `notes` line; `at`/`end` are where the input sits in the output, in seconds (a transition overlaps its neighbours). An input named by `--allow-silent N[,N]` (1-based) is a planned pause: always joined, listed with `intended: true`, no warning or note, whatever `--on-silent` says. `[]` otherwise. `--on-silent fail` names them in the `kind: input` refusal's `problems` (reason `silent (peak -91.0 dBFS)`), `skip` lists them under `skipped`. An input with no audio stream is never silent; `verified` is unaffected |
| `short_segments`, `duplicates` | `join.py` (every run) | warnings, never refusals, and the join command is unchanged: `short_segments: [{index, path, duration}]` names each measured input shorter than 2 frames at the join's fps (an audio-only join: shorter than 0.05 s); `duplicates: [{path, indices}]` names a path (compared resolved) listed more than once — repeating a clip can be intended. `[]` when none; each non-empty one adds a `notes` line |
| `silent` | `waveform.py` (every run) | `true` when the input audio's whole-file peak is at or below `--silence-threshold` (default -50 dBFS), which draws a flat line; `--on-silent warn` (default) renders it anyway with a `notes` line, `fail` refuses (`kind: input`) before ffmpeg runs. `false` when audible, `null` under `--dry-run` (nothing measured). `verified` is unaffected |
diff --git a/references/scripts.md b/references/scripts.md
index 839c060..6a2af10 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -560,7 +560,7 @@ 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] [--on-silent warn|fail|skip] [--silence-threshold -50] [...]
+join.py --list parts.txt [--on-missing fail|skip] [--on-silent warn|fail|skip] [--allow-silent N[,N]] [--silence-threshold -50] [...]
```
`--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
@@ -579,9 +579,11 @@ frame, rate or xfade offsets that rest on a pending input's unmeasured placehold
Every existing input with an audio stream is also measured (one volumedetect pass; not under `--dry-run`
too): a peak at or below `--silence-threshold` (default -50 dBFS) is silent, the trace of a TTS
call that wrote a valid but empty file. `--on-silent warn` (default) joins it and names it under
-`silent: [{index, path, peak_db}]` and in `notes`; `fail` refuses it in the same `kind: input`
-document (`silent (peak -91.0 dBFS)`); `skip` leaves it out under `skipped`. A clip without an
-audio stream is never silent.
+`silent: [{index, path, peak_db, at, end}]` (`at`/`end`: where it sits in the output, seconds)
+and in `notes`; `fail` refuses it in the same `kind: input` document (`silent (peak -91.0 dBFS)`);
+`skip` leaves it out under `skipped`. A pause that is meant to be silent: `--allow-silent 3,7`
+(1-based) joins those inputs whatever `--on-silent` says and lists them with `intended: true`,
+no warning. A clip without an audio stream is never silent.
Two warnings never refuse or change the command: `short_segments: [{index, path, duration}]`
names a clip shorter than 2 frames at the join's fps (audio-only: 0.05 s), and
`duplicates: [{path, indices}]` a path listed more than once (a repeat can be intended); both
diff --git a/scripts/_contract.py b/scripts/_contract.py
index c9e973c..9b9ac01 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -464,7 +464,7 @@ def output_schema(name: str, meta: Dict[str, Any]) -> Dict[str, Any]:
"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"},
"skipped": {"type": "array", "description": "inputs --on-missing skip left out: [{index, path, reason}] ([] when none were)"},
- "silent": {"type": "array", "description": "inputs whose audio peak is at or below --silence-threshold (default -50 dBFS) and that --on-silent warn (default) joined anyway: [{index, path, peak_db}] ([] otherwise; fail refuses them under problems, skip lists them under skipped); an input with no audio stream is never silent"},
+ "silent": {"type": "array", "description": "inputs whose audio peak is at or below --silence-threshold (default -50 dBFS) and that --on-silent warn (default) joined anyway, plus every --allow-silent input that was silent: [{index, path, peak_db, at, end, intended?}]; at/end are the input's start and end in output seconds (a transition overlaps neighbours), intended: true marks an --allow-silent input (joined whatever --on-silent says, no warning). [] otherwise; fail refuses unallowed ones under problems, skip lists them under skipped; an input with no audio stream is never silent"},
"short_segments": {"type": "array", "description": "warning, never a refusal: measured inputs shorter than 2 frames at the join's fps (audio-only join: shorter than 0.05 s), [{index, path, duration}] ([] when none), each also in notes; a pending --dry-run input is not measured"},
"duplicates": {"type": "array", "description": "warning, never a refusal (a repeat can be intended): a path (compared resolved) listed more than once and joined each time, [{path, indices}] with 0-based list positions ([] when none), also in notes"},
"pending": {"type": "array", "description": "--dry-run: inputs that do not exist yet, planned on as an earlier step's output and never also under skipped: [{index, path}] ([] otherwise)"},
diff --git a/scripts/join.py b/scripts/join.py
index bc0fb72..afb9bed 100755
--- a/scripts/join.py
+++ b/scripts/join.py
@@ -127,6 +127,7 @@ def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
n = len(args.inputs)
durs = [m.get("duration") or 0.0 for m in metas]
d = args.duration if args.transition != "none" else 0.0
+ place_silent(durs, d)
note_short_segments(args.inputs, metas, MIN_AUDIO_SEGMENT, f"{MIN_AUDIO_SEGMENT:g}s")
for p, dur in zip(args.inputs, durs):
if d and dur <= d * 2 and not STATE.dry_run:
@@ -258,6 +259,32 @@ def find_silent(paths: List[str], audible: List[int], threshold: float) -> List[
return silent
+def place_silent(lens: List[float], d: float) -> None:
+ """Where each joined silent input sits in the output: `at`/`end` in output seconds. Input k
+ (in kept order) starts after the kept inputs before it, each overlapped by the transition d."""
+ for sil in STATE_SILENT:
+ if sil["index"] not in STATE_KEPT:
+ continue
+ k = STATE_KEPT.index(sil["index"])
+ if k >= len(lens):
+ continue
+ at = sum(lens[:k]) - k * d
+ sil["at"], sil["end"] = round(at, 3), round(at + lens[k], 3)
+
+
+def parse_allow_silent(value: Optional[str], n: int) -> List[int]:
+ """--allow-silent 3,7 -> 0-based indices; each must name an input (1..n)."""
+ if not value:
+ return []
+ out = []
+ for tok in value.split(","):
+ tok = tok.strip()
+ if not tok.isdigit() or not 1 <= int(tok) <= n:
+ die(f"--allow-silent takes input numbers 1..{n} separated by commas, got {tok!r}")
+ out.append(int(tok) - 1)
+ return out
+
+
def main() -> int:
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("inputs", nargs="*", help="two or more clips in order (or --list FILE)")
@@ -270,6 +297,9 @@ def main() -> int:
help="an input whose audio peak is at or below --silence-threshold: warn (default; join it, "
"name it under `silent`), fail (refuse with the other input problems) or skip (leave it out, "
"under `skipped`); a clip with no audio stream is never silent")
+ ap.add_argument("--allow-silent", metavar="N[,N...]",
+ help="input numbers (1-based) whose silence is intended, e.g. a planned pause: always joined, "
+ "listed under `silent` with intended: true, no warning, whatever --on-silent says")
ap.add_argument("--silence-threshold", type=float, default=-50.0, metavar="DB",
help="peak level in dBFS at or below which an input counts as silent (default -50)")
ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
@@ -303,7 +333,10 @@ def main() -> int:
orig_inputs = list(args.inputs)
audible: List[int] = []
problems, pending = preflight(args.inputs, audible)
- silent = find_silent(args.inputs, audible, args.silence_threshold)
+ allowed = parse_allow_silent(args.allow_silent, len(args.inputs))
+ found = find_silent(args.inputs, audible, args.silence_threshold)
+ intended = [dict(s, intended=True) for s in found if s["index"] in allowed]
+ silent = [s for s in found if s["index"] not in allowed]
silent_problems = [{"index": s["index"], "path": s["path"], "reason": f"silent (peak {s['peak_db']:.1f} dBFS)"}
for s in silent]
refused = sorted((problems if args.on_missing == "fail" else [])
@@ -325,8 +358,8 @@ def main() -> int:
args.inputs = [p for i, p in enumerate(args.inputs) if i not in bad]
for p in dropped:
info(f"skipping #{p['index'] + 1} {p['path']}: {p['reason']}")
+ STATE_SILENT[:] = sorted(intended + (silent if args.on_silent == "warn" else []), key=lambda s: s["index"])
if silent and args.on_silent == "warn":
- STATE_SILENT[:] = silent
listing = ", ".join(f"#{s['index'] + 1} {s['path']} (peak {s['peak_db']:.1f} dBFS)" for s in silent)
info(f"warning: {len(silent)} input(s) silent at or below {args.silence_threshold:g} dBFS, joined anyway: {listing}")
STATE_NOTES.append(f"{len(silent)} input(s) have no audible sound (peak at or below {args.silence_threshold:g} dBFS) "
@@ -413,6 +446,7 @@ def main() -> int:
# a crossfaded join gives each clip one length for both streams, so the offsets that place
# every picture also place its sound; the plain cut (concat) keeps the streams paired itself
lens = [clip_length(m, fps) for m in metas] if d else durs
+ place_silent(lens, d)
for p, dur in zip(args.inputs, lens):
if d and dur <= d * 2 and not STATE.dry_run:
die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.json
index 4247b8d..b4bba55 100644
--- a/tests/fixtures/mcp_tools.json
+++ b/tests/fixtures/mcp_tools.json
@@ -559,6 +559,7 @@
{
"name": "join",
"properties": [
+ "allow_silent",
"argv",
"channels",
"codec",
diff --git a/tests/test_editing.py b/tests/test_editing.py
index d885ba0..5e8a794 100644
--- a/tests/test_editing.py
+++ b/tests/test_editing.py
@@ -1124,6 +1124,18 @@ class EditingTests(MediaFixtures):
self.assertLessEqual(doc["silent"][0]["peak_db"], -50)
self.assertTrue(any("line2.wav" in n for n in doc["notes"]))
self.assertTrue((d / "warn.wav").exists())
+ # where it sits in the output: after line1 (1.5 s), 1.5 s long
+ self.assertEqual((doc["silent"][0]["at"], doc["silent"][0]["end"]), (1.5, 3.0))
+ self.assertNotIn("intended", doc["silent"][0])
+ # --allow-silent: a planned pause, joined even under fail, marked intended, no note
+ doc = json.loads(script("join.py", "--list", d / "parts.txt", "--transition", "none", "--on-silent", "fail",
+ "--allow-silent", "2", "--json", "-o", d / "allow.wav").stdout)
+ self.assertEqual((doc["status"], doc["clips"]), ("completed", 3))
+ self.assertEqual([(s["index"], s["intended"], s["at"]) for s in doc["silent"]], [(1, True, 1.5)])
+ self.assertFalse(any("line2.wav" in n for n in doc.get("notes", [])))
+ proc = script("join.py", "--list", d / "parts.txt", "--allow-silent", "4", "--json",
+ "-o", d / "bad.wav", expect_fail=True)
+ self.assertIn("--allow-silent", json.loads(proc.stdout)["error"]["message"])
# fail: one kind-input refusal naming it, nothing written
proc = script("join.py", "--list", d / "parts.txt", "--transition", "none", "--on-silent", "fail",
"--json", "-o", d / "fail.wav", expect_fail=True)