renoise-kit 0.5.0__py3-none-any.whl

rn/listen.py

@@ -0,0 +1,199 @@
+"""rn listen: audio as facts and one picture (waveform, spectrogram, loudness, onsets, beats, silences, words)."""
+from __future__ import annotations
+
+import io
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .audio import measure
+from .ff import RnError, probe, run
+from .frames import DEFAULT_MAX_KB, _save_under
+
+ANALYSIS_RATE = 22050
+CURVE_STEP = 0.5
+SILENCE_DB = -50.0  # frame RMS below this, for at least SILENCE_MIN seconds
+SILENCE_MIN = 0.3
+MAX_EVENTS = 400  # onsets / beats kept in the result; the strongest onsets win when thinned
+BEAT_CLEAR = 0.15  # autocorrelation of the onset envelope at the beat period, 0..1
+
+
+def _short_term_curve(wav: Path) -> list[dict]:
+    """Short-term (3 s) loudness every CURVE_STEP seconds from ebur128's frame log (it logs every 0.1 s)."""
+    result = subprocess.run(['ffmpeg', '-hide_banner', '-nostdin', '-i', str(wav), '-af', 'ebur128',
+                             '-f', 'null', '-'], capture_output=True, text=True)
+    curve, next_t = [], 0.0
+    for match in re.finditer(r't:\s*([\d.]+)\s.*?M:\s*(-?[\d.]+|-inf)\s+S:\s*(-?[\d.]+|-inf)', result.stderr):
+        t = float(match.group(1))
+        level = match.group(3) if t >= 3 else match.group(2)
+        if t + 1e-6 >= next_t and level != '-inf':
+            curve.append({'t': round(t, 2), 'lufs': max(float(level), -70.0)})
+            next_t = t + CURVE_STEP
+    return curve
+
+
+def _silences(samples, rate: int) -> list[dict]:
+    import librosa
+    import numpy as np
+
+    hop = 512
+    rms = librosa.feature.rms(y=samples, frame_length=2048, hop_length=hop)[0]
+    quiet = 20 * np.log10(np.maximum(rms, 1e-9)) < SILENCE_DB
+    ranges, start = [], None
+    for index, flag in enumerate(list(quiet) + [False]):
+        if flag and start is None:
+            start = index
+        elif not flag and start is not None:
+            begin, end = start * hop / rate, min(index * hop / rate, len(samples) / rate)
+            if end - begin >= SILENCE_MIN:
+                ranges.append({'start': round(begin, 3), 'end': round(end, 3)})
+            start = None
+    return ranges
+
+
+def _beats(samples, rate: int, onset_env, hop: int = 512) -> dict:
+    import librosa
+    import numpy as np
+
+    tempo, frames = librosa.beat.beat_track(onset_envelope=onset_env, sr=rate, hop_length=hop)
+    bpm = float(np.atleast_1d(tempo)[0])
+    if bpm <= 0 or len(frames) < 3:
+        return {'bpm': None, 'alternatives': [], 'times': [], 'clear': False}
+    # The tracker's tempo sits on a coarse frame grid (~2 bpm steps); the mean beat interval over the whole span is finer.
+    beat_times = librosa.frames_to_time(frames, sr=rate, hop_length=hop)
+    bpm = float(60 * (len(beat_times) - 1) / (beat_times[-1] - beat_times[0]))
+    autocorr = librosa.autocorrelate(onset_env - onset_env.mean())
+    autocorr = autocorr / autocorr[0] if autocorr[0] > 0 else autocorr
+
+    def strength(candidate: float) -> float:
+        lag = int(round(60 * rate / (hop * candidate)))
+        return float(max(autocorr[max(lag - 1, 0):lag + 2], default=0)) if lag < len(autocorr) else 0.0
+
+    # The BPM octave check: a beat tracker can report half or double the felt pulse, so give all three with
+    # the periodicity strength measured at each; the main bpm is the tracker's.
+    alternatives = [{'bpm': round(value, 1), 'strength': round(strength(value), 3)} for value in (bpm / 2, bpm * 2)]
+    times = librosa.frames_to_time(frames, sr=rate, hop_length=hop)
+    return {'bpm': round(bpm, 1), 'strength': round(strength(bpm), 3), 'alternatives': alternatives,
+            'times': [round(float(t), 3) for t in times[:MAX_EVENTS]], 'clear': strength(bpm) >= BEAT_CLEAR}
+
+
+def _transcribe(wav: Path, *, language: str | None, model: str) -> dict:
+    try:
+        from faster_whisper import WhisperModel
+    except ImportError:
+        raise RnError("--transcribe needs faster-whisper (extra \"transcribe\"): uv tool install 'renoise-kit[all]'")
+    import numpy as np
+    # Decode here and pass samples: faster-whisper's own file decoding goes through PyAV, whose API it does not pin
+    # (av 16 dropped the `metadata_errors` argument it passes).
+    pcm = subprocess.run(['ffmpeg', '-hide_banner', '-v', 'error', '-nostdin', '-i', str(wav), '-f', 'f32le', '-ac', '1', '-ar', '16000', '-'],
+                         capture_output=True, check=True).stdout
+    audio = np.frombuffer(pcm, dtype=np.float32)
+    segments, info = WhisperModel(model, device='cpu', compute_type='int8').transcribe(audio, language=language, word_timestamps=True)
+    words, texts = [], []
+    for segment in segments:
+        texts.append({'start': round(segment.start, 3), 'end': round(segment.end, 3), 'text': segment.text.strip()})
+        # Whisper's leading space marks a new word in space-delimited languages; rn captions relies on it.
+        words.extend({'word': w.word, 'start': round(w.start, 3), 'end': round(w.end, 3), 'p': round(w.probability, 3)}
+                     for w in segment.words or [])
+    return {'words': words, 'segments': texts, 'language': info.language}
+
+
+def _draw(result: dict, samples, rate: int, onset_times: list[float]):
+    import librosa
+    import matplotlib
+    matplotlib.use('Agg')
+    import matplotlib.pyplot as plt
+    import numpy as np
+    from PIL import Image
+
+    duration = result['duration']
+    fig, axes = plt.subplots(4, 1, figsize=(10, 6), sharex=True, gridspec_kw={'height_ratios': [2, 3, 1.5, 0.8]})
+    wave, spec, loud, ticks = axes
+    times = np.arange(len(samples)) / rate
+    step = max(1, len(samples) // 4000)  # min/max envelope keeps spikes visible
+    blocks = len(samples) // step
+    shaped = samples[:blocks * step].reshape(blocks, step)
+    block_t = times[:blocks * step:step]
+    wave.fill_between(block_t, shaped.min(axis=1), shaped.max(axis=1), color='#3b6ea5', linewidth=0)
+    wave.set_ylabel('amp')
+    mel = librosa.power_to_db(librosa.feature.melspectrogram(y=samples, sr=rate, n_mels=96), ref=np.max)
+    spec.imshow(mel, aspect='auto', origin='lower', cmap='magma', extent=[0, len(samples) / rate, 0, 96], vmin=-80, vmax=0)
+    spec.set_ylabel('mel')
+    spec.set_yticks([])
+    curve = result['loudness']['curve']
+    if curve:
+        loud.plot([p['t'] for p in curve], [p['lufs'] for p in curve], color='#d95f02')
+    loud.set_ylabel('LUFS')
+    ticks.vlines(onset_times, 0.55, 1, color='#1b9e77', linewidth=0.8)
+    ticks.vlines(result['beats']['times'], 0, 0.45, color='#e7298a', linewidth=1.2)
+    ticks.set_yticks([0.225, 0.775])
+    ticks.set_yticklabels(['beat', 'onset'], fontsize=6)
+    ticks.set_xlabel('seconds')
+    for silence in result['silences']:
+        for axis in (wave, loud, ticks):
+            axis.axvspan(silence['start'], silence['end'], color='grey', alpha=0.35, linewidth=0)
+    ticks.set_xlim(0, duration)
+    lufs, bpm = result['loudness']['integrated'], result['beats']['bpm']
+    fig.suptitle(f"{Path(result['path']).name}  {duration:.2f}s  {lufs} LUFS  "
+                 f"{str(bpm) + ' bpm' if bpm and result['beats']['clear'] else 'no clear pulse'}", fontsize=10)
+    fig.tight_layout()
+    buffer = io.BytesIO()
+    fig.savefig(buffer, format='png', dpi=100)
+    plt.close(fig)
+    buffer.seek(0)
+    return Image.open(buffer).convert('RGB')
+
+
+def listen_command(path: str, *, out: str | None, transcribe: bool, language: str | None, model: str, max_kb: int = DEFAULT_MAX_KB) -> dict:
+    import librosa
+    import numpy as np
+
+    info = probe(path)
+    if not info['audio']:
+        raise RnError(f'{path}: no audio stream')
+    with tempfile.TemporaryDirectory() as tmp:
+        wav = Path(tmp) / 'audio.wav'
+        run(['ffmpeg', '-i', path, '-vn', '-ac', '1', '-ar', str(ANALYSIS_RATE), '-y', str(wav)])
+        samples, rate = librosa.load(str(wav), sr=None, mono=True)
+        loudness = measure(wav)
+        hop = 512
+        onset_env = librosa.onset.onset_strength(y=samples, sr=rate, hop_length=hop)
+        onset_frames = librosa.onset.onset_detect(onset_envelope=onset_env, sr=rate, hop_length=hop)
+        if len(onset_frames) > MAX_EVENTS:  # keep the strongest, back in time order
+            onset_frames = np.sort(onset_frames[np.argsort(onset_env[onset_frames])[-MAX_EVENTS:]])
+        onset_times = [round(float(t), 3) for t in librosa.frames_to_time(onset_frames, sr=rate, hop_length=hop)]
+        result: dict = {
+            'path': path,
+            'duration': round(len(samples) / rate, 3),
+            'sample_rate': info['audio']['sample_rate'],
+            'loudness': {'integrated': loudness['lufs'], 'true_peak': loudness['true_peak'], 'curve': _short_term_curve(wav)},
+            'silences': _silences(samples, rate),
+            'onsets': onset_times,
+            'beats': _beats(samples, rate, onset_env),
+        }
+        if transcribe:
+            result.update(_transcribe(wav, language=language, model=model))
+        target = Path(out) if out else Path('listen') / f'{Path(path).stem}.jpg'
+        target.parent.mkdir(parents=True, exist_ok=True)
+        size = _save_under(_draw(result, samples, rate, onset_times), target, max_kb)
+        result['image'] = {'path': str(target), 'bytes': size}
+    return result
+
+
+def summary_lines(result: dict) -> list[str]:
+    loudness, beats = result['loudness'], result['beats']
+    lines = [f"{result['path']}: {result['duration']:.2f}s  {result['sample_rate']} Hz",
+             f"loudness {loudness['integrated']} LUFS  true peak {loudness['true_peak']} dBTP"]
+    if beats['bpm'] and beats['clear']:
+        alternatives = ', '.join(f"{a['bpm']} ({a['strength']})" for a in beats['alternatives'])
+        lines.append(f"bpm {beats['bpm']} (strength {beats['strength']}; alternatives {alternatives})  {len(beats['times'])} beats")
+    else:
+        lines.append('no clear pulse')
+    lines.append(f"{len(result['onsets'])} onsets  {len(result['silences'])} silences"
+                 + ''.join(f"  {s['start']}-{s['end']}s" for s in result['silences'][:3]))
+    if 'words' in result:
+        first = ' '.join(w['word'] for w in result['words'][:8])
+        lines.append(f"{len(result['words'])} words ({result['language']}): {first}")
+    lines.append(f"image {result['image']['path']} ({result['image']['bytes']} bytes)")
+    return lines

rn/matte.py

@@ -0,0 +1,58 @@
+"""rn matte: the subject's alpha in every frame (rembg), as a numbered grey PNG sequence (white = subject) that an EDL
+uses as an overlay "mask" (text behind a person, a graphic that stays off them) or, with --cutout, as the cut-out
+subject itself. Measurement-grade, not roto: check the edges on a sheet.
+"""
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from .ff import RnError, probe, run, source_fps
+
+MODELS = ('isnet-general-use', 'u2net_human_seg', 'u2net', 'u2netp', 'silueta', 'birefnet-general', 'birefnet-portrait')
+
+
+def matte_command(path: str, *, out: str, model: str, every: int, cutout: bool) -> dict:
+    from PIL import Image
+    from rembg import new_session, remove
+
+    if every < 1:
+        raise RnError('--every must be >= 1')
+    info = probe(path)
+    video = info['video']
+    if not video or video['still']:
+        raise RnError(f'{path}: not a video (rembg itself handles a single image)')
+    fps = source_fps(info)
+    out_dir = Path(out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for stale in out_dir.glob('*.png'):
+        stale.unlink()
+    session = new_session(model)
+    with tempfile.TemporaryDirectory() as tmp:
+        # Every decoded frame in order (no timestamps involved), so output n is input frame n - 1.
+        run(['ffmpeg', '-i', path, '-map', '0:v:0', '-fps_mode', 'passthrough', '-y', str(Path(tmp) / '%06d.png')])
+        frames = sorted(Path(tmp).glob('*.png'))
+        mask = None
+        for k, png in enumerate(frames):
+            image = Image.open(png).convert('RGB')
+            if k % every == 0 or mask is None:
+                mask = remove(image, session=session, only_mask=True).convert('L')  # held in between with --every
+            target = out_dir / f'{k + 1:05d}.png'
+            if cutout:
+                rgba = image.convert('RGBA')
+                rgba.putalpha(mask)
+                rgba.save(target)
+            else:
+                mask.save(target)
+    fps_text = str(fps.numerator) if fps.denominator == 1 else f'{fps.numerator}/{fps.denominator}'
+    pattern = f'{out_dir.name}/%05d.png'
+    use = {'frames': pattern, 'fps': fps_text}
+    return {'dir': str(out_dir), 'frames': len(frames), 'model': model, 'every': every, 'cutout': cutout,
+            'edl': use if cutout else {'mask': {**use, 'mode': 'luma'}}}
+
+
+def summary_lines(result: dict) -> list[str]:
+    kind = 'RGBA cut-outs' if result['cutout'] else 'grey mattes (white = subject)'
+    return [f'{result["dir"]}/%05d.png  {result["frames"]} {kind}  model {result["model"]}, computed every {result["every"]} frame(s)',
+            f'EDL: {json.dumps(result["edl"])}' + ('' if result['cutout'] else '  (on an overlay; "invert": true keeps it off the subject)')]

rn/qa.py

@@ -0,0 +1,212 @@
+"""rn qa: delivery checks on the ENCODED file. FAIL blocks delivery; WARN needs a look (it may be intended)."""
+from __future__ import annotations
+
+import re
+import subprocess
+from fractions import Fraction
+from pathlib import Path
+
+from .audio import measure
+from .edl import Edit, load
+from .ff import RnError, probe
+
+
+def _scan(path: str) -> dict:
+    """One decode pass: black intervals, frozen intervals and the union crop box (black bars)."""
+    result = subprocess.run(['ffmpeg', '-hide_banner', '-nostdin', '-i', path, '-map', '0:v:0', '-vf',
+                             'blackdetect=d=0.1:pix_th=0.10,freezedetect=n=-60dB:d=0.5,cropdetect=limit=24:round=2:reset=0',
+                             '-f', 'null', '-'], capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RnError(f'{path}: decode failed: {result.stderr.strip().splitlines()[-1:]}')
+    log = result.stderr
+    black = [(float(a), float(b)) for a, b in re.findall(r'black_start:([\d.]+) black_end:([\d.]+)', log)]
+    starts = [float(v) for v in re.findall(r'freeze_start: ([\d.]+)', log)]
+    ends = [float(v) for v in re.findall(r'freeze_end: ([\d.]+)', log)]
+    freezes = [(s, ends[i] if i < len(ends) else None) for i, s in enumerate(starts)]
+    crops = re.findall(r'crop=(\d+):(\d+):(\d+):(\d+)', log)
+    crop = tuple(int(v) for v in crops[-1]) if crops else None
+    return {'black': black, 'freeze': freezes, 'crop': crop}
+
+
+SILENCE_DB, SILENCE_MIN = -70, 0.06  # digital silence inside a mix reads as a glitch, not a pause
+JUMP_DB = 15  # between adjacent 100 ms RMS windows: right for a designed hit, wrong for a music edit
+
+
+def _sound(path: str, seconds: float) -> dict:
+    """One decode pass: digital silences away from the head and tail, and level jumps between 100 ms windows."""
+    result = subprocess.run(['ffmpeg', '-hide_banner', '-nostdin', '-i', path, '-map', '0:a:0', '-af',
+                             f'aresample=48000,silencedetect=noise={SILENCE_DB}dB:d={SILENCE_MIN},asetnsamples=n=4800:p=0,'
+                             'astats=metadata=1:reset=1,ametadata=mode=print:key=lavfi.astats.Overall.RMS_level:file=-',
+                             '-f', 'null', '-'], capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RnError(f'{path}: audio decode failed: {result.stderr.strip().splitlines()[-1:]}')
+    starts = [float(v) for v in re.findall(r'silence_start: (-?[\d.]+)', result.stderr)]
+    ends = [float(v) for v in re.findall(r'silence_end: ([\d.]+)', result.stderr)]
+    silences = [(max(0.0, s), ends[i] if i < len(ends) else seconds) for i, s in enumerate(starts)]
+    silences = [(a, b) for a, b in silences if a > 0.05 and b < seconds - 0.05]  # lead-in and tail-out are a choice
+    levels = [float(v) for v in re.findall(r'RMS_level=(-?inf|-?[\d.]+)', result.stdout)]
+    # The last window is partial and holds the encoder's tail, so it reads as a drop; skip it like the head.
+    jumps = [(round(k * 0.1, 1), levels[k - 1], levels[k]) for k in range(1, len(levels))
+             if k * 0.1 < seconds - 0.15 and abs(levels[k] - levels[k - 1]) >= JUMP_DB and max(levels[k], levels[k - 1]) > -60]
+    return {'silence': silences, 'jumps': jumps}
+
+
+def _fixed_frame_rate(path: str) -> bool | None:
+    """The H.264 SPS fixed_frame_rate_flag, or None when the stream carries no timing info."""
+    result = subprocess.run(['ffmpeg', '-hide_banner', '-nostdin', '-i', path, '-map', '0:v:0', '-c', 'copy', '-bsf:v', 'trace_headers',
+                             '-frames:v', '1', '-f', 'null', '-'], capture_output=True, text=True)
+    flag = re.search(r'fixed_frame_rate_flag\s+[01]\s+=\s+([01])', result.stderr)
+    return flag.group(1) == '1' if flag else None
+
+
+def _intended(edit: Edit | None, kind: str) -> list[tuple[float, float]]:
+    """Timeline ranges the EDL itself makes black or still, so qa does not flag them."""
+    if not edit:
+        return []
+    ranges = []
+    for clip in edit.base:
+        if (kind == 'black' and clip.kind == 'color') or (kind == 'freeze' and clip.kind in ('image', 'color')):
+            ranges.append((float(clip.timeline_start / edit.fps), float((clip.timeline_start + clip.frames) / edit.fps)))
+    return ranges
+
+
+def _covered(interval: tuple[float, float | None], ranges: list[tuple[float, float]], end: float) -> bool:
+    start, stop = interval[0], interval[1] if interval[1] is not None else end
+    return any(a - 0.05 <= start and stop <= b + 0.05 for a, b in ranges)
+
+
+def parse_accept(values: list[str]) -> list[dict]:
+    """--accept CHECK or CHECK@SECONDS."""
+    accepted = []
+    for value in values:
+        name, _, at = value.partition('@')
+        try:
+            accepted.append({'check': name, **({'at': float(at)} if at else {}), 'note': 'command line'})
+        except ValueError:
+            raise RnError(f'--accept {value}: CHECK or CHECK@SECONDS, e.g. dead_air@12.5') from None
+    return accepted
+
+
+def qa_command(path: str, *, edl: str | None, frames: int | None, size: str | None, fps: str | None, lufs: float | None,
+               lufs_tolerance: float, true_peak: float | None, require_audio: bool, accept: list[dict] | None = None) -> dict:
+    edit = load(edl) if edl else None
+    checks: list[dict] = []
+    accepts = (edit.accept if edit else []) + (accept or [])
+
+    def check(name: str, status: str, detail: str):
+        checks.append({'check': name, 'status': status, 'detail': detail})
+
+    def keep(name: str, found: list, span) -> tuple[list, int]:
+        """Findings of an interval check minus those accepted (an accept "at" inside the interval, or without "at")."""
+        kept = [f for f in found if not any(a['check'] == name and ('at' not in a or span(f)[0] - 0.05 <= a['at'] <= span(f)[1] + 0.05)
+                                            for a in accepts)]
+        return kept, len(found) - len(kept)
+
+    def note(text: str, dropped: int) -> str:
+        return text + (f' ({dropped} accepted)' if dropped else '')
+
+    info = probe(path, exact=True)
+    video, audio = info['video'], info['audio']
+    if not video or video['still']:
+        raise RnError(f'{path}: no video stream')
+    expected_frames = frames or (edit.total_frames if edit else None)
+    expected_size = size or (f'{edit.width}x{edit.height}' if edit else None)
+    expected_fps = Fraction(fps) if fps else (edit.fps if edit else None)
+    if lufs is None and edit and edit.lufs is not None:
+        lufs = edit.lufs
+    if true_peak is None:
+        true_peak = edit.true_peak if edit else -1.0
+    require_audio = require_audio or bool(edit and (edit.audio or any(c.audio and c.has_audio for c in edit.base)))
+
+    actual_fps = Fraction(video['fps'])
+    frame_time = float(1 / actual_fps)
+    count = video['frames']
+    if expected_frames is not None:
+        check('frames', 'PASS' if count == expected_frames else 'FAIL', f'{count} decoded, expected {expected_frames}')
+    else:
+        check('frames', 'PASS', f'{count} decoded')
+    if expected_fps is not None:
+        check('fps', 'PASS' if actual_fps == expected_fps else 'FAIL', f'{video["fps"]}, expected {expected_fps}')
+    dims = f'{video["width"]}x{video["height"]}'
+    if expected_size:
+        check('size', 'PASS' if dims == expected_size else 'FAIL', f'{dims}, expected {expected_size}')
+    if video['width'] % 2 or video['height'] % 2:
+        check('size', 'FAIL', f'{dims}: odd dimensions break yuv420p players')
+    check('codec', 'PASS' if video['codec'] == 'h264' else ('WARN' if video['codec'] == 'hevc' else 'FAIL'),
+          f'{video["codec"]} {video["profile"] or ""}'.strip() + ('' if video['codec'] == 'h264' else ' (deliver H.264 for widest playback)'))
+    check('pix_fmt', 'PASS' if video['pix_fmt'] == 'yuv420p' else 'FAIL', f'{video["pix_fmt"]}' + ('' if video['pix_fmt'] == 'yuv420p' else ' (players and platforms expect yuv420p)'))
+    check('sar', 'PASS' if video['sar'] == '1:1' else 'FAIL', f'{video["sar"]}' + ('' if video['sar'] == '1:1' else ' (non-square pixels display stretched)'))
+    tags = (video['color_space'], video['color_primaries'], video['color_transfer'])
+    check('color', 'PASS' if tags == ('bt709', 'bt709', 'bt709') else 'WARN', 'space/primaries/transfer = ' + '/'.join(str(t) for t in tags))
+    if video['codec'] == 'h264':
+        fixed = _fixed_frame_rate(path)
+        if fixed is not None:
+            check('fixed_frame_rate', 'PASS' if fixed else 'WARN', 'SPS fixed_frame_rate_flag=1' if fixed else
+                  'SPS fixed_frame_rate_flag=0: some players time frames from the VUI and show the wrong length (rn finish fixes it)')
+    if info['faststart'] is not None:
+        check('faststart', 'PASS' if info['faststart'] else 'FAIL', 'moov before mdat' if info['faststart'] else 'moov at the end: remux with -movflags +faststart')
+
+    video_seconds = count * frame_time
+    if audio:
+        # Matroska/WebM carry no per-stream duration; the container's is the best available then.
+        audio_seconds = audio['duration'] if audio['duration'] is not None else info['duration']
+        if audio_seconds is None:
+            check('av_duration', 'WARN', f'video {video_seconds:.3f}s, audio duration unknown')
+        else:
+            drift = abs(audio_seconds - video_seconds)
+            check('av_duration', 'PASS' if drift <= max(frame_time, 0.05) else 'WARN',
+                  f'video {video_seconds:.3f}s, audio {audio_seconds:.3f}s')
+        loud = measure(path)
+        tp, integrated = loud['true_peak'], loud['lufs']
+        if tp is not None:
+            check('true_peak', 'PASS' if tp <= true_peak else 'FAIL', f'{tp:.1f} dBTP (limit {true_peak:.1f})')
+        if integrated is not None and integrated != float('-inf'):
+            if lufs is not None:
+                ok = abs(integrated - lufs) <= lufs_tolerance
+                check('loudness', 'PASS' if ok else 'WARN', f'{integrated:.1f} LUFS (target {lufs:.1f} ±{lufs_tolerance:g}), LRA {loud["lra"]}')
+            else:
+                check('loudness', 'PASS', f'{integrated:.1f} LUFS, LRA {loud["lra"]}')
+            sound = _sound(path, video_seconds)
+            silence, dropped = keep('dead_air', sound['silence'], lambda f: f)
+            check('dead_air', 'WARN' if silence else 'PASS', note(
+                ', '.join(f'{a:.2f}-{b:.2f}s' for a, b in silence) + ' below -70 dBFS (fill with a tail, room tone or bed)'
+                if silence else 'no digital silence inside the mix', dropped))
+            jumps, dropped = keep('level_jumps', sound['jumps'], lambda f: (f[0] - 0.1, f[0]))
+            check('level_jumps', 'WARN' if jumps else 'PASS', note(
+                ', '.join(f'{t:.1f}s {a:.0f}->{b:.0f} dB' for t, a, b in jumps[:8]) + (f' (+{len(jumps) - 8} more)' if len(jumps) > 8 else '')
+                if jumps else f'no jump >= {JUMP_DB} dB between 100 ms windows', dropped))
+            from .signal import clicks, pcm
+            pops, dropped = keep('clicks', clicks(pcm(path)), lambda f: (f, f))
+            check('clicks', 'WARN' if pops else 'PASS', note(
+                ', '.join(f'{t:.3f}s' for t in pops[:8]) + ' (a lone sample step: an edit without a fade, or a glitch)'
+                if pops else 'no lone sample steps', dropped))
+        else:
+            check('loudness', 'WARN', 'audio track is silent')
+    else:
+        check('audio', 'FAIL' if require_audio else 'WARN', 'no audio track')
+    container = info['duration'] or 0
+    if container > video_seconds + max(frame_time, 0.05):
+        check('container_duration', 'WARN', f'container {container:.3f}s > video {video_seconds:.3f}s (a longer stream stretches playback)')
+
+    scan = _scan(path)
+    black = [b for b in scan['black'] if not _covered(b, _intended(edit, 'black'), video_seconds)]
+    black, dropped = keep('black_frames', black, lambda f: f)
+    check('black_frames', 'WARN' if black else 'PASS',
+          note(', '.join(f'{a:.2f}-{b:.2f}s' for a, b in black) if black else 'none outside intended color clips', dropped))
+    freezes = [f for f in scan['freeze'] if not _covered(f, _intended(edit, 'freeze'), video_seconds)]
+    freezes, dropped = keep('frozen_frames', freezes, lambda f: (f[0], f[1] if f[1] is not None else video_seconds))
+    check('frozen_frames', 'WARN' if freezes else 'PASS', note(
+        ', '.join(f'{a:.2f}-{(b if b is not None else video_seconds):.2f}s' for a, b in freezes) if freezes else 'none outside stills', dropped))
+    if scan['crop']:
+        w, h, x, y = scan['crop']
+        bars = w < video['width'] - 8 or h < video['height'] - 8
+        check('black_bars', 'WARN' if bars else 'PASS', f'picture area {w}x{h}+{x}+{y} of {dims}' if bars else 'full frame used')
+
+    for item in checks:  # a whole-check accept (no "at") turns a WARN into an accepted PASS; a FAIL is never waived
+        waiver = next((a for a in accepts if a['check'] == item['check'] and 'at' not in a), None)
+        if item['status'] == 'WARN' and waiver:
+            item['status'], item['accepted'] = 'PASS', waiver.get('note', '')
+            item['detail'] += f' (accepted: {waiver.get("note") or "intended"})'
+    failed = [c for c in checks if c['status'] == 'FAIL']
+    warned = [c for c in checks if c['status'] == 'WARN']
+    return {'path': path, 'status': 'FAIL' if failed else 'PASS', 'failed': len(failed), 'warnings': len(warned), 'checks': checks}

rn/ref.py

@@ -0,0 +1,74 @@
+"""rn ref: the measurable half of breaking down a reference edit, in one folder. Shot boundaries (with suspects to
+check by eye), shot lengths, the audio facts from rn listen, and contact sheets covering every frame (or every Nth),
+paged so each page can be viewed. What a shot does and why it works is for you to read off the sheets; nothing here
+interprets: GUIDE.md, copied into the folder, is how to read it into breakdown.md. Not yet measured: on-screen text (OCR)."""
+from __future__ import annotations
+
+import json
+import shutil
+from fractions import Fraction
+from pathlib import Path
+
+from .cuts import DEFAULT_THRESHOLD, cuts_command
+from .ff import RnError, probe
+from .frames import sheet_command
+
+
+def ref_command(path: str, *, out: str | None, every: int, transcribe: bool, language: str | None, model: str,
+                threshold: float = DEFAULT_THRESHOLD, width: int = 192) -> dict:
+    info = probe(path, exact=True)
+    if not info['video'] or info['video']['still']:
+        raise RnError(f'{path}: not a video')
+    folder = Path(out) if out else Path('ref') / Path(path).stem
+    folder.mkdir(parents=True, exist_ok=True)
+    cuts = cuts_command(path, threshold=threshold, min_gap=0.3, sheet=str(folder / 'cuts.jpg'), max_kb=125)
+    frames = info['video']['frames']
+    coverage = sheet_command([path], out=str(folder / 'frames.jpg'), every=every, rate=None, indices=None, seconds=None,
+                             count=None, width=width, columns=6, max_kb=125)['pages']
+    listen = None
+    if info['audio']:
+        from .listen import listen_command
+        listen = listen_command(path, out=str(folder / 'listen.jpg'), transcribe=transcribe, language=language, model=model)
+    shutil.copyfile(Path(__file__).with_name('ref_guide.md'), folder / 'GUIDE.md')
+    result = {
+        'path': path,
+        'folder': str(folder),
+        'probe': info,
+        'shots': cuts['shots'],
+        'cuts': cuts['cuts'],
+        'suspects': cuts['suspects'],
+        'cut_sheets': [p['path'] for p in cuts.get('sheet', [])],
+        'coverage': {'frames': frames, 'every': every, 'sampled': sum(len(p['indices']) for p in coverage),
+                     'pages': [p['path'] for p in coverage],
+                     'page_frames': [[p['indices'][0], p['indices'][-1]] for p in coverage]},
+        'listen': listen,
+        'cut_sync': cut_sync(cuts['cuts'], listen['onsets'] if listen else [], Fraction(cuts['fps'])),
+    }
+    (folder / 'ref.json').write_text(json.dumps(result, indent=1, ensure_ascii=False, default=str))
+    return result
+
+
+def cut_sync(cuts: list[dict], onsets: list[float], fps: Fraction, tolerance: int = 2) -> dict | None:
+    """How tightly the cuts follow the audio: each cut's offset in frames to the nearest onset (negative = the cut
+    leads the sound) and the share within +-tolerance frames. A high share means the edit is cut on the sound."""
+    if not cuts or not onsets:
+        return None
+    offsets = [round(float((cut['time'] - min(onsets, key=lambda t: abs(t - cut['time']))) * fps)) for cut in cuts]
+    return {'share': round(sum(abs(o) <= tolerance for o in offsets) / len(offsets), 2), 'tolerance_frames': tolerance,
+            'offsets_frames': offsets}
+
+
+def summary_lines(result: dict) -> list[str]:
+    shots = result['shots']
+    lengths = ', '.join(f'{s["duration"]:.2f}' for s in shots[:12]) + (' ...' if len(shots) > 12 else '')
+    coverage = result['coverage']
+    lines = [f'{result["folder"]}/ref.json',
+             f'{len(shots)} shots ({lengths} s), {len(result["suspects"])} suspect cuts to check: {", ".join(result["cut_sheets"]) or "-"}',
+             f'frame coverage: {coverage["sampled"]} of {coverage["frames"]} frames (every {coverage["every"]}) on {len(coverage["pages"])} pages']
+    if result['listen']:
+        from .listen import summary_lines as listen_lines
+        lines += listen_lines(result['listen'])
+    if result['cut_sync']:
+        lines.append(f'cuts on an onset (+-2 frames): {result["cut_sync"]["share"]:.0%}')
+    lines.append(f'next: read {result["folder"]}/GUIDE.md and write {result["folder"]}/breakdown.md')
+    return lines