ffmpeg-skill 2.3.2 → 2.4.1

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.3.2`) | any release |
+| `skill.version` | the npm / package.json version (`2.4.1`) | 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.3.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.4.1", "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"},
@@ -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 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/scripts.md

@@ -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
@@ -589,10 +591,10 @@ are always present (`[]` when none) and noted.
 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` +
-`acrossfade`. With a transition each clip has one length for picture and sound
+`acrossfade` (or `concat` for `--transition none`). Every clip has one length for picture and sound
 -- the video stream's, or the audio's when it runs more than a frame longer --
 and the shorter stream is padded (silence / last frame held), so every clip's
-sound stays with its picture. Output length = sum of clip lengths −
+sound stays with its picture and a plain cut leaves no hole in the video. Output length = sum of clip lengths −
 transition × (n−1); `verified` checks the output's video-stream length against it. Clips must be
 longer than 2 × the transition. Use `--transition none` for a plain cut.
 A subtitle/data track in the source is not carried into the retimed/concatenated

package/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)"},

package/scripts/join.py

@@ -81,7 +81,7 @@ def unpending_length(durs: List[float], d: float) -> Optional[float]:
 
 
 def clip_length(meta: Dict[str, Any], fps: float) -> float:
-    """The one length a clip holds in a crossfaded join, for its picture and its sound alike: the
+    """The one length a clip holds in a join, for its picture and its sound alike: the
     video stream's, or the audio stream's when the sound runs more than a frame past the picture
     (narration is never cut; an AAC tail adds no frame). The container duration (audio priming,
     a longer track) is only the fallback when a stream length is unknown (a pending input)."""
@@ -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) "
@@ -410,9 +443,13 @@ def main() -> int:
     note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
     durs = [m.get("duration") or 0.0 for m in metas]
     d = args.duration if args.transition != "none" else 0.0
-    # 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
+    # every clip gets one length for both streams, so whatever places the next clip -- xfade's
+    # offsets, or the concat filter, which starts it after the LONGER stream of this one -- places
+    # its picture and its sound together. The plain cut used to take the raw streams, and a sound
+    # past the picture (a music bed padded to the container, even a 20 ms AAC tail) left a hole in
+    # the video there.
+    lens = [clip_length(m, fps) for m in metas]
+    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")
@@ -463,18 +500,17 @@ def main() -> int:
         parts.append(f"[{i}:v]{geo},setsar=1,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
         parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]")
 
+    # pad the shorter stream to the clip's length: the audio with silence, the picture by holding
+    # its last frame, then cut both there -- each clip boundary is then the same for both chains
+    for i in range(n):
+        vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
+        hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
+        parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
+        parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
     if args.transition == "none":
-        chain = "".join(f"[v{i}][a{i}]" for i in range(n))
+        chain = "".join(f"[vp{i}][ap{i}]" for i in range(n))
         parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
     else:
-        # pad the shorter stream to the clip's length: the audio with silence, the picture by
-        # holding its last frame, then cut both there -- each xfade and acrossfade then starts
-        # at the same clip boundary instead of the audio chain drifting by every clip's gap
-        for i in range(n):
-            vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
-            hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
-            parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
-            parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
         vprev, aprev = "vp0", "ap0"
         offset = 0.0
         for i in range(1, n):
@@ -495,11 +531,11 @@ def main() -> int:
                            "by its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
     cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
-    if d:
-        # the fps filter already made the picture constant-rate and xfade places every frame: FFmpeg
-        # 5.1's default cfr output mode still duplicated the last one to meet the AAC tail (a 51-frame
-        # dissolve came out 52), which newer builds no longer do -- pass the frames through as built
-        cmd += ["-fps_mode", "passthrough"]
+    # the fps filter already made the picture constant-rate, and the per-clip trims (then xfade or
+    # concat) place every frame: FFmpeg 5.1's default cfr output mode still duplicated the last one
+    # to meet the AAC tail (a 51-frame dissolve came out 52), which newer builds no longer do -- pass
+    # the frames through as built, for a plain cut as much as for a transition
+    cmd += ["-fps_mode", "passthrough"]
     cmd += video_args(hdr_meta or metas[0], args.crf, args.preset) + aac_args() + [output]
     run(cmd)
     expected = unpending_length(lens, d)