takecheck 0.1.0__tar.gz

takecheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yqyq-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

takecheck-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: takecheck
+Version: 0.1.0
+Summary: pytest for AI-generated video: turn 'is this take usable?' into an executable spec and a CI gate.
+Author: yqyq-ai
+License: MIT
+Project-URL: Homepage, https://github.com/yqyq-ai/takecheck
+Keywords: video,qa,comfyui,generative-ai,ci
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# takecheck
+
+[![CI](https://github.com/yqyq-ai/takecheck/actions/workflows/ci.yml/badge.svg)](https://github.com/yqyq-ai/takecheck/actions/workflows/ci.yml)
+
+**pytest for AI-generated video.** Turn “is this take usable?” into an executable spec and a CI gate.
+
+> **Status: v0.1.0 — the full mechanical check set.**
+> Spec compliance plus frozen / duplicate / blank / flicker / motion / subtitle residue / audio,
+> with a self-contained HTML report. PyPI publication is pending credentials.
+
+## Why
+
+A 20-minute render should not be judged by scrubbing frames by hand. `takecheck` reads a `takes.yml`
+spec, compares the delivered file against it, and returns **pass / fail + the reason** — in seconds,
+on CPU, while the GPU is still rendering.
+
+Generation pipelines fail in ways a thumbnail cannot show: a shot freezes for 300 ms, the camera starts
+flickering, the reference clip’s burned-in subtitles survive the redraw, the audio track silently
+disappears, the last frame of segment 3 does not match the first frame of segment 4. Each is cheap to
+detect and expensive to discover after a 20-minute render — or after stitching the whole film.
+
+Existing tools do not cover this layer: VMAF/DOVER/DVQA score perceptual quality against a reference
+or a learned aesthetic prior, VideoGen-Eval is an LLM-API research harness, and ComfyUI QC nodes check
+tensors inside a graph instead of the delivered file.
+
+## Install
+
+```bash
+pip install takecheck
+```
+
+Requires `ffmpeg` / `ffprobe` on `PATH`. No PyTorch, no GPU — `numpy` is the only numeric dependency.
+
+## Quick start
+
+`takes.yml`:
+
+```yaml
+name: h3-ep12-shot03
+expect:
+  duration: 5.0
+  fps: 24
+  frames: 121
+  resolution: 1280x720
+  audio: required
+  subtitles: forbidden
+  frozen_max_ms: 200
+  black_max_frames: 0
+  flicker_max: 0.35
+  motion_min: 0.002
+```
+
+```bash
+takecheck check out/shot03.mp4 --spec takes.yml --json report.json --html report.html
+```
+
+```console
+FAIL  h3-ep12-shot03  (shot03.mp4)
+  PASS  spec      1280x720 | 24fps | 121f | 5.04s
+  FAIL  frozen    1 frozen stretch(es) over 200ms: 0.00-0.83s (longest 833ms)
+  PASS  duplicate 0/120 frames replay an earlier frame (0.0%)
+  PASS  blank     0 blank frame(s), luma 12-241
+  PASS  flicker   worst 5-frame luma swing 9/255 (3.5% <= 35%)
+  PASS  motion    mean frame-to-frame motion 0.0412 >= 0.0020
+  PASS  subtitle  no persistent text band (row contrast 1.28 < 2 on 0% of frames)
+  PASS  audio     peak -3.2 dB, -18.4 LUFS, 0% silent
+```
+
+Add `--html report.html` for a self-contained report: a contact sheet with failing moments outlined in
+red, every measured value, and the raw JSON inline. No external assets, so it can be emailed or
+attached to a PR as a single file.
+
+Exit codes: `0` pass, `1` fail, `2` bad spec / unreadable file.
+
+### What the checks measure
+
+Every check reports the numbers behind its verdict in `--json` and `--html`, not just PASS/FAIL.
+
+| Check | Signal | Fails when |
+|---|---|---|
+| `frozen` | pHash Hamming distance between consecutive frames | ≤ 3 for longer than `frozen_max_ms` |
+| `duplicate` | repeated frame hashes, ignoring neighbours, blanks and freezes | more than 1% of frames replay an earlier one |
+| `blank` | mean luma per frame | below 16 or above 240, more than `black_max_frames` |
+| `flicker` | peak-to-peak luma inside a 5-frame window | above `flicker_max` (fraction of 0–255) |
+| `motion` | mean absolute frame-to-frame difference | below `motion_min` |
+| `subtitle` | busiest row's horizontal activity ÷ that band's median row | above 2.0 on ≥ 30% of frames, when `subtitles: forbidden` |
+| `audio` | peak dBFS, EBU R128 loudness, silent fraction | peak ≥ −0.1 dBFS, or more than 60% silent |
+
+Three design choices worth knowing:
+
+- **One defect, one check.** A cut to black is reported by `blank` only; `duplicate` skips blank frames,
+  and `flicker` skips windows containing them. A freeze is reported by `frozen`, and `duplicate` ignores
+  frames a freeze already explains. A missing audio track is reported by the spec check, so `audio`
+  stays quiet about it instead of failing twice for one problem.
+- **`motion` is exempt on purpose.** It is a whole-clip aggregate ("does this clip move at all"), not an
+  event with a timestamp, so it may legitimately co-fire with a local check: a fully black clip really
+  is both blank and motionless.
+- **Thresholds are calibrated, not guessed.** `motion_min` defaults to `0.002` because a normally moving
+  clip measures ≈ 0.009 and a still render ≈ 0.000 on the bundled fixtures. Real footage differs — set
+  the values in `takes.yml` for your own pipeline.
+- **Deliberately slow shots read as still.** A clip slowed down 8x measures `mean_motion ≈ 0.0010` and
+  will fail the default `motion_min` of `0.002`. If your pipeline uses slow motion or static
+  compositions on purpose, lower `motion_min` (or set it to `0`) in `takes.yml`.
+
+### Known limitations
+
+- **The `subtitle` check has only been validated on synthetic footage.** Its fixtures use a hard white
+  bar on black. Real subtitle ghosts are semi-transparent and blurred, and a scene that legitimately
+  contains text in the lower third will trip the check. Treat the default threshold as a starting
+  point, not a calibrated value.
+- **Loudness is reported, not enforced.** Only clipping and excessive silence fail the audio check;
+  a quiet or hot mix is recorded under `measured` for you to judge.
+- **Long clips are untested.** Decoding is streamed, so memory should stay flat, but a 20-minute render
+  has not been benchmarked.
+
+## Roadmap
+
+- [x] v0.0.1 — spec format, ffprobe compliance check, CLI, `takecheck selftest`
+- [x] v0.1.0 — frozen / duplicate / blank / flicker / motion / subtitle / audio, HTML report
+- [ ] v0.1.1 — publish to PyPI (pending credentials)
+- [ ] v0.2.0 — calibration against accepted/rejected takes, head/tail continuity
+- [ ] v0.3.0 — pipeline lint (custom-node provenance, model hash pinning)
+- [ ] v0.4.0 — pluggable VLM judge
+- [ ] v0.2.0 — calibration against accepted/rejected takes, head/tail continuity
+- [ ] v0.3.0 — pipeline lint (custom-node provenance, model hash pinning)
+- [ ] v0.4.0 — pluggable VLM judge
+
+## Test media
+
+`testmedia/synthetic/` holds seven tiny clips that each reproduce exactly one defect — frozen frames,
+duplicate frames, blank frames, flicker, missing audio, burned-in subtitles — plus `good.mp4` as the
+control that must always pass. Rebuild them with:
+
+```bash
+python scripts/make_testmedia.py
+```
+
+The script also verifies each clip against its expected profile (duration, frame count, audio) and
+runs in CI, so the fixtures cannot silently rot. A second script asserts the *verdict* for each one:
+
+```bash
+python scripts/check_synthetic.py
+```
+
+It fails if `good.mp4` trips any check, or if a defect clip stops being caught — so a threshold change
+cannot quietly break detection.
+
+Real footage never goes in the repository: `testmedia/real/` is git-ignored.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+takecheck selftest            # builds synthetic clips in a temp dir; needs ffmpeg
+python scripts/check_synthetic.py
+```
+
+Note for contributors on Windows: `drawtext` needs an explicit `fontfile=`, otherwise ffmpeg aborts
+with a Fontconfig error instead of drawing anything. The test helpers search a list of common font
+paths for this reason.
+
+## 中文简介
+
+`takecheck` 是给 AI 生成视频用的**验收层**：用 `takes.yml` 声明一条片子该满足什么（时长、帧率、
+无静帧、无字幕残影、音轨完整），一条命令返回通过与否和原因，可直接当 CI 门禁。
+全程 CPU、秒级，能与渲染并行，不占显存。
+
+## License
+
+MIT.

takecheck-0.1.0/README.md

@@ -0,0 +1,171 @@
+# takecheck
+
+[![CI](https://github.com/yqyq-ai/takecheck/actions/workflows/ci.yml/badge.svg)](https://github.com/yqyq-ai/takecheck/actions/workflows/ci.yml)
+
+**pytest for AI-generated video.** Turn “is this take usable?” into an executable spec and a CI gate.
+
+> **Status: v0.1.0 — the full mechanical check set.**
+> Spec compliance plus frozen / duplicate / blank / flicker / motion / subtitle residue / audio,
+> with a self-contained HTML report. PyPI publication is pending credentials.
+
+## Why
+
+A 20-minute render should not be judged by scrubbing frames by hand. `takecheck` reads a `takes.yml`
+spec, compares the delivered file against it, and returns **pass / fail + the reason** — in seconds,
+on CPU, while the GPU is still rendering.
+
+Generation pipelines fail in ways a thumbnail cannot show: a shot freezes for 300 ms, the camera starts
+flickering, the reference clip’s burned-in subtitles survive the redraw, the audio track silently
+disappears, the last frame of segment 3 does not match the first frame of segment 4. Each is cheap to
+detect and expensive to discover after a 20-minute render — or after stitching the whole film.
+
+Existing tools do not cover this layer: VMAF/DOVER/DVQA score perceptual quality against a reference
+or a learned aesthetic prior, VideoGen-Eval is an LLM-API research harness, and ComfyUI QC nodes check
+tensors inside a graph instead of the delivered file.
+
+## Install
+
+```bash
+pip install takecheck
+```
+
+Requires `ffmpeg` / `ffprobe` on `PATH`. No PyTorch, no GPU — `numpy` is the only numeric dependency.
+
+## Quick start
+
+`takes.yml`:
+
+```yaml
+name: h3-ep12-shot03
+expect:
+  duration: 5.0
+  fps: 24
+  frames: 121
+  resolution: 1280x720
+  audio: required
+  subtitles: forbidden
+  frozen_max_ms: 200
+  black_max_frames: 0
+  flicker_max: 0.35
+  motion_min: 0.002
+```
+
+```bash
+takecheck check out/shot03.mp4 --spec takes.yml --json report.json --html report.html
+```
+
+```console
+FAIL  h3-ep12-shot03  (shot03.mp4)
+  PASS  spec      1280x720 | 24fps | 121f | 5.04s
+  FAIL  frozen    1 frozen stretch(es) over 200ms: 0.00-0.83s (longest 833ms)
+  PASS  duplicate 0/120 frames replay an earlier frame (0.0%)
+  PASS  blank     0 blank frame(s), luma 12-241
+  PASS  flicker   worst 5-frame luma swing 9/255 (3.5% <= 35%)
+  PASS  motion    mean frame-to-frame motion 0.0412 >= 0.0020
+  PASS  subtitle  no persistent text band (row contrast 1.28 < 2 on 0% of frames)
+  PASS  audio     peak -3.2 dB, -18.4 LUFS, 0% silent
+```
+
+Add `--html report.html` for a self-contained report: a contact sheet with failing moments outlined in
+red, every measured value, and the raw JSON inline. No external assets, so it can be emailed or
+attached to a PR as a single file.
+
+Exit codes: `0` pass, `1` fail, `2` bad spec / unreadable file.
+
+### What the checks measure
+
+Every check reports the numbers behind its verdict in `--json` and `--html`, not just PASS/FAIL.
+
+| Check | Signal | Fails when |
+|---|---|---|
+| `frozen` | pHash Hamming distance between consecutive frames | ≤ 3 for longer than `frozen_max_ms` |
+| `duplicate` | repeated frame hashes, ignoring neighbours, blanks and freezes | more than 1% of frames replay an earlier one |
+| `blank` | mean luma per frame | below 16 or above 240, more than `black_max_frames` |
+| `flicker` | peak-to-peak luma inside a 5-frame window | above `flicker_max` (fraction of 0–255) |
+| `motion` | mean absolute frame-to-frame difference | below `motion_min` |
+| `subtitle` | busiest row's horizontal activity ÷ that band's median row | above 2.0 on ≥ 30% of frames, when `subtitles: forbidden` |
+| `audio` | peak dBFS, EBU R128 loudness, silent fraction | peak ≥ −0.1 dBFS, or more than 60% silent |
+
+Three design choices worth knowing:
+
+- **One defect, one check.** A cut to black is reported by `blank` only; `duplicate` skips blank frames,
+  and `flicker` skips windows containing them. A freeze is reported by `frozen`, and `duplicate` ignores
+  frames a freeze already explains. A missing audio track is reported by the spec check, so `audio`
+  stays quiet about it instead of failing twice for one problem.
+- **`motion` is exempt on purpose.** It is a whole-clip aggregate ("does this clip move at all"), not an
+  event with a timestamp, so it may legitimately co-fire with a local check: a fully black clip really
+  is both blank and motionless.
+- **Thresholds are calibrated, not guessed.** `motion_min` defaults to `0.002` because a normally moving
+  clip measures ≈ 0.009 and a still render ≈ 0.000 on the bundled fixtures. Real footage differs — set
+  the values in `takes.yml` for your own pipeline.
+- **Deliberately slow shots read as still.** A clip slowed down 8x measures `mean_motion ≈ 0.0010` and
+  will fail the default `motion_min` of `0.002`. If your pipeline uses slow motion or static
+  compositions on purpose, lower `motion_min` (or set it to `0`) in `takes.yml`.
+
+### Known limitations
+
+- **The `subtitle` check has only been validated on synthetic footage.** Its fixtures use a hard white
+  bar on black. Real subtitle ghosts are semi-transparent and blurred, and a scene that legitimately
+  contains text in the lower third will trip the check. Treat the default threshold as a starting
+  point, not a calibrated value.
+- **Loudness is reported, not enforced.** Only clipping and excessive silence fail the audio check;
+  a quiet or hot mix is recorded under `measured` for you to judge.
+- **Long clips are untested.** Decoding is streamed, so memory should stay flat, but a 20-minute render
+  has not been benchmarked.
+
+## Roadmap
+
+- [x] v0.0.1 — spec format, ffprobe compliance check, CLI, `takecheck selftest`
+- [x] v0.1.0 — frozen / duplicate / blank / flicker / motion / subtitle / audio, HTML report
+- [ ] v0.1.1 — publish to PyPI (pending credentials)
+- [ ] v0.2.0 — calibration against accepted/rejected takes, head/tail continuity
+- [ ] v0.3.0 — pipeline lint (custom-node provenance, model hash pinning)
+- [ ] v0.4.0 — pluggable VLM judge
+- [ ] v0.2.0 — calibration against accepted/rejected takes, head/tail continuity
+- [ ] v0.3.0 — pipeline lint (custom-node provenance, model hash pinning)
+- [ ] v0.4.0 — pluggable VLM judge
+
+## Test media
+
+`testmedia/synthetic/` holds seven tiny clips that each reproduce exactly one defect — frozen frames,
+duplicate frames, blank frames, flicker, missing audio, burned-in subtitles — plus `good.mp4` as the
+control that must always pass. Rebuild them with:
+
+```bash
+python scripts/make_testmedia.py
+```
+
+The script also verifies each clip against its expected profile (duration, frame count, audio) and
+runs in CI, so the fixtures cannot silently rot. A second script asserts the *verdict* for each one:
+
+```bash
+python scripts/check_synthetic.py
+```
+
+It fails if `good.mp4` trips any check, or if a defect clip stops being caught — so a threshold change
+cannot quietly break detection.
+
+Real footage never goes in the repository: `testmedia/real/` is git-ignored.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+takecheck selftest            # builds synthetic clips in a temp dir; needs ffmpeg
+python scripts/check_synthetic.py
+```
+
+Note for contributors on Windows: `drawtext` needs an explicit `fontfile=`, otherwise ffmpeg aborts
+with a Fontconfig error instead of drawing anything. The test helpers search a list of common font
+paths for this reason.
+
+## 中文简介
+
+`takecheck` 是给 AI 生成视频用的**验收层**：用 `takes.yml` 声明一条片子该满足什么（时长、帧率、
+无静帧、无字幕残影、音轨完整），一条命令返回通过与否和原因，可直接当 CI 门禁。
+全程 CPU、秒级，能与渲染并行，不占显存。
+
+## License
+
+MIT.

takecheck-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "takecheck"
+version = "0.1.0"
+description = "pytest for AI-generated video: turn 'is this take usable?' into an executable spec and a CI gate."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "yqyq-ai" }]
+keywords = ["video", "qa", "comfyui", "generative-ai", "ci"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = ["PyYAML>=6.0", "numpy>=1.24"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.5"]
+
+[project.scripts]
+takecheck = "takecheck.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/yqyq-ai/takecheck"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Keep pytest's scratch dirs out of the repository root: on some Windows sandboxes the
+# system temp directory is not writable by Python, so pytest would otherwise drop a
+# `pytest-of-*` directory next to the sources. A bare relative path works because its
+# parent (the project root) always exists.
+addopts = "--basetemp=.tmp"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+# The report embeds a stylesheet as one string per rule; wrapping CSS inside a
+# Python literal hurts readability far more than a long line does.
+"src/takecheck/report.py" = ["E501"]

takecheck-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

takecheck-0.1.0/src/takecheck/__init__.py

@@ -0,0 +1,3 @@
+"""takecheck — pytest for AI-generated video."""
+
+__version__ = "0.1.0"

takecheck-0.1.0/src/takecheck/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

takecheck-0.1.0/src/takecheck/checks/__init__.py

@@ -0,0 +1,21 @@
+"""Individual checks. Each check inspects one aspect of a take."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+PASS = "pass"
+FAIL = "fail"
+WARN = "warn"
+SKIP = "skip"
+
+
+@dataclass
+class CheckResult:
+    """Outcome of a single check."""
+
+    name: str
+    status: str
+    detail: str
+    measured: dict[str, Any] = field(default_factory=dict)

takecheck-0.1.0/src/takecheck/checks/audio_check.py

@@ -0,0 +1,184 @@
+"""Audio checks: is there a track, is it audible, is it clipped, how loud?
+
+Everything here comes from ``ffmpeg`` filters that already do the measuring, so
+no audio code is decoded into Python: ``volumedetect`` gives peak and mean
+level, ``silencedetect`` gives the silent stretches, and ``ebur128`` gives the
+integrated loudness that broadcasters actually care about.
+
+Nothing in this module needs numpy.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..probe import VideoInfo
+from . import FAIL, PASS, CheckResult
+
+# A peak at or above this dBFS means the waveform is hitting the ceiling.
+CLIP_PEAK_DB = -0.1
+# Silence shorter than this is a pause, not a defect.
+MIN_SILENCE_SECONDS = 0.30
+# Silence quieter than this counts as silence.
+SILENCE_NOISE_DB = -50.0
+# More than this share of the clip being silent is a broken audio track.
+MAX_SILENT_FRACTION = 0.60
+# Integrated loudness outside this window is a mixing problem, not a defect;
+# we report it as a warning rather than failing the take.
+LOUDNESS_RANGE = (-30.0, -10.0)
+
+_MEAN_RE = re.compile(r"mean_volume:\s*(-?\d+(?:\.\d+)?) dB")
+_MAX_RE = re.compile(r"max_volume:\s*(-?\d+(?:\.\d+)?) dB")
+_SILENCE_START_RE = re.compile(r"silence_start:\s*(-?\d+(?:\.\d+)?)")
+_SILENCE_END_RE = re.compile(r"silence_end:\s*(-?\d+(?:\.\d+)?)")
+_LOUDNESS_RE = re.compile(r"^\s*I:\s*(-?\d+(?:\.\d+)?)\s*LUFS", re.MULTILINE)
+
+
+@dataclass
+class AudioStats:
+    """Raw measurements, so they can be tested without a CheckResult."""
+
+    duration: float = 0.0
+    mean_db: float | None = None
+    peak_db: float | None = None
+    loudness_lufs: float | None = None
+    silent_seconds: float = 0.0
+    silent_segments: list[tuple[float, float]] = field(default_factory=list)
+
+    @property
+    def silent_fraction(self) -> float:
+        if self.duration <= 0:
+            return 0.0
+        return min(1.0, self.silent_seconds / self.duration)
+
+
+def _ffmpeg() -> str:
+    executable = shutil.which("ffmpeg")
+    if executable is None:
+        raise RuntimeError("ffmpeg not found on PATH (install ffmpeg)")
+    return executable
+
+
+def _analyse(path: Path, duration: float) -> AudioStats:
+    """Run ffmpeg once with several measurement filters chained."""
+    filters = (
+        f"silencedetect=noise={SILENCE_NOISE_DB}dB:d={MIN_SILENCE_SECONDS},"
+        "volumedetect,ebur128"
+    )
+    cmd = [
+        _ffmpeg(),
+        "-v",
+        "info",
+        "-nostats",
+        "-i",
+        str(path),
+        "-af",
+        filters,
+        "-f",
+        "null",
+        "-",
+    ]
+    proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8", errors="replace")
+    # ffmpeg reports measurements on stderr and still exits 0 for a valid file.
+    log = proc.stderr or ""
+
+    stats = AudioStats(duration=duration)
+
+    match = _MEAN_RE.search(log)
+    if match:
+        stats.mean_db = float(match.group(1))
+    match = _MAX_RE.search(log)
+    if match:
+        stats.peak_db = float(match.group(1))
+    match = _LOUDNESS_RE.search(log)
+    if match:
+        stats.loudness_lufs = float(match.group(1))
+
+    starts = [float(value) for value in _SILENCE_START_RE.findall(log)]
+    ends = [float(value) for value in _SILENCE_END_RE.findall(log)]
+    for index, start in enumerate(starts):
+        # A still-open silence runs to the end of the file.
+        end = ends[index] if index < len(ends) else duration
+        if end > start:
+            stats.silent_segments.append((start, end))
+            stats.silent_seconds += end - start
+
+    return stats
+
+
+def check_audio(info: VideoInfo, expect) -> CheckResult:
+    """Verify the audio track exists, is audible, and is not clipped.
+
+    Presence is deliberately left to ``spec_check``: when a track is missing the
+    spec check already fails with "audio track missing", and reporting it a
+    second time here would put two red lines on one problem. This check adds
+    the measurements spec compliance does not make -- silence, clipping and
+    loudness -- and enforces ``audio: forbidden``, which only exists here.
+    """
+    mode = expect.audio or "optional"
+
+    if mode == "forbidden":
+        status = FAIL if info.has_audio else PASS
+        detail = (
+            "audio track present but forbidden"
+            if info.has_audio
+            else "no audio track, as required"
+        )
+        return CheckResult(
+            "audio",
+            status,
+            detail,
+            {"checked": True, "mode": mode, "has_audio": info.has_audio},
+        )
+
+    if not info.has_audio:
+        # Missing-track verdicts belong to ``spec`` (see the docstring).
+        return CheckResult(
+            "audio",
+            PASS,
+            "no audio track to measure (presence is checked by `spec`)",
+            {"checked": False, "mode": mode, "has_audio": False},
+        )
+
+    stats = _analyse(info.path, info.duration)
+    measured: dict[str, Any] = {
+        "checked": True,
+        "mode": mode,
+        "has_audio": True,
+        "mean_db": stats.mean_db,
+        "peak_db": stats.peak_db,
+        "loudness_lufs": stats.loudness_lufs,
+        "silent_seconds": round(stats.silent_seconds, 3),
+        "silent_fraction": round(stats.silent_fraction, 3),
+        "silent_segments": len(stats.silent_segments),
+        "max_silent_fraction": MAX_SILENT_FRACTION,
+        "clip_peak_db": CLIP_PEAK_DB,
+    }
+
+    problems: list[str] = []
+    if stats.silent_fraction > MAX_SILENT_FRACTION:
+        problems.append(
+            f"{stats.silent_fraction:.0%} of the clip is silent "
+            f"(> {MAX_SILENT_FRACTION:.0%})"
+        )
+    if stats.peak_db is not None and stats.peak_db >= CLIP_PEAK_DB:
+        problems.append(f"peak {stats.peak_db:.1f} dBFS hits the ceiling (clipping)")
+
+    if problems:
+        return CheckResult("audio", FAIL, "; ".join(problems), measured)
+
+    loudness = (
+        f", {stats.loudness_lufs:.1f} LUFS" if stats.loudness_lufs is not None else ""
+    )
+    peak = f"peak {stats.peak_db:.1f} dB" if stats.peak_db is not None else "peak unknown"
+    return CheckResult(
+        "audio",
+        PASS,
+        f"{peak}{loudness}, {stats.silent_fraction:.0%} silent",
+        measured,
+    )