takecheck 0.1.0__py3-none-any.whl

takecheck/__init__.py

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

takecheck/__main__.py

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

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/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,
+    )

takecheck/checks/frame_checks.py

@@ -0,0 +1,302 @@
+"""Frame-level checks: frozen, duplicate, blank, flicker, motion.
+
+All five read the same decoded clip (see :mod:`takecheck.clip`), so adding them
+costs no extra ffmpeg pass. Every check reports the numbers it measured, not
+just a verdict -- a failing run has to explain itself.
+
+**Localised defects are attributed to exactly one check.** ``frozen``,
+``duplicate``, ``blank`` and ``flicker`` all describe an event at a specific
+time, so they must not report the same event: a black stretch is ``blank``
+only, a freeze is ``frozen`` only, and ``duplicate``/``flicker`` skip blank
+frames and frozen stretches. Otherwise one bad moment would produce four red
+lines and bury the actual diagnosis.
+
+``motion`` is deliberately outside that rule: it is a whole-clip aggregate
+("does this clip move at all over its length"), not an event with a timestamp,
+so it answers a different question. A fully black clip genuinely is both blank
+*and* motionless, and reporting both is accurate rather than redundant.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ..clip import Clip
+from ..spec import Expect
+from . import FAIL, PASS, CheckResult
+
+# Two consecutive frames count as "the same picture" at or below this pHash
+# Hamming distance (0 = identical, 64 = nothing in common).
+FROZEN_HASH_DISTANCE = 3
+# A freeze has to last at least this many frames before it is even considered,
+# so that a single skipped frame is not reported as a still stretch.
+FROZEN_MIN_FRAMES = 5
+# Frames closer together than this are neighbours, not duplicates: immediate
+# repeats are what ``frozen`` is for.
+DUPLICATE_MIN_GAP = 5
+# Share of comparable frames allowed to be repeats before the clip is rejected.
+DUPLICATE_MAX_RATIO = 0.01
+# Mean luma below/above these is treated as a black or blown-out frame.
+BLANK_DARK = 16.0
+BLANK_BRIGHT = 240.0
+# Sliding window (frames) used for the flicker extreme-range measurement.
+FLICKER_WINDOW = 5
+
+
+def _runs(mask: np.ndarray, min_len: int) -> list[tuple[int, int]]:
+    """Return ``(start, end)`` index pairs for runs of ``True`` >= ``min_len``.
+
+    ``end`` is inclusive, in the index space of ``mask``.
+    """
+    if mask.size == 0:
+        return []
+    padded = np.concatenate(([False], mask, [False]))
+    edges = np.flatnonzero(padded[1:] != padded[:-1])
+    runs = [(int(a), int(b - 1)) for a, b in zip(edges[::2], edges[1::2], strict=False)]
+    return [run for run in runs if run[1] - run[0] + 1 >= min_len]
+
+
+def _fmt_ranges(ranges: list[tuple[float, float]], limit: int = 3) -> str:
+    shown = ", ".join(f"{a:.2f}-{b:.2f}s" for a, b in ranges[:limit])
+    if len(ranges) > limit:
+        shown += f", +{len(ranges) - limit} more"
+    return shown
+
+
+def _seconds(pairs: list[tuple[int, int]], fps: float) -> list[tuple[float, float]]:
+    return [(a / fps, (b + 1) / fps) for a, b in pairs]
+
+
+def frozen_runs(clip: Clip, expect: Expect) -> list[tuple[int, int]]:
+    """Frame index ranges that count as a freeze, inclusive.
+
+    Indices refer to frames, not to the ``hash_delta`` array.
+
+    Blank frames are excluded: a stretch of pure black is a *blank* defect, and
+    it would otherwise be reported here as well, double-counting one problem.
+    """
+    if clip.count < FROZEN_MIN_FRAMES:
+        return []
+    # One entry per adjacent pair, so pair i compares frame i and frame i+1.
+    still = clip.metrics.hash_delta <= FROZEN_HASH_DISTANCE
+    luma = clip.metrics.luma
+    blank = (luma < BLANK_DARK) | (luma > BLANK_BRIGHT)
+    # Drop pairs where either frame is blank, so a run cannot span black frames.
+    still &= ~blank[:-1] & ~blank[1:]
+    allowed = int(round(clip.ms_to_frames(expect.frozen_max_ms)))
+    # A run of N pairs spans N+1 frames, so require N+1 > allowed.
+    min_pairs = max(FROZEN_MIN_FRAMES - 1, allowed)
+    return [(start, end + 1) for start, end in _runs(still, min_pairs)]
+
+
+def check_frozen(clip: Clip, expect: Expect) -> CheckResult:
+    """Flag stretches where nothing moves for longer than ``frozen_max_ms``."""
+    runs = frozen_runs(clip, expect)
+    longest_frames = max((end - start + 1 for start, end in runs), default=0)
+
+    measured: dict[str, Any] = {
+        "longest_run_ms": round(clip.ms(longest_frames), 1),
+        "frozen_runs": len(runs),
+        "allowed_ms": expect.frozen_max_ms,
+        "hash_distance": FROZEN_HASH_DISTANCE,
+        "total_frames": clip.count,
+    }
+    if not runs:
+        return CheckResult(
+            "frozen",
+            PASS,
+            f"longest still stretch {measured['longest_run_ms']:.0f}ms "
+            f"(limit {expect.frozen_max_ms}ms)",
+            measured,
+        )
+
+    ranges = _seconds(runs, clip.fps)
+    measured["ranges"] = [[round(a, 3), round(b, 3)] for a, b in ranges]
+    detail = (
+        f"{len(runs)} frozen stretch(es) over {expect.frozen_max_ms}ms: "
+        f"{_fmt_ranges(ranges)} (longest {measured['longest_run_ms']:.0f}ms)"
+    )
+    return CheckResult("frozen", FAIL, detail, measured)
+
+
+def check_duplicate(clip: Clip, expect: Expect) -> CheckResult:
+    """Flag frames that replay an earlier frame after the picture has moved on.
+
+    Blank frames and frames inside a freeze are skipped: those are reported by
+    ``blank`` and ``frozen``, and counting them here would report one defect
+    three times over.
+    """
+    hashes = clip.metrics.hashes
+    luma = clip.metrics.luma
+    total = len(hashes)
+    if total == 0:
+        return CheckResult("duplicate", FAIL, "no frames decoded", {"total_frames": 0})
+
+    usable = (luma >= BLANK_DARK) & (luma <= BLANK_BRIGHT)
+    for start, end in frozen_runs(clip, expect):
+        usable[start : end + 1] = False
+
+    repeats: list[int] = []
+    seen: dict[int, int] = {}
+    for index in range(total):
+        if not usable[index]:
+            continue
+        key = int(hashes[index])
+        first = seen.get(key)
+        if first is None:
+            seen[key] = index
+        elif index - first >= DUPLICATE_MIN_GAP:
+            repeats.append(index)
+
+    counted = int(usable.sum())
+    ratio = len(repeats) / counted if counted else 0.0
+    measured: dict[str, Any] = {
+        "duplicate_frames": len(repeats),
+        "duplicate_ratio": round(ratio, 4),
+        "allowed_ratio": DUPLICATE_MAX_RATIO,
+        "min_gap_frames": DUPLICATE_MIN_GAP,
+        "compared_frames": counted,
+        "total_frames": total,
+    }
+    if ratio <= DUPLICATE_MAX_RATIO:
+        return CheckResult(
+            "duplicate",
+            PASS,
+            f"{len(repeats)}/{counted} frames replay an earlier frame ({ratio:.1%})",
+            measured,
+        )
+
+    times = [index / clip.fps for index in repeats[:5]]
+    measured["first_repeats_s"] = [round(t, 3) for t in times]
+    detail = (
+        f"{len(repeats)}/{counted} frames replay an earlier frame ({ratio:.1%} > "
+        f"{DUPLICATE_MAX_RATIO:.0%}), first at {times[0]:.2f}s"
+    )
+    return CheckResult("duplicate", FAIL, detail, measured)
+
+
+def check_blank(clip: Clip, expect: Expect) -> CheckResult:
+    """Count frames that are essentially black or blown out to white."""
+    luma = clip.metrics.luma
+    dark = luma < BLANK_DARK
+    bright = luma > BLANK_BRIGHT
+    bad = dark | bright
+
+    measured: dict[str, Any] = {
+        "blank_frames": int(bad.sum()),
+        "dark_frames": int(dark.sum()),
+        "bright_frames": int(bright.sum()),
+        "allowed_frames": expect.black_max_frames,
+        "min_luma": round(float(luma.min()), 2) if luma.size else 0.0,
+        "max_luma": round(float(luma.max()), 2) if luma.size else 0.0,
+        "mean_luma": round(float(luma.mean()), 2) if luma.size else 0.0,
+        "total_frames": clip.count,
+    }
+    if measured["blank_frames"] <= expect.black_max_frames:
+        return CheckResult(
+            "blank",
+            PASS,
+            f"{measured['blank_frames']} blank frame(s), "
+            f"luma {measured['min_luma']:.0f}-{measured['max_luma']:.0f}",
+            measured,
+        )
+
+    ranges = _seconds(_runs(bad, 1), clip.fps)
+    measured["ranges"] = [[round(a, 3), round(b, 3)] for a, b in ranges]
+    detail = (
+        f"{measured['blank_frames']} blank frame(s) (allowed {expect.black_max_frames}) "
+        f"at {_fmt_ranges(ranges)}: "
+        f"{measured['dark_frames']} dark, {measured['bright_frames']} bright"
+    )
+    return CheckResult("blank", FAIL, detail, measured)
+
+
+def check_flicker(clip: Clip, expect: Expect) -> CheckResult:
+    """Measure the worst brightness swing inside a short sliding window.
+
+    ``flicker_max`` is a fraction of full scale: a clip whose mean luma jumps
+    by 35% of 0..255 within a handful of frames is visibly strobing. Windows
+    that contain a blank frame are ignored -- a cut to black is not a flicker
+    and is already reported by ``blank``.
+    """
+    luma = clip.metrics.luma
+    if luma.size == 0:
+        return CheckResult("flicker", FAIL, "no frames decoded", {"frames": 0})
+
+    blank = (luma < BLANK_DARK) | (luma > BLANK_BRIGHT)
+    window = max(2, min(FLICKER_WINDOW, luma.size))
+    swings = np.zeros(luma.size, dtype=np.float32)
+    for index in range(luma.size):
+        lo = max(0, index - window + 1)
+        if blank[lo : index + 1].any():
+            continue
+        swings[index] = np.ptp(luma[lo : index + 1])
+
+    swing = float(swings.max())
+    normalised = swing / 255.0
+
+    measured: dict[str, Any] = {
+        "max_window_swing": round(swing, 2),
+        "normalised_swing": round(normalised, 4),
+        "allowed": expect.flicker_max,
+        "window_frames": window,
+        "mean_abs_step": round(float(np.abs(np.diff(luma)).mean()) / 255.0, 4)
+        if luma.size > 1
+        else 0.0,
+        "total_frames": clip.count,
+    }
+    if normalised <= expect.flicker_max:
+        return CheckResult(
+            "flicker",
+            PASS,
+            f"worst {window}-frame luma swing {swing:.0f}/255 "
+            f"({normalised:.1%} <= {expect.flicker_max:.0%})",
+            measured,
+        )
+
+    index = int(swings.argmax())
+    measured["worst_at_s"] = round(index / clip.fps, 3)
+    detail = (
+        f"luma swings {swing:.0f}/255 ({normalised:.1%}) within {window} frames at "
+        f"{measured['worst_at_s']:.2f}s, over the {expect.flicker_max:.0%} limit"
+    )
+    return CheckResult("flicker", FAIL, detail, measured)
+
+
+def check_motion(clip: Clip, expect: Expect) -> CheckResult:
+    """Reject a clip whose frames barely differ, i.e. a near-static render."""
+    motion = clip.metrics.motion
+    if motion.size == 0:
+        measured = {
+            "mean_motion": 0.0,
+            "min_motion": 0.0,
+            "allowed_min": expect.motion_min,
+            "total_frames": clip.count,
+        }
+        return CheckResult("motion", FAIL, "only one frame, cannot measure motion", measured)
+
+    mean_motion = float(motion.mean())
+    measured: dict[str, Any] = {
+        "mean_motion": round(mean_motion, 5),
+        "min_motion": round(float(motion.min()), 5),
+        "max_motion": round(float(motion.max()), 5),
+        "allowed_min": expect.motion_min,
+        "still_frames": int((motion < expect.motion_min).sum()),
+        "total_frames": clip.count,
+    }
+    if mean_motion >= expect.motion_min:
+        return CheckResult(
+            "motion",
+            PASS,
+            f"mean frame-to-frame motion {mean_motion:.4f} >= {expect.motion_min:.4f}",
+            measured,
+        )
+    return CheckResult(
+        "motion",
+        FAIL,
+        f"mean frame-to-frame motion {mean_motion:.4f} is below the required "
+        f"{expect.motion_min:.4f} (near-static output)",
+        measured,
+    )

takecheck/checks/spec_check.py

@@ -0,0 +1,51 @@
+"""Spec compliance: does the file match the declared duration/fps/frames/audio?"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..probe import VideoInfo
+from ..spec import Expect
+from . import FAIL, PASS, CheckResult
+
+DURATION_TOL = 0.05  # seconds
+FPS_TOL = 0.01
+
+
+def check_spec(info: VideoInfo, expect: Expect) -> CheckResult:
+    """Compare probed facts with the declared expectations."""
+    problems: list[str] = []
+    measured: dict[str, Any] = {
+        "duration": round(info.duration, 3),
+        "fps": round(info.fps, 3),
+        "frames": info.frames,
+        "resolution": f"{info.width}x{info.height}",
+        "audio": info.has_audio,
+    }
+
+    if expect.duration is not None and abs(info.duration - expect.duration) > DURATION_TOL:
+        problems.append(f"duration {info.duration:.2f}s != {expect.duration:.2f}s")
+
+    if expect.fps is not None and abs(info.fps - expect.fps) > FPS_TOL:
+        problems.append(f"fps {info.fps:g} != {expect.fps:g}")
+
+    if expect.frames is not None and info.frames != expect.frames:
+        suffix = "" if info.frames_exact else " (estimated)"
+        problems.append(f"frames {info.frames}{suffix} != {expect.frames}")
+
+    expected_size = expect.width_height()
+    if expected_size is not None and (info.width, info.height) != expected_size:
+        problems.append(f"resolution {info.width}x{info.height} != {expect.resolution}")
+
+    if expect.audio == "required" and not info.has_audio:
+        problems.append("audio track missing")
+    if expect.audio == "forbidden" and info.has_audio:
+        problems.append("audio track present but forbidden")
+
+    if problems:
+        return CheckResult("spec", FAIL, "; ".join(problems), measured)
+
+    summary = (
+        f"{info.width}x{info.height} | {info.fps:g}fps | {info.frames}f | {info.duration:.2f}s"
+    )
+    return CheckResult("spec", PASS, summary, measured)