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.

check.py --content: a dropouts row for short gaps of digital silence (#360)

Shogo Kajiyama7950f3301c8a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5ccba41..68486dd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,9 @@
## Unreleased
-(nothing yet)
+### Added
+
+- **`check.py --content` reports audio dropouts.** A new `dropouts` row counts short gaps of digital silence with sound on both sides: at or below -80 dBFS, lasting 20 ms to 1 s. These come from lost audio at a join or a glitched decode, which the silence row (a share of the running time) did not catch. It WARNs when there is any gap, and never FAILs, because a noise gate makes such gaps on purpose. The check costs one extra audio-only pass.
## 2.16.1
diff --git a/README.md b/README.md
index f731292..cae380e 100644
--- a/README.md
+++ b/README.md
@@ -259,7 +259,7 @@ These are the rules the skill file gives the agent and the code enforces.
|---|---|
| `export.py` | Presets `youtube`, `youtube4k`, `reels`, `tiktok`, `shorts`, `linkedin`, `facebook`, `x`, `youtube-hdr` (HEVC Main10, source HDR tags kept), `youtube-av1`, `prores`, `h265`, `gif`, `copy`, all tagged BT.709 unless they carry HDR (a BT.601-matrix or RGB source is converted to BT.709, not relabelled); `--normalize` meets the platform's loudness in the same call (`render.py` turns it on by default for platform presets) |
| `proxy.py` | Small, low-bitrate proxy for downstream AI analysis/preview/editing decisions — resize by `--width`/`--scale`, proxy-grade `--quality` (default 30), `--fps`, `--no-audio`; not a delivery preset |
-| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row |
+| `check.py` | PASS / WARN / FAIL against YouTube, Shorts, Reels, TikTok, X, LinkedIn, Facebook, broadcast and podcast specs, from the same delivery table the export presets and templates read (podcast also reports chapter markers and channel count), with the fix for each failure and a `format` / `judgement` kind per row; `--content` adds black-frame, frozen-frame, silence and short audio-dropout rows |
| `report.py` | Single-file HTML delivery report: before/after sheets, media facts, loudness, compliance, the commands run; `--pack` renders a social pack table |
**Orchestration**
diff --git a/demos/build.py b/demos/build.py
index ac0d755..a19a7ad 100644
--- a/demos/build.py
+++ b/demos/build.py
@@ -1662,6 +1662,11 @@ INSPECTION = [
("batch.py", "python3 scripts/batch.py ~/Footage --recipe batch.json --dry-run",
"applies one recipe to a folder with a content-hash cache, printing what it would run, "
"what it skipped as unchanged, and where each output lands."),
+ ("check.py --content", "python3 scripts/check.py final.mp4 --platform youtube --content",
+ "adds content rows to the platform check: black frames, frozen frames, the share of "
+ "silence, and short dropouts (digital silence for 20 ms to 1 s with sound on both sides, "
+ "the mark of lost audio at a join). The dropouts row lists the first five gaps' times "
+ "and lengths; a row that does not pass names a fix."),
("report.py", "python3 scripts/report.py --before raw.mov --after final.mp4 -o report.html",
"a single self-contained HTML page: before/after contact sheets, loudness, the platform "
"check table and the exact commands. It is a file to open, not a picture to embed here."),
diff --git a/docs/contract.md b/docs/contract.md
index 66158a7..9106a2f 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -205,7 +205,7 @@ rows carry `kind: format` (fix it) or `kind: judgement` (decide with the user).
The `audio` row FAILs (WARN when no loudness target applies) when the track is present but silent (peak at or below -50 dBFS, from
the loudness pass or, when loudness is skipped, one volumedetect pass). `check --content`
(opt-in; render.py `"check": {"content": true}`) adds `black`, `frozen` and `silence` rows
-from one decode pass; without it the row set is unchanged. Thresholds:
+from one decode pass, and `dropouts` (2.17) from one audio-only pass; without it the row set is unchanged. Thresholds:
`docs/design-decisions.md` ("check.py --content").
### Dry run
diff --git a/docs/demos.md b/docs/demos.md
index 59dbac1..e5444ff 100644
--- a/docs/demos.md
+++ b/docs/demos.md
@@ -758,6 +758,14 @@ python3 scripts/batch.py ~/Footage --recipe batch.json --dry-run
**No picture:** applies one recipe to a folder with a content-hash cache, printing what it would run, what it skipped as unchanged, and where each output lands.
+### check.py --content
+
+```bash
+python3 scripts/check.py final.mp4 --platform youtube --content
+```
+
+**No picture:** adds content rows to the platform check: black frames, frozen frames, the share of silence, and short dropouts (digital silence for 20 ms to 1 s with sound on both sides, the mark of lost audio at a join). The dropouts row lists the first five gaps' times and lengths; a row that does not pass names a fix.
+
### report.py
```bash
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 6f9a414..3642313 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -46,6 +46,7 @@ exists. When a decision changes, edit the entry in the same PR.
- [2.14.0 — the FFmpeg 5.x deprecation](#2140--the-ffmpeg-5x-deprecation)
- [2.15.0 — render.py's intermediate stages encode with veryfast](#2150--renderpys-intermediate-stages-encode-with-veryfast)
- [2.16.0 — intermediates at superfast, not ultrafast](#2160--intermediates-at-superfast-not-ultrafast)
+- [2.17.0 — check.py --content's dropouts row](#2170--checkpy---contents-dropouts-row)
<!-- contents:end -->
## Time limits
@@ -2093,3 +2094,18 @@ What was decided there:
ultrafast's last 4 s cost a visible step in quality, which the export cannot win back.
Test: `test_render_intermediate_stages_use_veryfast_only_before_an_encoding_export` (its name
is from 2.15; it asserts the current default).
+
+## 2.17.0 — check.py --content's dropouts row
+
+- **A dropout is a short gap of digital silence with sound on both sides, and it only WARNs.**
+ The silence row measures a share of the running time, so 0.2 s of lost audio at a join (3%
+ of a 6 s clip) passed. The new row counts gaps at or below -80 dBFS lasting 20 ms to 1 s,
+ more than 50 ms from either end. -80 dB, far below the silence row's -50 dB, keeps a
+ recording's own pauses (room tone at around -60 dB) out. A gap still open at the end is a
+ tail, and one at the very start is a lead-in. The pass pads the audio with 2 s of zeros
+ first, because audio that ends before the video would otherwise close its silent tail at
+ its own EOF, inside the container's duration, and count as a dropout. A noise gate does make such gaps on purpose,
+ which is why the row never FAILs and its fix says so. It costs one audio-only decode, because
+ a second silencedetect in the main pass logs under the same name as the silence row's, and
+ their lines could not be told apart. Code: `_common.probe._detect_dropouts()`. Test:
+ `test_check_content_dropouts_row`.
diff --git a/references/scripts.md b/references/scripts.md
index d53a93a..28566a6 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -1042,7 +1042,10 @@ pass when `--no-loudness` (or a spec with no loudness target) skips it.
`--content` (opt-in, one decode pass) adds three rows: `black` (share of the duration that is
black: WARN > 10%, FAIL >= 95%), `frozen` (longest frozen span: WARN > max(3 s, 30% of the
duration), FAIL when it covers >= 95%, i.e. the whole video) and `silence` (share below
--50 dBFS: WARN > 50%, FAIL >= 95%). A render project enables it with `"check": {"platform":
+-50 dBFS: WARN > 50%, FAIL >= 95%); since 2.17 one more audio-only pass adds `dropouts`
+(gaps of digital silence, <= -80 dBFS for 20 ms to 1 s with sound on both sides -- lost audio
+at a join, a glitched decode; WARN when there is any, never FAIL, because a noise gate makes
+them on purpose). A render project enables it with `"check": {"platform":
"reels", "content": true}`.
### batch.py — same recipe over a folder, cached
diff --git a/scripts/_common/probe.py b/scripts/_common/probe.py
index 68707a4..6114110 100644
--- a/scripts/_common/probe.py
+++ b/scripts/_common/probe.py
@@ -569,6 +569,14 @@ CONTENT_MIN_SPAN = 0.1 # blackdetect minimum run, seconds
CONTENT_FREEZE_NOISE = "-60dB" # freezedetect noise tolerance
CONTENT_FREEZE_MIN = 0.5 # freezedetect minimum run, seconds
CONTENT_SILENCE_MIN = 0.5 # silencedetect minimum run, seconds
+# 2.17: a dropout is a short run of (near) digital silence with sound on both sides -- a join
+# that lost its audio, a glitched decode. Far quieter than the silence row's -50 dB, so a
+# recording's own pauses (room tone) do not count; a noise gate does produce them, which is
+# why the row only ever WARNs.
+CONTENT_DROPOUT_DB = -80.0
+CONTENT_DROPOUT_MIN, CONTENT_DROPOUT_MAX = 0.02, 1.0 # seconds
+CONTENT_DROPOUT_EDGE = 0.05 # a gap this close to the start or end is a lead-in/out, not a dropout
+CONTENT_DROPOUT_PAD = 2.0 # zeros appended before the dropout pass; > MAX, so a tail that runs into it never counts
_BLACK_RE = re.compile(r"black_start:\s*([0-9.]+)\s+black_end:\s*([0-9.]+)")
_FREEZE_RE = re.compile(r"lavfi\.freezedetect\.freeze_(start|end):\s*([0-9.]+)")
@@ -618,9 +626,37 @@ def detect_content(path: str, duration: float, *, video: bool = True, audio: boo
if start is not None:
sil.append((start, end))
out["silence"] = sil
+ out["dropouts"] = _detect_dropouts(path, end)
return out
+def _detect_dropouts(path: str, end: float) -> "List[Tuple[float, float]]":
+ """Short (near) digital-silence gaps inside the first audio stream: one audio-only pass
+ (silencedetect at CONTENT_DROPOUT_DB). A second silencedetect in the main pass would log
+ under the same name as the silence row's, so its lines could not be told apart. The audio
+ is padded with CONTENT_DROPOUT_PAD s of zeros first: a silent tail of audio that ends before
+ the container does then runs into the pad and is too long to count, instead of closing at
+ the audio's EOF and passing the container-duration edge test."""
+ proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-i", path, "-map", "0:a:0", "-af",
+ f"apad=pad_dur={CONTENT_DROPOUT_PAD:g},"
+ f"silencedetect=noise={CONTENT_DROPOUT_DB:g}dB:d={CONTENT_DROPOUT_MIN}", "-f", "null", "-"],
+ check=False, record=True)
+ if proc.returncode != 0:
+ die(f"dropout detection failed:\n{proc.stderr.strip()[-800:]}", kind="ffmpeg")
+ gaps: "List[Tuple[float, float]]" = []
+ start = None
+ for kind, val in SIL_RE.findall(proc.stderr):
+ if kind == "start":
+ start = float(val)
+ elif start is not None:
+ s, e = start, float(val)
+ start = None
+ inside = s > CONTENT_DROPOUT_EDGE and (not end or e < end - CONTENT_DROPOUT_EDGE)
+ if inside and CONTENT_DROPOUT_MIN <= e - s <= CONTENT_DROPOUT_MAX:
+ gaps.append((s, e))
+ return gaps # a gap still open at the end is a tail, never a dropout
+
+
SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
diff --git a/scripts/check.py b/scripts/check.py
index 7bb2ce4..411beb0 100755
--- a/scripts/check.py
+++ b/scripts/check.py
@@ -20,10 +20,12 @@ Examples:
python3 check.py clip.mp4 --platform custom --max-duration 30 --aspect 1:1 --lufs -16
python3 check.py final.mp4 --platform reels --content
---content (opt-in) adds three content rows from one decode pass: black (share of the
+--content (opt-in) adds content rows from one decode pass: black (share of the
duration that is black: WARN > 10%, FAIL >= 95%), frozen (longest frozen span: WARN >
max(3 s, 30% of the duration), FAIL when the whole video is frozen) and silence (share
-below -50 dBFS: WARN > 50%, FAIL >= 95%). Without it the row set is unchanged.
+below -50 dBFS: WARN > 50%, FAIL >= 95%); and, from one more audio-only pass (2.17),
+dropouts (gaps of digital silence, <= -80 dBFS for 20 ms to 1 s with sound on both sides:
+WARN when there is any). Without it the row set is unchanged.
"""
import argparse
import json
@@ -89,7 +91,7 @@ def main() -> int:
ap.add_argument("--max-mb", type=float, help="override max file size in MB")
ap.add_argument("--no-loudness", action="store_true", help="skip the loudness measurement (faster)")
ap.add_argument("--content", action="store_true",
- help="also check the content (one decode pass): black, frozen and silence rows")
+ help="also check the content (one decode pass, plus an audio-only one): black, frozen, silence and dropouts rows")
add_common(ap)
args = ap.parse_args()
apply_common(args)
@@ -288,6 +290,14 @@ def main() -> int:
f"{share * 100:.0f}% silent", f"<= {SILENCE_WARN * 100:.0f}% below {SILENT_PEAK_DBFS:g} dBFS",
"silence.py to cut the gaps, or audio.py --replace when the track is empty",
reason="most of the running time has no audible sound")
+ if "dropouts" in cd:
+ gaps = cd["dropouts"]
+ at = ", ".join(f"{s:.2f}s ({(e - s) * 1000:.0f} ms)" for s, e in gaps[:5]) + (" ..." if len(gaps) > 5 else "")
+ row("dropouts", "WARN" if gaps else "PASS", f"{len(gaps)}" + (f": {at}" if gaps else ""),
+ "no digital-silence gap under 1 s with sound on both sides",
+ "listen at those times: a gap at a cut or join is lost audio (re-cut with cut.py --accurate, or join.py "
+ "again); a noise gate makes these on purpose" if gaps else "",
+ reason="a short stretch of digital silence in the middle of the sound is usually lost audio at a join or a glitched decode" if gaps else "")
failed = [r for r in rows if r["status"] == "FAIL"]
warned = [r for r in rows if r["status"] == "WARN"]
diff --git a/tests/test_analysis.py b/tests/test_analysis.py
index b9ba712..fc9c102 100644
--- a/tests/test_analysis.py
+++ b/tests/test_analysis.py
@@ -303,7 +303,7 @@ class AnalysisTests(MediaFixtures):
"-f", "lavfi", "-i", tone + ",volume=enable='gte(t,2)':volume=0", "-t", "6",
"-pix_fmt", "yuv420p", "-c:v", "libx264", "-c:a", "aac", mixed)
r = self._rows(normal, "--content")
- self.assertEqual([r[k]["status"] for k in ("black", "frozen", "silence")], ["PASS"] * 3, r)
+ self.assertEqual([r[k]["status"] for k in ("black", "frozen", "silence", "dropouts")], ["PASS"] * 4, r)
self.assertEqual(self._rows(black, "--content")["black"]["status"], "FAIL")
self.assertEqual(self._rows(frozen, "--content")["frozen"]["status"], "FAIL")
self.assertEqual(self._rows(part, "--content")["frozen"]["status"], "WARN")
@@ -311,6 +311,33 @@ class AnalysisTests(MediaFixtures):
r = self._rows(mixed, "--content")
self.assertEqual((r["black"]["status"], r["silence"]["status"]), ("WARN", "WARN"), r)
+ def test_check_content_dropouts_row(self):
+ """2.17: a short run of digital silence with sound on both sides (lost audio at a join) is a
+ dropouts WARN; the same gap holding -60 dB room tone is a recording's pause and PASSes, and
+ a silent lead-in or tail is not a dropout, also when the audio ends before the video. The
+ silence row (share below -50 dB) misses all three: 0.2 s of 6 s is 3%."""
+ def clip(name, audio_graph):
+ path = OUT / name
+ if not path.exists():
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=gray:s=64x64:r=10:d=6",
+ "-f", "lavfi", "-i", "sine=f=440:d=6", "-f", "lavfi", "-i", "anoisesrc=a=0.001:d=6",
+ "-filter_complex", audio_graph, "-map", "0:v", "-map", "[a]", "-c:v", "libx264", "-c:a", "aac", "-t", "6", path)
+ return path
+ gap = "volume='if(between(t,2,2.2),0,1)':eval=frame"
+ dropped = clip("dropout_gap.mp4", f"[1]{gap}[a]")
+ room = clip("dropout_roomtone.mp4", f"[1]{gap}[t];[t][2]amix=inputs=2:normalize=0[a]")
+ edges = clip("dropout_edges.mp4", "[1]volume='if(lt(t,0.5)+gt(t,5.5),0,1)':eval=frame[a]")
+ # audio 2 s shorter than the video, its last 0.2 s silent: silencedetect closes that tail at
+ # the audio's EOF, well inside the container's 6 s, so only the padded pass keeps it a tail
+ short = clip("dropout_short_audio.mp4", "[1]atrim=0:4,volume='if(gt(t,3.8),0,1)':eval=frame[a]")
+ r = self._rows(dropped, "--content")
+ self.assertEqual((r["silence"]["status"], r["dropouts"]["status"]), ("PASS", "WARN"), r)
+ self.assertTrue(r["dropouts"]["value"].startswith("1: 2."), r["dropouts"])
+ self.assertIn("join", r["dropouts"]["fix"])
+ self.assertEqual(self._rows(room, "--content")["dropouts"]["status"], "PASS")
+ self.assertEqual(self._rows(edges, "--content")["dropouts"]["status"], "PASS")
+ self.assertEqual(self._rows(short, "--content")["dropouts"]["status"], "PASS")
+
def test_check_colour_row_reads_the_matrix_tag(self):
"""#325: the colour row decided "untagged" from primaries and transfer only, so a file whose
only tag is a BT.601 matrix passed as "untagged (players assume bt709)" while a tag-honouring