driftcheck-audio 0.1.0__py3-none-any.whl

driftcheck/__init__.py

@@ -0,0 +1,8 @@
+"""driftcheck: do timed labels still line up with their audio?"""
+from ._version import __version__
+from .activity import DriftcheckError
+from .checks import FileResult, Finding, check_file
+from .labels import Segment, read_labels
+from .scan import Report, run
+
+__all__ = ["__version__", "DriftcheckError", "FileResult", "Finding", "check_file", "Segment", "read_labels", "Report", "run"]

driftcheck/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

driftcheck/activity.py

@@ -0,0 +1,129 @@
+"""Where is there sound? A plain energy-based activity detector (no model, no training).
+
+Audio is cut into 10 ms frames, the energy of each frame is measured in the speech band (100 Hz to 4 kHz), and a
+frame counts as "active" when it is clearly louder than the quiet parts of the same file. Short gaps are filled
+and tiny blips are removed. This is deliberately simple. It works when speech stands out from the background;
+it does not work on music or on constant loud noise, and it says so (``Activity.reliable``).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from scipy import signal
+
+FRAME_S = 0.01            # 10 ms frames
+CONTRAST_DB = 12.0        # needs at least this much difference between loud and quiet parts to trust the result
+THRESHOLD_FRACTION = 0.3  # a frame is active above floor + 30% of the way up to the loud level
+FILL_GAP_S = 0.25         # silence shorter than this inside speech is filled in
+MIN_RUN_S = 0.10          # active runs shorter than this are dropped
+
+
+class DriftcheckError(ValueError):
+    """A problem the user can fix (bad input or option). The CLI shows it without a traceback."""
+
+
+@dataclass
+class Envelope:
+    db: np.ndarray        # energy per frame in dB (relative, not calibrated)
+    hop_s: float          # real length of one frame in seconds (sr and frame size rarely divide exactly)
+    duration_s: float
+
+
+@dataclass
+class Activity:
+    active: np.ndarray    # bool per frame
+    hop_s: float
+    duration_s: float
+    reliable: bool
+    floor_db: float
+    top_db: float
+    reason: str = ""
+
+    @property
+    def n(self) -> int:
+        return len(self.active)
+
+
+def _sos(sr: int):
+    hi = min(4000.0, 0.45 * sr)
+    lo = min(100.0, 0.5 * hi)
+    return signal.butter(4, [lo, hi], "band", fs=sr, output="sos")
+
+
+def envelope_from_array(x: np.ndarray, sr: int) -> Envelope:
+    """x: mono float signal."""
+    hop = max(int(round(sr * FRAME_S)), 1)
+    nf = len(x) // hop
+    if nf < 1:
+        return Envelope(np.zeros(0), hop / sr, len(x) / sr)
+    y = signal.sosfilt(_sos(sr), np.asarray(x, dtype=np.float64)[: nf * hop])
+    e = (y.reshape(nf, hop) ** 2).mean(axis=1)
+    return Envelope(10.0 * np.log10(np.maximum(e, 1e-14)), hop / sr, len(x) / sr)
+
+
+def envelope_from_file(path: Path, block_s: float = 60.0) -> Envelope:
+    """Read a file block by block (any length, constant memory) and measure its envelope."""
+    try:
+        f = sf.SoundFile(str(path))
+    except Exception as e:
+        raise DriftcheckError(f"cannot read {Path(path).name}: {e}") from None
+    with f:
+        sr = f.samplerate
+        total = f.frames
+        hop = max(int(round(sr * FRAME_S)), 1)
+        block = hop * max(int(block_s * sr / hop), 1)
+        sos = _sos(sr)
+        zi = np.zeros((sos.shape[0], 2))
+        parts, carry = [], np.zeros(0)
+        while True:
+            a = f.read(block, dtype="float32", always_2d=True)
+            if len(a) == 0:
+                break
+            x = a.mean(axis=1).astype(np.float64)
+            y, zi = signal.sosfilt(sos, x, zi=zi)
+            y = np.concatenate([carry, y])
+            nf = len(y) // hop
+            if nf:
+                parts.append((y[: nf * hop].reshape(nf, hop) ** 2).mean(axis=1))
+            carry = y[nf * hop:]
+    e = np.concatenate(parts) if parts else np.zeros(0)
+    return Envelope(10.0 * np.log10(np.maximum(e, 1e-14)), hop / sr, total / sr)
+
+
+def _runs(b: np.ndarray):
+    """(start, end) index pairs of the True runs in a bool array (end exclusive)."""
+    if len(b) == 0:
+        return []
+    d = np.diff(np.concatenate([[0], b.astype(np.int8), [0]]))
+    return list(zip(np.flatnonzero(d == 1), np.flatnonzero(d == -1)))
+
+
+def clean_runs(active: np.ndarray, hop_s: float, fill_gap_s: float = FILL_GAP_S, min_run_s: float = MIN_RUN_S) -> np.ndarray:
+    """Fill short gaps between active runs, then drop short active runs."""
+    out = active.copy()
+    gap = int(round(fill_gap_s / hop_s))
+    for s, e in _runs(~active):
+        if s > 0 and e < len(active) and e - s <= gap:       # a gap with sound on both sides
+            out[s:e] = True
+    mn = int(round(min_run_s / hop_s))
+    for s, e in _runs(out):
+        if e - s < mn:
+            out[s:e] = False
+    return out
+
+
+def detect_activity(env: Envelope) -> Activity:
+    n = len(env.db)
+    if n < 20:
+        return Activity(np.zeros(n, bool), env.hop_s, env.duration_s, False, 0.0, 0.0, "audio is too short")
+    floor = float(np.percentile(env.db, 10))
+    top = float(np.percentile(env.db, 95))
+    if top - floor < CONTRAST_DB:
+        return Activity(np.zeros(n, bool), env.hop_s, env.duration_s, False, floor, top,
+                        "no clear difference between loud and quiet parts (silent file, constant noise, or sound all the way through)")
+    thr = floor + THRESHOLD_FRACTION * (top - floor)
+    act = clean_runs(env.db > thr, env.hop_s)
+    return Activity(act, env.hop_s, env.duration_s, True, floor, top)

driftcheck/align.py

@@ -0,0 +1,246 @@
+"""How far are the labels from the audio, and does the gap change over time?
+
+Two on/off signals are compared, both at 10 ms steps:
+  * the label signal: ON where some label says there is speech,
+  * the audio signal: ON where the audio has sound (see activity.py).
+We slide one against the other and see where they agree best. Agreement is counted +1 when both are ON or both
+are OFF, -1 when they differ, and 0 where one of them has no information (shifted off the end).
+
+Sign convention (used everywhere): **offset = the number of seconds to ADD to the label times to match the
+audio.** A positive offset means the labels are early; the sound happens later than the labels say.
+
+For long files this is done in windows (default 60 s each), giving an offset over time. A straight line through
+those points is a steady drift (for example a subtitle file made for a different frame rate); a sudden step is a
+jump (for example a cut or an inserted ad).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy import signal, stats
+
+from .activity import Activity
+from .labels import Segment
+
+MIN_SCORE = 0.3          # agreement needed at the best position to trust it
+NULL_MARGIN = 0.1        # ...and it must beat the best score that unrelated made-up labels reach by this much
+N_NULL = 60              # number of made-up unrelated label layouts tried for a whole file
+N_NULL_WINDOW = 30       # ...and for each window of a long file
+AMBIGUOUS_RATIO = 0.85   # another peak this close to the best one (far away from it) makes the answer ambiguous
+EXCLUDE_S = 0.5          # "far away" for the rule above
+MIN_WINDOWS = 4          # fewer good windows than this: no drift is reported
+
+
+def label_indicator(segments: list[Segment], n: int, hop_s: float) -> np.ndarray:
+    """Bool per audio frame: True where a label covers the frame's centre."""
+    out = np.zeros(n, bool)
+    for s in segments:
+        if s.end <= s.start:
+            continue
+        i0 = int(np.ceil(s.start / hop_s - 0.5))
+        i1 = int(np.ceil(s.end / hop_s - 0.5))
+        i0, i1 = max(i0, 0), min(i1, n)
+        if i1 > i0:
+            out[i0:i1] = True
+    return out
+
+
+def _pm(b: np.ndarray) -> np.ndarray:
+    return np.where(b, 1.0, -1.0)
+
+
+def lag_scores(xw: np.ndarray, y: np.ndarray, w0: int, max_lag: int, center: int = 0) -> np.ndarray:
+    """Agreement between the label window `xw` (+-1, starting at audio frame w0) and the audio signal y (+-1)
+    shifted by each lag in -max_lag..max_lag.
+
+    Lag L means: label frame t is compared with audio frame t+L. Audio outside the file counts as 0 (no
+    information). Result has length 2*max_lag+1, divided by the window size. With `center`, the lags examined are
+    center-max_lag..center+max_lag instead.
+    """
+    n = len(y)
+    w1 = w0 + len(xw)
+    lo, hi = w0 + center - max_lag, w1 + center + max_lag
+    seg = np.zeros(hi - lo)
+    a, b = max(lo, 0), min(hi, n)
+    seg[a - lo:b - lo] = y[a:b]
+    return signal.fftconvolve(seg, xw[::-1], mode="valid") / max(len(xw), 1)
+
+
+def _runs(b: np.ndarray):
+    """(start, end) pairs of the True runs in a bool array (end exclusive)."""
+    d = np.diff(np.concatenate([[0], b.astype(np.int8), [0]]))
+    return list(zip(np.flatnonzero(d == 1), np.flatnonzero(d == -1)))
+
+
+def null_layouts(lab: np.ndarray, k: int, rng) -> list[np.ndarray]:
+    """`k` made-up label layouts with the same ingredients as the real one but no link to the audio.
+
+    The lengths of the labelled stretches and the lengths of the gaps between them are each shuffled, and the
+    result is moved to a random place. These show how well UNRELATED labels of this kind can agree with this audio
+    by coincidence, which is what a real measurement has to beat.
+    """
+    n = len(lab)
+    runs = _runs(lab)
+    if not runs:
+        return []
+    lens = np.array([e - s for s, e in runs])
+    gaps = np.array([runs[0][0]] + [runs[i + 1][0] - runs[i][1] for i in range(len(runs) - 1)])
+    out = []
+    for _ in range(k):
+        L, G = rng.permutation(lens), rng.permutation(gaps)
+        z = np.zeros(n, bool)
+        t = 0
+        for g, ln in zip(G, L):
+            t += int(g)
+            z[t:min(t + int(ln), n)] = True
+            t += int(ln)
+            if t >= n:
+                break
+        out.append(np.roll(z, int(rng.randint(0, n))))
+    return out
+
+
+@dataclass
+class Peak:
+    offset_s: float | None
+    score: float
+    confident: bool
+    reason: str = ""
+
+
+def pick_peak(scores: np.ndarray, max_lag: int, hop_s: float, x_transitions: int, y_transitions: int,
+              null_max: float | None = None, center: int = 0) -> Peak:
+    """Choose the best lag and decide whether to trust it."""
+    k = int(np.argmax(scores))
+    best = float(scores[k])
+    delta = 0.0
+    if 0 < k < len(scores) - 1:
+        a, b, c = scores[k - 1], scores[k], scores[k + 1]
+        den = a - 2 * b + c
+        if den < -1e-12:
+            delta = float(np.clip(0.5 * (a - c) / den, -0.5, 0.5))
+    offset = (k - max_lag + delta + center) * hop_s
+    if x_transitions < 1:
+        return Peak(None, best, False, "the labels cover all of this stretch or none of it, so there is nothing to line up")
+    if y_transitions < 1:
+        return Peak(None, best, False, "the audio has no change between sound and silence here")
+    if best < MIN_SCORE or (null_max is not None and best < null_max + NULL_MARGIN):
+        return Peak(offset, best, False, "labels and audio do not agree better than unrelated labels would (wrong labels for this audio?)")
+    ex = max(int(round(EXCLUDE_S / hop_s)), 1)
+    pk, _ = signal.find_peaks(scores)
+    for j in pk:
+        if abs(int(j) - k) > ex and scores[j] >= AMBIGUOUS_RATIO * best:
+            return Peak(offset, best, False, "more than one position fits equally well (repetitive pattern)")
+    return Peak(offset, best, True)
+
+
+def _transitions(b: np.ndarray) -> int:
+    return int(np.count_nonzero(np.diff(b.astype(np.int8))))
+
+
+def _peak_for(x: np.ndarray, y: np.ndarray, lab: np.ndarray, act_bits: np.ndarray, w0: int, w1: int,
+              max_lag: int, hop_s: float, nulls: list[np.ndarray], center: int = 0) -> Peak:
+    M = int(max(min(max_lag, (w1 - w0 - 8) // 4), 1))
+    xw = x[w0:w1]
+    sc = lag_scores(xw, y, w0, M, center)
+    nm = None
+    if nulls:
+        nm = max(float(lag_scores(_pm(z[w0:w1]), y, w0, M, center).max()) for z in nulls)
+    return pick_peak(sc, M, hop_s, _transitions(lab[w0:w1]), _transitions(act_bits[w0:w1]), nm, center)
+
+
+def estimate_offset(act: Activity, segments: list[Segment], max_offset_s: float = 5.0, seed: int = 0) -> Peak:
+    """One offset for the whole file."""
+    if not act.reliable:
+        return Peak(None, 0.0, False, act.reason)
+    n = act.n
+    lab = label_indicator(segments, n, act.hop_s)
+    M = max(int(round(max_offset_s / act.hop_s)), 1)
+    return _peak_for(_pm(lab), _pm(act.active), lab, act.active, 0, n, M, act.hop_s,
+                     null_layouts(lab, N_NULL, np.random.RandomState(seed)))
+
+
+@dataclass
+class WindowOffset:
+    start_s: float
+    end_s: float
+    offset_s: float | None
+    score: float
+    confident: bool
+    reason: str = ""
+
+
+@dataclass
+class Drift:
+    windows: list[WindowOffset]
+    n_good: int = 0
+    slope_s_per_min: float | None = None
+    offset_start_s: float | None = None
+    offset_end_s: float | None = None
+    offset_median_s: float | None = None
+    scatter_s: float | None = None
+    jumps: list[dict] = field(default_factory=list)
+
+
+def estimate_drift(act: Activity, segments: list[Segment], window_s: float = 60.0, max_offset_s: float = 5.0,
+                   jump_s: float = 0.3, seed: int = 0) -> Drift:
+    """Offset in consecutive windows of `window_s`, then a straight line through them and a search for jumps."""
+    if not act.reliable:
+        return Drift(windows=[])
+    n = act.n
+    hop = act.hop_s
+    lab = label_indicator(segments, n, hop)
+    x, y = _pm(lab), _pm(act.active)
+    M = max(int(round(max_offset_s / hop)), 1)
+    w = max(int(round(window_s / hop)), 10)
+    nulls = null_layouts(lab, N_NULL_WINDOW, np.random.RandomState(seed))
+    wins: list[WindowOffset] = []
+    seen: list[tuple[float, float]] = []          # (window centre time, offset) of the good windows so far
+    for w0 in range(0, n - w // 2, w):
+        w1 = min(w0 + w, n)
+        if w1 - w0 < w // 2:
+            break
+        # Each window searches around where the previous good windows say the offset should be now, so a steady
+        # drift (which can add up to many seconds) is followed instead of being lost beyond the search range.
+        tc = 0.5 * (w0 + w1) * hop
+        centre = 0.0
+        if seen:
+            centre = seen[-1][1]
+            if len(seen) >= 2:
+                (t1, o1), (t2, o2) = seen[-2], seen[-1]
+                centre = o2 + (o2 - o1) / (t2 - t1) * (tc - t2)
+        pk = _peak_for(x, y, lab, act.active, w0, w1, M, hop, nulls, int(round(centre / hop)))
+        if pk.confident:
+            seen.append((tc, pk.offset_s))
+        wins.append(WindowOffset(round(w0 * hop, 3), round(w1 * hop, 3), None if pk.offset_s is None else round(pk.offset_s, 4),
+                                 round(pk.score, 3), pk.confident, pk.reason))
+    d = Drift(windows=wins)
+    good = [(0.5 * (v.start_s + v.end_s), v.offset_s) for v in wins if v.confident]
+    d.n_good = len(good)
+    if good:
+        d.offset_median_s = float(np.median([g[1] for g in good]))
+    if len(good) < MIN_WINDOWS:
+        return d
+    t = np.array([g[0] for g in good])
+    o = np.array([g[1] for g in good])
+    # jumps first: a step between neighbouring good windows that the steady drift cannot explain
+    dt = np.diff(t)
+    adj = np.diff(o) / dt                                   # drift between neighbours, seconds per second
+    typical = float(np.median(adj))
+    steps = np.diff(o) - typical * dt                       # what is left over at each step
+    noise = max(float(1.4826 * np.median(np.abs(steps - np.median(steps)))), 0.02)
+    jump_at = np.zeros(len(o), float)                       # size of the jump just before each good window
+    for i, st in enumerate(steps):
+        if abs(st) >= jump_s and abs(st) >= 4 * noise:
+            d.jumps.append({"at_s": float(0.5 * (t[i] + t[i + 1])), "step_s": float(st)})
+            jump_at[i + 1] = st
+    o_adj = o - np.cumsum(jump_at)                          # offsets with the jumps taken out
+    slope, icpt, _, _ = stats.theilslopes(o_adj, t)
+    res = o_adj - (icpt + slope * t)
+    d.scatter_s = float(1.4826 * np.median(np.abs(res - np.median(res))))
+    d.slope_s_per_min = float(slope * 60.0)
+    d.offset_start_s = float(icpt)
+    t_end = min(act.duration_s, max(sg.end for sg in segments))     # the end of the labels, in label time
+    d.offset_end_s = float(icpt + slope * t_end + jump_at.sum())
+    return d

driftcheck/checks.py

@@ -0,0 +1,250 @@
+"""The per-file checks: put the labels next to the audio and list what does not fit."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+from scipy import ndimage
+
+from .activity import Activity, DriftcheckError, detect_activity, envelope_from_file, _runs
+from .align import MIN_WINDOWS, Drift, estimate_drift, estimate_offset, label_indicator
+from .labels import Segment
+
+# Judgement defaults, not standards. Change them with --warn / --fail.
+WARN_S = 0.15                # an offset this big is noticeable in subtitles and starts to hurt alignment-based training
+FAIL_S = 0.5
+UNLABELLED_WARN, UNLABELLED_FAIL = 0.10, 0.40     # share of the speech that no label covers
+SILENT_WARN, SILENT_FAIL = 0.10, 0.40             # share of the labelled time that is silent
+PAD_S = 0.15                 # labels are given this much slack on each side before saying "speech outside labels"
+MIN_UNLABELLED_S = 0.5       # speech outside the labels shorter than this is ignored
+MIN_SILENT_LABEL_S = 1.0     # shorter labels are not judged for silence
+SILENT_ACTIVE_SHARE = 0.2    # a label with less than this share of sound counts as silent
+RATE_RATIO = 3.0             # characters per second more than this many times the usual (or less than 1/RATE_RATIO^1.33)
+RATE_ABS_MAX = 35.0          # characters (without spaces) per second nobody can speak
+
+# Pairs of frame rates that are commonly mixed up: label times written for one, audio/video made at the other.
+FRAME_RATE_RATIOS = {
+    "25 vs 23.976 fps": 25 / 23.976, "23.976 vs 25 fps": 23.976 / 25,
+    "25 vs 24 fps": 25 / 24, "24 vs 25 fps": 24 / 25,
+    "30 vs 29.97 fps": 30 / 29.97, "29.97 vs 30 fps": 29.97 / 30,
+    "24 vs 23.976 fps": 24 / 23.976, "23.976 vs 24 fps": 23.976 / 24,
+}
+
+
+@dataclass
+class Finding:
+    level: str            # INFO, WARN or FAIL
+    code: str
+    message: str
+    at_s: float | None = None
+
+
+@dataclass
+class FileResult:
+    name: str
+    duration_s: float | None
+    n_labels: int
+    findings: list[Finding] = field(default_factory=list)
+    measurable: bool = False
+    offset_s: float | None = None             # best single number (the middle of the file when it drifts)
+    offset_start_s: float | None = None
+    offset_end_s: float | None = None
+    drift_s_per_min: float | None = None
+    score: float | None = None
+    windows: list = field(default_factory=list)
+    jumps: list = field(default_factory=list)
+    unlabelled_speech_share: float | None = None
+    silent_label_share: float | None = None
+    suggested_scale: float | None = None
+
+    def verdict(self) -> str:
+        lv = {f.level for f in self.findings}
+        return "FAIL" if "FAIL" in lv else "WARN" if "WARN" in lv else "PASS"
+
+
+def _level(x: float, warn: float, fail: float) -> str | None:
+    return "FAIL" if x >= fail else "WARN" if x >= warn else None
+
+
+def _ms(x: float) -> str:
+    return f"{x * 1000:+.0f} ms" if abs(x) < 1 else f"{x:+.2f} s"
+
+
+def _chars(text: str) -> int:
+    return len(re.sub(r"\s+", "", text))
+
+
+def chars_per_second(segs: list[Segment], min_s: float = 1.0) -> list[float]:
+    return [_chars(s.text) / s.duration for s in segs if s.text and s.duration >= min_s]
+
+
+def _structure_checks(segs: list[Segment], duration: float | None, F: list[Finding]):
+    bad = [s for s in segs if s.end <= s.start]
+    if bad:
+        F.append(Finding("FAIL", "bad-length", f"{len(bad)} label(s) end before they start or have zero length "
+                         f"(first at {bad[0].start:.2f} s)", bad[0].start))
+    if any(b.start < a.start - 1e-9 for a, b in zip(segs, segs[1:])):
+        F.append(Finding("WARN", "out-of-order", "labels are not in time order"))
+    ordered = sorted((s for s in segs if s.end > s.start), key=lambda s: s.start)
+    ov = [(a, b) for a, b in zip(ordered, ordered[1:]) if a.end - b.start > 0.5]
+    if ov:
+        F.append(Finding("WARN", "overlap", f"{len(ov)} label(s) overlap the one before by more than 0.5 s "
+                         f"(first at {ov[0][1].start:.2f} s)", ov[0][1].start))
+    if duration is not None:
+        after = [s for s in segs if s.start >= duration]
+        if after:
+            F.append(Finding("FAIL", "after-end", f"{len(after)} label(s) start after the audio has ended "
+                             f"({duration:.1f} s); first at {after[0].start:.1f} s", after[0].start))
+        else:
+            past = [s for s in segs if s.end > duration + 0.5]
+            if past:
+                F.append(Finding("WARN", "past-end", f"{len(past)} label(s) run past the end of the audio ({duration:.1f} s)",
+                                 past[0].start))
+    texts = [bool(s.text.strip()) for s in segs]
+    if any(texts) and not all(texts):
+        F.append(Finding("WARN", "empty-text", f"{texts.count(False)} label(s) have no text"))
+
+
+def _rate_checks(segs: list[Segment], ref_rate: float | None, F: list[Finding]):
+    rates = [(_chars(s.text) / s.duration, s) for s in segs if s.text and s.duration >= 1.0]
+    if not rates:
+        return
+    ref = ref_rate if ref_rate else (float(np.median([r for r, _ in rates])) if len(rates) >= 8 else None)
+    fast = [(r, s) for r, s in rates if r > RATE_ABS_MAX or (ref and r > RATE_RATIO * ref)]
+    slow = [(r, s) for r, s in rates if ref and r < ref / RATE_RATIO ** 1.33]
+    if fast:
+        r, s = max(fast, key=lambda t: t[0])
+        F.append(Finding("WARN", "too-fast", f"{len(fast)} label(s) hold more text than anyone speaks in that time "
+                         f"(fastest: {r:.0f} characters per second at {s.start:.1f} s): the text may belong to a longer stretch", s.start))
+    if slow:
+        r, s = min(slow, key=lambda t: t[0])
+        F.append(Finding("WARN", "too-slow", f"{len(slow)} label(s) hold very little text for their length "
+                         f"(slowest: {r:.1f} characters per second at {s.start:.1f} s): the label may cover more than the text", s.start))
+
+
+def _timing(act: Activity, segs: list[Segment], res: FileResult, F: list[Finding], *, warn_s, fail_s, window_s, max_offset_s):
+    long_file = act.duration_s >= 2 * window_s
+    drift: Drift | None = estimate_drift(act, segs, window_s, max_offset_s) if long_file else None
+    if drift is not None and drift.n_good >= MIN_WINDOWS:
+        res.windows = [vars(w) for w in drift.windows]
+        res.jumps = drift.jumps
+        res.score = float(np.median([w.score for w in drift.windows if w.confident]))
+        total = drift.offset_end_s - drift.offset_start_s - sum(j["step_s"] for j in drift.jumps)
+        steady = abs(total) >= warn_s and abs(total) >= 3 * drift.scatter_s
+        res.offset_start_s, res.offset_end_s = drift.offset_start_s, drift.offset_end_s
+        res.measurable = True
+        if steady:
+            res.drift_s_per_min = drift.slope_s_per_min
+            res.offset_s = 0.5 * (drift.offset_start_s + drift.offset_end_s)
+            ratio = 1.0 + drift.slope_s_per_min / 60.0
+            res.suggested_scale = ratio
+            worst = max(abs(drift.offset_start_s), abs(drift.offset_end_s))
+            lvl = _level(worst, warn_s, fail_s) or "WARN"
+            hint = next((k for k, v in FRAME_RATE_RATIOS.items() if abs(ratio - v) < 0.0004), None)
+            F.append(Finding(lvl, "drift",
+                             f"the labels drift against the audio: offset is {_ms(drift.offset_start_s)} at the start and "
+                             f"{_ms(drift.offset_end_s)} at the end ({drift.slope_s_per_min * 1000:+.0f} ms per minute). "
+                             f"Multiplying the label times by about {ratio:.5f} would remove the drift"
+                             + (f"; that is the ratio of {hint}, a common frame-rate mix-up" if hint else "")))
+        else:
+            res.offset_s = drift.offset_median_s
+            res.drift_s_per_min = drift.slope_s_per_min
+            lvl = _level(abs(res.offset_s), warn_s, fail_s)
+            F.append(Finding(lvl or "INFO", "offset",
+                             f"labels are {_ms(res.offset_s)} from the audio (add this to the label times to line up)"
+                             if lvl else f"labels line up with the audio within {1000 * max(abs(res.offset_s), 0.01):.0f} ms "
+                             f"and do not drift (steady over {drift.n_good} windows)"))
+        for j in drift.jumps:
+            F.append(Finding("FAIL" if abs(j["step_s"]) >= fail_s else "WARN", "jump",
+                             f"the offset suddenly changes by {_ms(j['step_s'])} near {j['at_s']:.0f} s "
+                             f"(a cut, an inserted section, or labels from two different versions)", j["at_s"]))
+        return
+    # not enough good windows (short file, or windows that could not be measured): one offset for the whole file
+    pk = estimate_offset(act, segs, max_offset_s)
+    res.score = pk.score
+    if drift is not None:
+        res.windows = [vars(w) for w in drift.windows]
+    if pk.confident:
+        res.measurable = True
+        res.offset_s = pk.offset_s
+        lvl = _level(abs(pk.offset_s), warn_s, fail_s)
+        msg = (f"labels are {_ms(pk.offset_s)} from the audio (add this to the label times to line up)" if lvl else
+               f"labels line up with the audio within {1000 * max(abs(pk.offset_s), 0.01):.0f} ms")
+        if int(act.duration_s // window_s) < MIN_WINDOWS:
+            note = f" (drift is not measured on this file: it needs at least {MIN_WINDOWS} windows of {window_s:g} s)"
+        else:
+            note = " (drift could not be measured: too few good windows)"
+        F.append(Finding(lvl or "INFO", "offset", msg + note))
+    else:
+        F.append(Finding("INFO", "offset-unmeasurable", f"offset could not be measured: {pk.reason}"))
+
+
+def _coverage(act: Activity, segs: list[Segment], res: FileResult, F: list[Finding], offset_note: bool):
+    hop = act.hop_s
+    lab = label_indicator(segs, act.n, hop)
+    pad = max(int(round(PAD_S / hop)), 1)
+    dil = ndimage.binary_dilation(lab, iterations=pad) if lab.any() else lab
+    total_active = float(act.active.sum()) * hop
+    # speech outside the labels
+    runs = [(s, e) for s, e in _runs(act.active & ~dil) if (e - s) * hop >= MIN_UNLABELLED_S]
+    un = sum(e - s for s, e in runs) * hop
+    if total_active > 0:
+        res.unlabelled_speech_share = un / total_active
+        lvl = _level(res.unlabelled_speech_share, UNLABELLED_WARN, UNLABELLED_FAIL)
+        if lvl:
+            s0, e0 = max(runs, key=lambda r: r[1] - r[0])
+            F.append(Finding(lvl, "unlabelled-speech",
+                             f"{100 * res.unlabelled_speech_share:.0f}% of the sound ({un:.0f} s in {len(runs)} stretches) is outside every label; "
+                             f"longest: {(e0 - s0) * hop:.1f} s at {s0 * hop:.1f} s"
+                             + ("; this may be a result of the offset above" if offset_note else ""), s0 * hop))
+    # labels over silence
+    sil, tot = 0.0, 0.0
+    first = None
+    for sg in segs:
+        d = sg.end - sg.start
+        if d < MIN_SILENT_LABEL_S:
+            continue
+        i0, i1 = max(int(round(sg.start / hop)), 0), min(int(round(sg.end / hop)), act.n)
+        if i1 - i0 < 10:
+            continue
+        tot += d
+        if act.active[i0:i1].mean() < SILENT_ACTIVE_SHARE:
+            sil += d
+            first = first if first is not None else sg.start
+    if tot > 0:
+        res.silent_label_share = sil / tot
+        lvl = _level(res.silent_label_share, SILENT_WARN, SILENT_FAIL)
+        if lvl:
+            F.append(Finding(lvl, "silent-labels",
+                             f"{100 * res.silent_label_share:.0f}% of the labelled time ({sil:.0f} s) has almost no sound in the audio; "
+                             f"first at {first:.1f} s"
+                             + ("; this may be a result of the offset above" if offset_note else ""), first))
+
+
+def check_file(name: str, audio_path: Path | None, segs: list[Segment], *, warn_s: float = WARN_S, fail_s: float = FAIL_S,
+               window_s: float = 60.0, max_offset_s: float = 5.0, ref_rate: float | None = None) -> FileResult:
+    """Check one recording's labels against its audio. audio_path=None runs only the checks that need no audio."""
+    F: list[Finding] = []
+    act = None
+    duration = None
+    if audio_path is not None:
+        env = envelope_from_file(audio_path)
+        duration = env.duration_s
+        act = detect_activity(env)
+    res = FileResult(name, duration, len(segs), F)
+    _structure_checks(segs, duration, F)
+    _rate_checks(segs, ref_rate, F)
+    if act is None:
+        return res
+    if not act.reliable:
+        F.append(Finding("INFO", "audio-unreliable", f"timing was not checked: {act.reason}"))
+        return res
+    valid = [s for s in segs if s.end > s.start]
+    if not valid:
+        return res
+    _timing(act, valid, res, F, warn_s=warn_s, fail_s=fail_s, window_s=window_s, max_offset_s=max_offset_s)
+    off_flag = any(f.code in ("offset", "drift", "jump") and f.level in ("WARN", "FAIL") for f in F)
+    _coverage(act, valid, res, F, off_flag)
+    return res