ffmpeg-skill 2.19.0 → 2.21.0

package/README.md

@@ -412,6 +412,33 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 
 Each operation is a script whose flags are its argparse parser, and that parser is what `contract --json` and the MCP `inputSchema` are built from. CI fails the build when those drift from the scripts. A caller-supplied filter graph, `-vf` string, or other ffmpeg option is not an argument any script accepts. `doctor` reads `ffmpeg -filters` (and `-encoders`, `-bsfs`) and reports a filter a tool needs before a job runs into it. MCP does accept an `argv` array, and that array is the named script's own CLI flags, still bound to that script: the script's flags, never an ffmpeg command line and never a shell.
 
+### Why 42 tools? Isn't that overkill?
+
+One tool per job, because each job promises something different, and the tool measures that promise after the run. `loudness.py` re-measures integrated loudness and true peak. `cut.py` reports how far a cut snapped to a keyframe. `silence.py` returns the ranges it kept. `export.py` checks the preset's maximum length. A value a tool cannot read fails that step as `not_measured`; it does not pass. One tool with a mode flag would need as large a schema, and its checks would be vaguer.
+
+An agent does not read 42 schemas. Over MCP, `tools/list` advertises the core 12 (bold below). The other 30 are called by name through `tools/call` when a job needs one, and `FFMPEG_SKILL_MCP_FULL=1` lists all 42. The groups are the ones in [Tools](#tools).
+
+<!-- why42:start -->
+| Group | MCP default / all | Tools |
+|---|---|---|
+| Analysis and inspection | 2 / 3 | **probe**, **look**, scenes |
+| Editing | 3 / 24 | **cut**, **fit**, **silence**, join, crop, cropdetect, deinterlace, denoise, redact, sphere, straighten, insert, background, reverse, stabilize, sequence, waveform, freeze, pad, speedramp, loop, broll, metadata, grid |
+| Audio | 2 / 3 | **audio**, **loudness**, sync |
+| Picture | 2 / 4 | **caption**, **graphics**, overlay, color |
+| Delivery | 2 / 4 | **export**, **check**, proxy, report |
+| Orchestration | 1 / 4 | **render**, batch, multicam, verify |
+| **Total** | **12 / 42** | |
+<!-- why42:end -->
+
+Without the other 30, an agent writes raw ffmpeg for those jobs, and a mistake there often still exits 0:
+
+- `stabilize.py` runs vidstab in two passes, and the second pass needs the first pass's transforms file.
+- `color.py` builds the HDR-to-SDR chain. With a wrong colour tag the run still finishes, and the picture comes out washed out.
+- `join.py` puts transitions between clips that differ in size, frame rate or audio layout. Done by hand, those clips have to be normalised first or xfade fails.
+- `sync.py` and `multicam.py` find the offset between two recordings by audio cross-correlation. No ffmpeg filter measures it.
+
+Every command a tool ran is in its `--json` `commands`, shell-quoted so it can be pasted and run again, and `--dry-run` prints the commands without running anything. In the 100-prompt agent eval (1.17.0, [Tested on real footage](#tested-on-real-footage)) the agent made no raw ffmpeg calls and reported no false successes.
+
 ### How does ffmpeg-skill compare with Remotion?
 
 ffmpeg-skill edits footage you already have, on this machine, with FFmpeg tools whose flags are a machine-readable contract (`contract --json`). Remotion renders a video from React components. They complement each other: this repository does not call Remotion, and a file Remotion writes is an ordinary input (`probe.py`, `cut.py`, `fit.py`, `export.py`, `check.py`). [`remotion-ffmpeg-skill`](https://github.com/kajisho5/remotion-ffmpeg-skill) joins the two. It measures the footage with this repo, draws the graphics in Remotion from those measurements, and checks and delivers the result with this repo again. Install both (`npx ffmpeg-skill`, then `npx remotion-ffmpeg-skill`). As with the other skills, the dependency runs one way: it calls these tools, and nothing here calls it. HyperFrames renders a video from HTML and is the same kind of neighbour: a file it writes is an ordinary input too.
@@ -614,6 +641,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
 | [SECURITY.md](SECURITY.md) | how to report a vulnerability privately |
 | [SKILL.md](SKILL.md) | what the agent reads: workflow, request → tool map, audio-only rules, report format, pitfalls |
 | [references/scripts.md](references/scripts.md) | per-flag reference for every tool |
+| [references/scripts.md § Verdict thresholds](references/scripts.md#verdict-thresholds-what-passes) | every number behind `verified` and `check.py`'s rows (tolerances, silence levels, per-platform loudness and length), each with the constant or flag it comes from |
 | [references/devices.md](references/devices.md) | real-device notes (iPhone HDR, GoPro, DJI, screen recordings) |
 | [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) | per-OS ffmpeg/CI behaviour differences already diagnosed once — read before re-diagnosing a Windows/macOS-only test failure |
 | [references/process-pitfalls.md](references/process-pitfalls.md) | process mistakes already made once (breaking a pinned test by narrowing a capability list, retrying a git/GitHub operation this environment can't do, re-designing a fixture instead of recognising a real platform difference) — a living record, add to it whenever one recurs |

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.19.0`) | any release |
+| `skill.version` | the npm / package.json version (`2.21.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`
@@ -131,7 +131,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [{"what": "running on Python 3.9 (the requirements.python floor)", "since": "2.10.9", "replacement": "Python 3.10 or later; ...", "removed_in": "3.0.0", "where": "behaviour"},
                  {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.19.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.21.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; 3.9 deprecated since 2.10.9, removed in 3.0.0; 3.10+ recommended)", "ffmpeg": ">=5.0 (5.x deprecated since 2.14.0, removed in 3.0.0; 6.1+ recommended)", "ffprobe": ">=5.0"},
@@ -699,6 +699,16 @@ from where the expected value came, and what was not measured.
 | `audio_substituted` | `join.py` (video join) | the clips that had no audio stream, whose span of the join is generated silence; `notes` says the same |
 | loudness `tolerance.tp` | `loudness.py`, `export.py`, and `check.py`'s true-peak row | the one dBTP margin every tool applies (`_platforms.TP_TOLERANCE_DB`, 0.1 dB); before 2.18 it was 0.1, 0.05 and 0.0 in the three tools |
 
+Keys added in 2.20, all additive, from the same paper's baseline experiment (each was a length or a
+silence a tool reported as fine while another measurement disagreed):
+
+| key | tool | what it holds |
+|---|---|---|
+| `verification[]` step `duration` | `export.py` (a preset with a platform maximum, without `--allow-long`) | the written file's length against the maximum, measured as `check.py` measures it (the container's duration, `tolerance` 0). A length that cannot be read fails the step with `reason: not_measured` |
+| `verification[]` step `duration` (`property: audio_duration`) | `loudness.py` | the output's sound against the input's, to one AAC frame (at least 0.03 s): a levels pass changes no timing. A length that cannot be read fails the step with `reason: not_measured` |
+| `inputs_duration`, `transition_shortening`; step `duration`'s `inputs_total` | `join.py` | the clips' own total and how much the transitions took out of it. `expected_duration` is derived from the transition the join applied, so it cannot show that on its own |
+| `silence_kinds`, `silence_breakdown` | `silence.py` | per detected silence, `digital` (at or below -90 dBFS) or `below_threshold` (quiet sound under `--threshold`), and the count and seconds of each with the level that defines it |
+
 Per-tool keys added after 2.10.11 ("nothing happens silently"), all additive:
 
 | key | tool | what it holds |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.19.0",
+  "version": "2.21.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",

package/references/scripts.md

@@ -14,7 +14,67 @@ yourself, which is the only way for a tool with no input file (`caption.py
 anywhere is `kind: input` naming the flag. Nothing else about times differs
 between tools.
 
+## Verdict thresholds (what passes)
+
+The numbers behind `verified`, `check.py`'s PASS/WARN/FAIL rows and the cuts the tools make. A
+result also carries the tolerance it used in each `verification[]` step (`tolerance`, since 2.18).
+Every row names the constant or flag it comes from, and a test holds the table to it
+(`test_the_thresholds_table_matches_the_code`).
+
+<!-- thresholds:start -->
+| what | value | source | used by |
+|---|---|---|---|
+| true peak may exceed the dBTP ceiling by | 0.1 dB | `_platforms.TP_TOLERANCE_DB` | `loudness.py`, `check.py`, `export.py` |
+| a normalised file is on its `-I` target within | 1.0 LU | `loudness.LUFS_TOLERANCE` | `loudness.py` |
+| a levels pass keeps the sound's length to (or one AAC frame, 1024 samples, if longer) | 0.03 s | `loudness.AUDIO_LENGTH_TOLERANCE` | `loudness.py` |
+| a joined picture is as long as the clips less the transitions, to (frames) | 1.5 | `join.DURATION_TOLERANCE_FRAMES` | `join.py` |
+| ... and at least | 0.05 s | `join.DURATION_TOLERANCE_MIN` | `join.py` |
+| a lossless cut may land this far from the asked time before it re-encodes | 0.5 s | `cut.py --tolerance` | `cut.py` |
+| silence is sound at or below | -35 dBFS | `silence.py --threshold` | `silence.py` |
+| ... lasting at least | 0.6 s | `silence.py --min-silence` | `silence.py` |
+| a removed silence is digital silence when 99% of it sits at or below | -90 dBFS | `silence.DIGITAL_SILENCE_DB` | `silence.py` (`silence_kinds`) |
+| a track is silent when its peak is at or below | -50 dBFS | `_common.probe.SILENT_PEAK_DBFS` | `check.py`; the `--silence-threshold` default of `join.py`, `audio.py`, `waveform.py` |
+| a filler word longer than this is a held vowel, kept | 1.2 s | `_common.decision.FILLER_MAX_WORD` | `silence.py --filler` |
+| a pause this long between two tokens of an unspaced script is a word boundary | 0.1 s | `_common.decision.FILLER_BOUNDARY_GAP` | `silence.py --filler` |
+| `--content` black: WARN above this share of the duration | 0.10 | `check.BLACK_WARN` | `check.py --content` |
+| `--content` black: FAIL at this share | 0.95 | `check.BLACK_FAIL` | `check.py --content` |
+| `--content` black: a pixel is black below this share of the luma range | 0.10 | `_common.probe.CONTENT_BLACK_PIX_TH` | `check.py --content` |
+| `--content` black: a black run shorter than this is not counted | 0.1 s | `_common.probe.CONTENT_MIN_SPAN` | `check.py --content` |
+| `--content` frozen: WARN when the longest span is above this, or above 30% | 3.0 s | `check.FROZEN_WARN_S` | `check.py --content` |
+| `--content` frozen: FAIL when one span covers this share | 0.95 | `check.FROZEN_FAIL` | `check.py --content` |
+| `--content` frozen: a picture unchanged for at least this long is frozen | 0.5 s | `_common.probe.CONTENT_FREEZE_MIN` | `check.py --content` |
+| `--content` frozen: frames this close count as unchanged (freezedetect noise) | -60 dB | `_common.probe.CONTENT_FREEZE_NOISE` | `check.py --content` |
+| `--content` silence: WARN above this share below the silent level | 0.50 | `check.SILENCE_WARN` | `check.py --content` |
+| `--content` silence: FAIL at this share | 0.95 | `check.SILENCE_FAIL` | `check.py --content` |
+| `--content` silence: a silent run shorter than this is not counted | 0.5 s | `_common.probe.CONTENT_SILENCE_MIN` | `check.py --content` |
+| `--content` dropout: a gap of sound at or below | -80 dBFS | `_common.probe.CONTENT_DROPOUT_DB` | `check.py --content` |
+| ... between (s) and 1 s long, with sound on both sides | 0.02 s | `_common.probe.CONTENT_DROPOUT_MIN` | `check.py --content` |
+| a beat grid below this confidence is not snapped to | 0.5 | `_common.decision.BEAT_MIN_CONFIDENCE` | `cut.py --snap beats`, `scenes.py --beats` |
+<!-- thresholds:end -->
+
+Delivery targets per platform (`scripts/_platforms.py`). A file passes loudness within the
+platform's tolerance of its target, and true peak at or below its ceiling plus 0.1 dB. `export.py`
+holds the written length to the maximum with no tolerance, as `check.py` does.
+
+<!-- platforms:start -->
+| platform | loudness | tolerance | true peak | max duration |
+|---|---|---|---|---|
+| `tiktok` | -14 LUFS | ±2 LU | -1 dBTP | 600 s |
+| `reels` | -14 LUFS | ±2 LU | -1 dBTP | 90 s |
+| `shorts` | -14 LUFS | ±2 LU | -1 dBTP | 180 s |
+| `youtube` | -14 LUFS | ±2 LU | -1 dBTP | 43200 s |
+| `youtube-hdr` | -14 LUFS | ±2 LU | -1 dBTP | 43200 s |
+| `youtube-av1` | -14 LUFS | ±2 LU | -1 dBTP | 43200 s |
+| `x` | -14 LUFS | ±3 LU | -1 dBTP | 140 s |
+| `linkedin` | -14 LUFS | ±3 LU | -1 dBTP | 600 s |
+| `facebook` | -14 LUFS | ±3 LU | -1 dBTP | 14400 s |
+| `podcast` | -16 LUFS | ±1 LU | -1 dBTP | — |
+| `broadcast` | -23 LUFS | ±1 LU | -1 dBTP | — |
+| `custom` | — | ±2 LU | -1 dBTP | — |
+<!-- platforms:end -->
+
 ## Contents
+- verdict thresholds — what passes, and where each number lives
 - probe.py — inspect
 - cut.py — cut / join segments
 - fit.py — target duration and/or aspect, rotate/flip

package/scripts/_common/probe.py

@@ -300,6 +300,9 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "bitrate": _to_int(audio.get("bit_rate")),
             "duration": _to_float(audio.get("duration")),
             "start_time": _to_float(audio.get("start_time")),
+            # Matroska/WebM give no stream duration, only a DURATION tag; the container's own length
+            # is the longest stream's, which is not the sound's when the picture runs longer (2.20)
+            "tagged_duration": _tag_seconds((audio.get("tags") or {}).get("DURATION")),
         }
         # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
         out["audio_streams"] = [{
@@ -497,6 +500,19 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     }
 
 
+def _tag_seconds(value: Any) -> "Optional[float]":
+    """A Matroska DURATION tag ("00:00:04.008000000") in seconds, or None."""
+    try:
+        if "-" in str(value):  # "-00:00:01": int("-00") is 0, so the sign would be lost
+            return None
+        h, m, sec = str(value).split(":")
+        seconds = int(h) * 3600 + int(m) * 60 + float(sec)
+    except (TypeError, ValueError):
+        return None
+    # float() reads "nan" and "inf": a length that is not a finite, non-negative number is none
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
 def _to_float(v: Any) -> Optional[float]:
     try:
         return float(v) if v is not None else None

package/scripts/audio.py

@@ -25,6 +25,7 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
+from _common.probe import SILENT_PEAK_DBFS
 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, measured_level_dbfs, probe, run, run_keeping_subtitles, fmt_secs
 from _common.emit import warn
 
@@ -216,7 +217,7 @@ def main() -> int:
     ap.add_argument("--on-silent", choices=["warn", "fail"], default="warn",
                     help="a --music/--replace/--effects file (or, under --duck, the voice) whose peak is at or below "
                          "--silence-threshold: warn (default: mix it, report it under `silent`) or fail (refuse before ffmpeg runs)")
-    ap.add_argument("--silence-threshold", type=float, default=-50.0, metavar="DBFS",
+    ap.add_argument("--silence-threshold", type=float, default=SILENT_PEAK_DBFS, metavar="DBFS",
                     help="peak level in dBFS at or below which a track counts as silent (default -50)")
     add_common(ap)
     args = ap.parse_args()

package/scripts/export.py

@@ -333,6 +333,20 @@ def main() -> int:
     elif platform and has_audio and args.normalize:
         spec = PLATFORMS[platform]
         notes.append(f"[dry-run] --normalize: loudness.py -I {spec['lufs']:g} --tp {spec['tp']:g} would run on the written file if it misses {platform}'s spec")
+    if p["max"] and not args.allow_long and not STATE.dry_run:
+        # the preset's length promise, measured the way check.py measures it (the container's
+        # duration, no tolerance): before 2.20 nothing re-read the length, and a --normalize pass
+        # that left the sound 0.1 s long shipped a 90.10 s Reels file as verified
+        written = probe(output, role="output").get("duration")
+        if written is not None:
+            step = {"step": "duration", "property": "duration", "ok": written <= p["max"],
+                    "expected": {"max": p["max"]}, "measured": round(written, 3),
+                    "delta": round(written - p["max"], 3), "tolerance": 0.0, "provenance": "specification"}
+        else:
+            # the preset promised a length; one that could not be read is not one that held
+            step = {"step": "duration", "property": "duration", "ok": False, "expected": {"max": p["max"]},
+                    "reason": "not_measured: the written file reports no duration"}
+        extra.setdefault("verification", []).append(step)
     if notes:
         extra["notes"] = notes
     # the delivery keeps the source's picture and, except as a GIF, its sound

package/scripts/join.py

@@ -39,6 +39,7 @@ import os
 import sys
 from typing import Any, Dict, List, Optional, Tuple
 
+from _common.probe import SILENT_PEAK_DBFS
 from _common import STATE, AUDIO_MEDIA_EXT, draws_chroma, drawn_chain, label_chain, matrix_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 from _common.emit import warn
 
@@ -50,6 +51,9 @@ STATE_SKIPPED: List[Dict[str, Any]] = []
 # --dry-run: inputs that do not exist yet, planned on as an earlier step's output
 STATE_PENDING: List[Dict[str, Any]] = []
 STATE_NOTES: List[str] = []
+# the joined picture's length against the clips' sum less the transitions: 1.5 frames, at least 0.05 s
+DURATION_TOLERANCE_FRAMES = 1.5
+DURATION_TOLERANCE_MIN = 0.05
 # --on-silent warn: inputs whose audio peak is at or below --silence-threshold, joined anyway
 STATE_SILENT: List[Dict[str, Any]] = []
 # warnings, never refusals: a clip shorter than MIN_SEGMENT_FRAMES frames (audio-only: shorter than
@@ -81,6 +85,20 @@ def unpending_length(durs: List[float], d: float) -> Optional[float]:
     return round(sum(durs) - d * (len(durs) - 1), 3)
 
 
+def overlap_report(durs: List[float], expected: Optional[float]) -> Dict[str, Any]:
+    """The clips' own total next to the joined length (2.20). The joined length is derived from
+    the transition the join itself applied, so a check against it alone cannot show that a fade
+    took time out of the material; the sum of the inputs is the yardstick the user holds."""
+    if expected is None or STATE_PENDING:
+        return {}
+    total = round(sum(durs), 3)
+    out: Dict[str, Any] = {"inputs_duration": total, "transition_shortening": round(total - expected, 3)}
+    if out["transition_shortening"] > 0.0005:
+        STATE_NOTES.append(f"the transitions overlap the clips: {fmt_secs(total)} of clips play as {fmt_secs(expected)} "
+                           f"({out['transition_shortening']:.3f} s shorter)")
+    return out
+
+
 def clip_length(meta: Dict[str, Any], fps: float) -> float:
     """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
@@ -175,7 +193,8 @@ 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_text(expected)}, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
          + ("crossfade" if d else "butt join") + ")")
-    emit(output, mode="audio", **reported(), clips=n, transition=args.transition if d else "none", expected_duration=expected,
+    overlap = overlap_report(durs, expected)
+    emit(output, mode="audio", **overlap, **reported(), clips=n, transition=args.transition if d else "none", expected_duration=expected,
          sample_rate=rate, channels=channels, video=False)
     return 0
 
@@ -301,7 +320,7 @@ def main() -> int:
     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",
+    ap.add_argument("--silence-threshold", type=float, default=SILENT_PEAK_DBFS, 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)")
     ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
@@ -564,11 +583,11 @@ def main() -> int:
     measured = (r.get("video") or {}).get("duration") or r.get("duration")
     verification = []
     if expected is not None and measured is not None and not STATE.dry_run:
-        tol = max(1.5 / fps, 0.05)
+        tol = max(DURATION_TOLERANCE_FRAMES / fps, DURATION_TOLERANCE_MIN)
         verification.append({"step": "duration", "property": "video_duration", "ok": abs(measured - expected) <= tol,
                              "measured": round(measured, 3), "expected": expected,
                              "delta": round(measured - expected, 3), "tolerance": round(tol, 3),
-                             "provenance": "input_premeasurement"})
+                             "provenance": "input_premeasurement", "inputs_total": round(sum(lens), 3)})
     # a clip with no audio stream is joined over generated silence: the join is right to do that, but
     # the report must say which clips' sound is not theirs (the paper's join finding: absence was
     # filled and nothing in the result showed it)
@@ -577,7 +596,8 @@ def main() -> int:
         STATE_NOTES.append(f"{len(substituted)} clip(s) had no audio stream; their span of the join is generated "
                            "silence: " + ", ".join(os.path.basename(p) for p in substituted))
     info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
-    emit(output, mode="video", **reported(), clips=n, transition=args.transition, expected_duration=expected,
+    overlap = overlap_report(lens, expected)
+    emit(output, mode="video", **overlap, **reported(), clips=n, transition=args.transition, expected_duration=expected,
          verification=verification, expect_streams={"video": True, "audio": True},
          audio_substituted=substituted,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))

package/scripts/loudness.py

@@ -20,6 +20,9 @@ import re
 import sys
 
 from _platforms import TP_TOLERANCE_DB
+
+AUDIO_LENGTH_TOLERANCE = 0.03  # seconds: one AAC frame at 48 kHz is 0.021 s
+LUFS_TOLERANCE = 1.0  # LU: a normalised file within this of the requested -I is on target
 from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
@@ -93,6 +96,12 @@ def main() -> int:
     bitrate = args.audio_bitrate or "192k"
 
     dropped_streams = False
+    # loudnorm emits its last block whole, and through the AAC encoder that came out as 0.1 s more
+    # sound than the input had (a 90.000 s Reels export left at 90.100 s, which check.py fails):
+    # the sound is trimmed back to the input's own length. `duration=` counts from the first sample,
+    # so sound that starts late keeps its end (`end=` is a timestamp, and cut it). atrim follows
+    # loudnorm directly: an aresample between them fails channel-layout negotiation on FFmpeg 5.1
+    in_audio = audio_length(meta)
 
     def encode(tp: float, bitrate: str) -> None:
         nonlocal dropped_streams
@@ -101,6 +110,8 @@ def main() -> int:
             f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
             f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
         )
+        if in_audio:
+            af += f",atrim=duration={float(in_audio):.6f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
         if ext in AUDIO_CODECS or not meta.get("video"):
             cmd += ["-vn"] + audio_codec_for(output, bitrate)
@@ -149,7 +160,7 @@ def main() -> int:
     if ext not in AUDIO_CODECS or "aac" in AUDIO_CODECS[ext]:
         result["audio_bitrate_used"] = bitrate
     result["encodes"] = rounds + 1
-    if not after.get("silent") and abs(float(after["input_i"]) - args.lufs) > 1.0:
+    if not after.get("silent") and abs(float(after["input_i"]) - args.lufs) > LUFS_TOLERANCE:
         result["note"] = (f"integrated loudness is {float(after['input_i']) - args.lufs:+.1f} LU from the target because the "
                           f"true-peak ceiling had to absorb the encoder's overshoot; a lossless delivery (wav/flac) or a pinned "
                           f"higher --audio-bitrate keeps both")
@@ -158,19 +169,40 @@ def main() -> int:
             f"the encoder overshoots more than the loudnorm ceiling can absorb at this bitrate",
             kind="verification", output=output, result=result,
             hint="raise --audio-bitrate (e.g. 256k) or deliver a lossless format (wav/flac) and let the platform encode")
+    verification = [{"step": "loudness",
+                     "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= LUFS_TOLERANCE and float(after["input_tp"]) <= args.tp + TP_TOLERANCE_DB),
+                     "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp,
+                     "property": "loudness", "expected": {"lufs": args.lufs, "tp_max": args.tp},
+                     "measured": {"lufs": float(after["input_i"]), "tp": float(after["input_tp"])},
+                     "delta": {"lufs": round(float(after["input_i"]) - args.lufs, 2), "tp": round(float(after["input_tp"]) - args.tp, 2)},
+                     "tolerance": {"lufs": LUFS_TOLERANCE, "tp": TP_TOLERANCE_DB}, "provenance": "user_specified"}]
+    written = probe(output, role="output")
+    out_audio = audio_length(written)
+    if in_audio and out_audio:
+        # a levels pass changes no timing: the sound is as long as the input's, to one AAC frame
+        tol = max(1024.0 / float(sr), AUDIO_LENGTH_TOLERANCE)
+        verification.append({"step": "duration", "property": "audio_duration", "ok": abs(out_audio - in_audio) <= tol,
+                             "expected": round(float(in_audio), 3), "measured": round(float(out_audio), 3),
+                             "delta": round(float(out_audio) - float(in_audio), 3), "tolerance": round(tol, 3),
+                             "provenance": "input_premeasurement"})
+    else:
+        # a length that could not be read is not a length that matched
+        verification.append({"step": "duration", "property": "audio_duration", "ok": False,
+                             "reason": "not_measured: the " + ("input" if not in_audio else "output") + " reports no duration"})
     emit(output, result=result, dropped_non_av_streams=dropped_streams,
          measured={k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset", "silent")},
-         targets={"lufs": args.lufs, "tp": args.tp, "lra": args.lra},
-         verification=[{"step": "loudness",
-                        "ok": bool(after.get("silent")) or (abs(float(after["input_i"]) - args.lufs) <= 1.0 and float(after["input_tp"]) <= args.tp + TP_TOLERANCE_DB),
-                        "lufs": float(after["input_i"]), "tp": float(after["input_tp"]), "target_lufs": args.lufs, "target_tp": args.tp,
-                        "property": "loudness", "expected": {"lufs": args.lufs, "tp_max": args.tp},
-                        "measured": {"lufs": float(after["input_i"]), "tp": float(after["input_tp"])},
-                        "delta": {"lufs": round(float(after["input_i"]) - args.lufs, 2), "tp": round(float(after["input_tp"]) - args.tp, 2)},
-                        "tolerance": {"lufs": 1.0, "tp": TP_TOLERANCE_DB}, "provenance": "user_specified"}])
+         targets={"lufs": args.lufs, "tp": args.tp, "lra": args.lra}, verification=verification)
     return 0
 
 
+def audio_length(meta: dict) -> "Optional[float]":
+    """The sound's own length: the stream's duration, else Matroska's DURATION tag. Never the
+    container's, which is the picture's when the picture runs longer (and would fail a correct
+    output against an expected length the sound never had)."""
+    audio = meta.get("audio") or {}
+    return audio.get("duration") or audio.get("tagged_duration")
+
+
 def _kbps(value: str) -> int:
     v = value.lower().rstrip("k")
     try:

package/scripts/silence.py

@@ -15,7 +15,7 @@ import argparse
 import json
 import os
 import sys
-from typing import List, Tuple
+from typing import Any, Dict, List, Tuple
 
 # `detect` moved into _common/probe.py in 1.16.0 so metadata.py --auto-chapters can measure the
 # same silences without importing this tool; the body is unchanged and the name still lives here.
@@ -44,6 +44,7 @@ def merge_spans(spans: List[Tuple[float, float]]) -> List[Tuple[float, float]]:
     return out
 
 
+DIGITAL_SILENCE_DB = -90.0  # 2.20: at or below this a span is digital silence (16-bit dither sits near -96)
 BREATH_FLOOR = 0.12  # shortest gap silencedetect is asked for under --speech-aware
 
 
@@ -255,6 +256,33 @@ def _words_from_transcript(data):
     return out, had_segments, untimed
 
 
+def silence_kinds(path: str, silences: "List[Tuple[float, float]]", duration: float,
+                  threshold: float) -> "Dict[str, Any]":
+    """Which detected silences are digital silence and which are quiet sound under the threshold
+    (2.20). Both are removed alike, but they are not the same finding: a room tone, a breath or a
+    whisper under --threshold is sound, and a report that called all of it "silence" hid that the
+    cut took audible material. One more silencedetect pass at DIGITAL_SILENCE_DB finds the digital
+    spans; a detected silence that is at least 99% digital counts as digital."""
+    if not silences or STATE.dry_run:
+        return {}
+    digital = [(s, duration if e == float("inf") else e) for s, e in detect(path, DIGITAL_SILENCE_DB, 0.02)]
+    labels, tally = [], {"digital": [0, 0.0], "below_threshold": [0, 0.0]}
+    for s, e in silences:
+        e = duration if e == float("inf") else e
+        span = max(e - s, 1e-9)
+        covered = sum(max(0.0, min(e, de) - max(s, ds)) for ds, de in digital)
+        kind = "digital" if covered / span >= 0.99 else "below_threshold"
+        labels.append(kind)
+        tally[kind][0] += 1
+        tally[kind][1] += e - s
+    return {"silence_kinds": labels,
+            "silence_breakdown": {"digital": {"count": tally["digital"][0], "seconds": round(tally["digital"][1], 3),
+                                              "level_db": DIGITAL_SILENCE_DB},
+                                  "below_threshold": {"count": tally["below_threshold"][0],
+                                                      "seconds": round(tally["below_threshold"][1], 3),
+                                                      "level_db": threshold}}}
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -344,6 +372,7 @@ def main() -> int:
     if args.filler:
         silence_keeps = keep_ranges(merge_spans(list(silences)), duration, args.margin, args.min_keep)
         silence_only = max(0.0, duration - sum(e - s for s, e in silence_keeps))
+    kinds = silence_kinds(args.input, silences, duration, args.threshold)
     summary = {
         "silences": [[round(s, 3), None if e == float("inf") else round(e, 3)] for s, e in silences],
         "keep": [[round(s, 3), round(e, 3)] for s, e in keeps],
@@ -351,6 +380,8 @@ def main() -> int:
         "kept_duration": round(kept, 3),
         "removed_seconds": round(silence_only, 3),
     }
+    if kinds:
+        summary.update(kinds)
     if args.speech_aware:
         summary["speech_aware"] = {
             "min_silence": args.min_silence, "floor": min(BREATH_FLOOR, args.min_silence),

package/scripts/waveform.py

@@ -35,6 +35,7 @@ import os
 import sys
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
+from _common.probe import SILENT_PEAK_DBFS
 from _common import (add_common, apply_common, aac_args, default_output, die, draws_chroma, emit, ffmpeg_base,
                      info, load_brand, pad_filters, probe, rgb_chain_to_bt709, run, STATE, validate_color, video_args, X264_PRESETS,
                      fmt_secs, child_args, run_tool, measured_level_dbfs)
@@ -60,7 +61,7 @@ def main() -> int:
     ap.add_argument("--on-silent", choices=["warn", "fail"], default="warn",
                     help="input audio whose peak is at or below --silence-threshold (the render would be a flat "
                          "line): warn (default: render it, report `silent: true`) or fail (refuse before ffmpeg runs)")
-    ap.add_argument("--silence-threshold", type=float, default=-50.0, metavar="DBFS",
+    ap.add_argument("--silence-threshold", type=float, default=SILENT_PEAK_DBFS, metavar="DBFS",
                     help="peak level in dBFS at or below which the input counts as silent (default -50)")
     ag = ap.add_argument_group("audiogram (1.16)",
                                "The visualisation over a picture, for an episode that has no video. The image is a "