renoise-kit 0.5.0__py3-none-any.whl

rn/assets.py

@@ -0,0 +1,125 @@
+"""rn assets: licensed sound effects and real overlay footage (film grain scans, light leaks, dust, paper) from the
+Renoise asset library on the CDN. Not baked into the image: the files are large, each needs its licence recorded, and a
+template upgrade replaces every user's sandbox, so content that changes often must not ride on the image.
+
+Manifest (JSON at RN_ASSETS_URL): {"version": 1, "assets": [{"id", "kind": "sfx"|"overlay"|"texture"|"music", "title",
+"tags": [...], "duration"?, "width"?, "height"?, "license", "source", "url" (absolute or relative to the manifest),
+"sha256", "bytes"}]}. Every file is checked against its sha256 and cached by it.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from .ff import RnError
+
+DEFAULT_URL = 'https://assets.renoise.ai/static/rn-assets/manifest.json'
+KINDS = ('sfx', 'overlay', 'texture', 'music')
+
+
+def _url() -> str:
+    return os.environ.get('RN_ASSETS_URL', DEFAULT_URL)
+
+
+def _cache() -> Path:
+    return Path(os.environ.get('RN_ASSETS_CACHE', Path.home() / '.cache' / 'rn-assets'))
+
+
+def _open(url: str):
+    try:
+        return urllib.request.urlopen(url, timeout=30)
+    except urllib.error.HTTPError as error:
+        if error.code in (403, 404):
+            raise RnError(f'the asset library is not published at {url} yet ({error.code})') from None
+        raise RnError(f'{url}: HTTP {error.code}') from None
+    except (urllib.error.URLError, OSError) as error:
+        raise RnError(f'{url}: {getattr(error, "reason", error)}') from None
+
+
+def fetch_checked(source: str, digest: str, cached: Path, *, name: str) -> Path:
+    """Downloads `source` to `cached` once, refusing content whose sha256 is not `digest`."""
+    if cached.exists():
+        return cached
+    cached.parent.mkdir(parents=True, exist_ok=True)
+    partial = cached.with_name(f'{cached.name}.part')
+    hasher = hashlib.sha256()
+    with _open(source) as response, open(partial, 'wb') as file:
+        while chunk := response.read(1 << 20):
+            hasher.update(chunk)
+            file.write(chunk)
+    if hasher.hexdigest() != digest:
+        partial.unlink()
+        raise RnError(f'{name}: checksum mismatch, refusing the download')
+    partial.rename(cached)
+    return cached
+
+
+def manifest() -> tuple[str, list[dict]]:
+    url = _url()
+    if '://' not in url:
+        url = Path(url).resolve().as_uri()
+    with _open(url) as response:
+        try:
+            data = json.loads(response.read())
+        except json.JSONDecodeError as error:
+            raise RnError(f'{url}: not JSON ({error})') from None
+    assets = data.get('assets') if isinstance(data, dict) else None
+    if not isinstance(assets, list):
+        raise RnError(f'{url}: expected {{"version": 1, "assets": [...]}}')
+    return url, assets
+
+
+def search_command(query: str | None, *, kind: str | None, limit: int) -> dict:
+    if kind and kind not in KINDS:
+        raise RnError(f'--kind: one of {", ".join(KINDS)}')
+    url, assets = manifest()
+    words = [w for w in (query or '').lower().split() if w]
+    scored = []
+    for asset in assets:
+        if kind and asset.get('kind') != kind:
+            continue
+        haystack = ' '.join([asset.get('id', ''), asset.get('title', ''), *asset.get('tags', [])]).lower()
+        score = sum(haystack.count(w) for w in words)
+        if words and not score:
+            continue
+        scored.append((score, asset))
+    scored.sort(key=lambda pair: (-pair[0], pair[1].get('id', '')))
+    keep = ('id', 'kind', 'title', 'tags', 'duration', 'width', 'height', 'license')
+    return {'manifest': url, 'total': len(scored), 'assets': [{k: a[k] for k in keep if k in a} for _, a in scored[:limit]]}
+
+
+def get_command(ids: list[str], *, out: str) -> dict:
+    url, assets = manifest()
+    by_id = {a.get('id'): a for a in assets}
+    missing = [i for i in ids if i not in by_id]
+    if missing:
+        raise RnError(f'unknown asset id(s) {missing}; find ids with rn assets search')
+    out_dir = Path(out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    cache = _cache()
+    cache.mkdir(parents=True, exist_ok=True)
+    files = []
+    for asset_id in ids:
+        asset = by_id[asset_id]
+        digest = asset.get('sha256', '')
+        source = urllib.parse.urljoin(url, asset['url'])
+        cached = fetch_checked(source, digest, cache / digest, name=asset_id)
+        target = out_dir / f'{asset_id}{Path(urllib.parse.urlparse(source).path).suffix}'
+        shutil.copyfile(cached, target)
+        files.append({'id': asset_id, 'path': str(target), 'license': asset.get('license'), 'source': asset.get('source')})
+    return {'files': files}
+
+
+def summary_lines(result: dict) -> list[str]:
+    if 'files' in result:
+        return [f'{f["path"]}  ({f["license"]})' for f in result['files']]
+    lines = [f'{a["id"]}  [{a["kind"]}] {a.get("title", "")}' + (f'  {a["duration"]}s' if a.get('duration') else '')
+             + f'  tags: {", ".join(a.get("tags", []))}' for a in result['assets']]
+    lines.append(f'{len(result["assets"])} of {result["total"]} matches')
+    return lines

rn/audio.py

@@ -0,0 +1,79 @@
+"""Loudness and true-peak finishing shared by `rn assemble` and `rn finish`.
+
+The rule (spec/mcp/03-media-kit.md §5): mix without normalisation, gain to the LUFS target, limit with
+alimiter's auto-level off, then measure the true peak on the ENCODED AAC — the encoder adds 1-2 dB of
+overshoot, so a limiter that looks safe on PCM fails after encoding. Re-encode only the audio until it fits.
+"""
+from __future__ import annotations
+
+import re
+import subprocess
+from pathlib import Path
+
+from .ff import RnError, run
+
+AAC_BITRATE = '192k'
+SAMPLE_RATE = 48000
+MAX_LIMITER_PASSES = 6
+
+
+def measure(path: str | Path, *, stream: str = 'a:0') -> dict:
+    """Integrated loudness (LUFS), loudness range and true peak (dBTP) via ebur128."""
+    result = subprocess.run(['ffmpeg', '-hide_banner', '-nostdin', '-i', str(path), '-map', f'0:{stream}',
+                             '-af', 'ebur128=peak=true:framelog=quiet', '-f', 'null', '-'], capture_output=True, text=True)
+    if result.returncode != 0:
+        raise RnError(f'loudness measurement failed: {result.stderr.strip().splitlines()[-1:]}')
+    summary = result.stderr[result.stderr.rfind('Summary:'):]
+
+    def pick(label: str) -> float | None:
+        match = re.search(rf'{label}:\s+(-?inf|-?[\d.]+)', summary)
+        if not match:
+            return None
+        value = match.group(1)
+        return float('-inf') if 'inf' in value else float(value)
+
+    return {'lufs': pick('I'), 'lra': pick('LRA'), 'true_peak': pick('Peak')}
+
+
+def finish_audio(mix_wav: Path, out_m4a: Path, *, lufs: float | None, true_peak: float, reference: Path | None = None) -> dict:
+    """mix_wav -> AAC whose encoded true peak is at or below `true_peak` dBTP. The LUFS gain is measured on `reference`
+    (default mix_wav): an excerpt keeps the level of the whole mix."""
+    gain_db = 0.0
+    if lufs is not None:
+        measured = measure(reference or mix_wav)['lufs']
+        if measured is not None and measured != float('-inf'):
+            gain_db = max(-30.0, min(30.0, lufs - measured))
+    ceiling = true_peak - 0.5  # headroom for encoder overshoot; tightened below if still too hot
+    attempts = []
+    for _ in range(MAX_LIMITER_PASSES):
+        limit = 10 ** (ceiling / 20)
+        run(['ffmpeg', '-i', str(mix_wav), '-af',
+             f'volume={gain_db:.3f}dB,alimiter=limit={max(0.0625, limit):.5f}:level=disabled:latency=1:attack=5:release=50,'
+             f'aresample={SAMPLE_RATE}', '-c:a', 'aac', '-b:a', AAC_BITRATE, '-ar', str(SAMPLE_RATE), '-ac', '2', '-y', str(out_m4a)])
+        measured = measure(out_m4a)
+        attempts.append({'limiter_dbfs': round(ceiling, 2), 'true_peak': measured['true_peak']})
+        if measured['true_peak'] is None or measured['true_peak'] <= true_peak:
+            return {'gain_db': round(gain_db, 2), **measured, 'attempts': attempts}
+        ceiling -= max(0.5, measured['true_peak'] - true_peak)
+    raise RnError(f'true peak stayed above {true_peak} dBTP after {MAX_LIMITER_PASSES} limiter passes: {attempts}')
+
+
+# Frame properties win over encoder flags in ffmpeg 7+, so tag the frames themselves too.
+BT709 = 'setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709'
+VIDEO_ENCODE = ['-c:v', 'libx264', '-profile:v', 'high', '-pix_fmt', 'yuv420p',
+                '-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709']
+# fixed_frame_rate_flag=1 in the SPS: with 0, some players and platforms time frames from the VUI tick and show a
+# 30 fps film at half its length (promo-video, 2026-09-29). Only for constant-rate input: x264 then ignores timestamps.
+CFR_VUI = ['-x264-params', 'force-cfr=1']
+
+
+def mux(video: Path, audio_m4a: Path | None, out: Path, *, frames: int) -> None:
+    """Copies both streams into an MP4 with moov first. The audio was already cut to the video's length by sample;
+    no -shortest: on ffmpeg 7 it trims the video to the AAC stream, which can end a few ms early, dropping frames."""
+    args = ['ffmpeg', '-i', str(video)]
+    if audio_m4a:
+        args += ['-i', str(audio_m4a), '-map', '0:v:0', '-map', '1:a:0', '-c:a', 'copy']
+    else:
+        args += ['-map', '0:v:0']
+    out.parent.mkdir(parents=True, exist_ok=True)
+    run(args + ['-c:v', 'copy', '-frames:v', str(frames), '-movflags', '+faststart', '-y', str(out)])

rn/captions.py

@@ -0,0 +1,343 @@
+"""rn captions: mechanical caption chunking, script alignment, safe-area / face-aware placement.
+
+Writes one plain .ass (single readable style), an .srt, and a JSON of events with word timing so the agent can render
+its own styled captions. Never imposes a style. Contract: spec/mcp/03-media-kit.md §3.1.
+"""
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+from difflib import SequenceMatcher
+from pathlib import Path
+
+from .ff import RnError
+
+# Approximate platform UI clearance as fractions of the frame, NOT exact platform specs: the apps move their overlays
+# between releases. top/bottom = reserved by caption/username/progress bars, left/right = reserved by action buttons.
+SAFE_MARGINS = {
+    'tiktok': {'top': 0.13, 'bottom': 0.22, 'left': 0.06, 'right': 0.16},
+    'reels': {'top': 0.12, 'bottom': 0.20, 'left': 0.06, 'right': 0.12},
+    'youtube': {'top': 0.05, 'bottom': 0.08, 'left': 0.05, 'right': 0.05},  # 16:9 title-safe + player controls
+    'none': {'top': 0.02, 'bottom': 0.02, 'left': 0.02, 'right': 0.02},
+}
+BASE_CHARS = {'cjk': 14, 'latin': 32}  # per line at 1080 px width
+LATIN_EM = 0.55  # average advance of a Latin glyph in em
+OPENERS = set('「『（([“‘《〈【')
+SENTENCE_END = set('。！？.!?…‼⁇')
+SOFT_BREAK = set('，、；：,;:—')
+CLOSERS = set('」』）)]”’》〉】"\'')
+FONTS = {'zh': 'Noto Sans CJK SC', 'yue': 'Noto Sans CJK SC', 'ja': 'Noto Sans CJK JP', 'ko': 'Noto Sans CJK KR'}
+PAUSE_BREAK = 0.5  # seconds of silence that ends a caption
+
+
+def _norm(text: str) -> str:
+    return ''.join(c for c in text.lower() if c.isalnum())
+
+
+def _wide(char: str) -> bool:
+    return unicodedata.east_asian_width(char) in 'WF'
+
+
+def _width(text: str, cjk: bool) -> float:
+    """Line-limit measure: a wide char is 1; in CJK mode a Latin char is half."""
+    return sum(1 if _wide(c) else (0.5 if cjk else 1) for c in text)
+
+
+def _em(text: str) -> float:
+    return sum(1.0 if _wide(c) else LATIN_EM for c in text)
+
+
+def _join(texts: list[str], cjk: bool) -> str:
+    out = ''
+    for text in texts:
+        glue = ' ' if out and (not cjk or (out[-1].isascii() and out[-1].isalnum() and text[0].isascii() and text[0].isalnum())) else ''
+        out += glue + text
+    return out
+
+
+def _is_cjk_language(language: str, words: list[dict]) -> bool:
+    if language:
+        return language.split('-')[0].lower() in ('zh', 'ja', 'yue')
+    sample = ''.join(w['word'] for w in words)
+    return bool(sample) and sum(_wide(c) for c in sample) / len(sample) > 0.3
+
+
+def _attach_punctuation(tokens: list[dict]) -> list[dict]:
+    """Closing punctuation joins the previous token, opening brackets join the next: no unit starts with 、。」 or ends with 「."""
+    units: list[dict] = []
+    prefix = ''
+    for token in tokens:
+        if not any(c.isalnum() for c in token['text']):
+            if all(c in OPENERS for c in token['text']) or not units:
+                prefix += token['text']
+            else:
+                units[-1]['text'] += token['text']
+            continue
+        units.append({**token, 'text': prefix + token['text']})
+        prefix = ''
+    if prefix and units:
+        units[-1]['text'] += prefix
+    return units
+
+
+def _transcript_units(words: list[dict], cjk: bool) -> list[dict]:
+    raw: list[dict] = []
+    if cjk:
+        for word in words:
+            pieces = re.findall(r"[A-Za-z0-9]+(?:['’\-][A-Za-z0-9]+)*|\S", word['word'])
+            lexical = sum(any(c.isalnum() for c in p) for p in pieces) or 1
+            span = (word['end'] - word['start']) / lexical
+            cursor = word['start']
+            for piece in pieces:
+                if any(c.isalnum() for c in piece):
+                    raw.append({'text': piece, 'start': cursor, 'end': cursor + span})
+                    cursor += span
+                else:
+                    raw.append({'text': piece, 'start': cursor, 'end': cursor})
+    else:
+        spaced = any(w['word'].startswith(' ') for w in words[1:])
+        for word in words:
+            text = word['word'].strip()
+            if not text:
+                continue
+            if spaced and raw and not word['word'].startswith(' '):  # Whisper sub-word piece: glue to the previous word
+                raw[-1]['text'] += text
+                raw[-1]['end'] = word['end']
+            else:
+                raw.append({'text': text, 'start': word['start'], 'end': word['end']})
+    return _attach_punctuation(raw)
+
+
+def _script_units(script: str, cjk: bool) -> list[dict]:
+    pieces = re.findall(r"[A-Za-z0-9]+(?:['’\-][A-Za-z0-9]+)*|\S", script) if cjk else script.split()
+    return _attach_punctuation([{'text': p} for p in pieces])
+
+
+def _align_script(transcript: list[dict], script: list[dict]) -> tuple[list[dict], dict]:
+    """Script text with transcript timing; unmatched script runs get timing interpolated across the transcript gap."""
+    matcher = SequenceMatcher(None, [_norm(u['text']) for u in transcript], [_norm(u['text']) for u in script], autojunk=False)
+    aligned: list[dict] = [{}] * len(script)
+    matched = 0
+    unmatched: list[dict] = []
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        if tag == 'equal':
+            matched += j2 - j1
+            for offset in range(j2 - j1):
+                aligned[j1 + offset] = {'text': script[j1 + offset]['text'], 'start': transcript[i1 + offset]['start'], 'end': transcript[i1 + offset]['end']}
+            continue
+        if i2 > i1:
+            span_start, span_end = transcript[i1]['start'], transcript[i2 - 1]['end']
+        else:  # script-only run: use the silence between the neighbouring transcript units
+            span_start = transcript[i1 - 1]['end'] if i1 > 0 else transcript[0]['start']
+            span_end = transcript[i1]['start'] if i1 < len(transcript) else transcript[-1]['end']
+        span_end = max(span_start, span_end)
+        step = (span_end - span_start) / max(j2 - j1, 1)
+        for offset in range(j2 - j1):
+            aligned[j1 + offset] = {'text': script[j1 + offset]['text'], 'start': span_start + step * offset, 'end': span_start + step * (offset + 1)}
+        unmatched.append({'script': _join([u['text'] for u in script[j1:j2]], False), 'transcript': _join([u['text'] for u in transcript[i1:i2]], False),
+                          'start': round(span_start, 3), 'end': round(span_end, 3)})
+    stats = {'match_ratio': round(matched / len(script), 3) if script else 0.0, 'script_units': len(script), 'transcript_units': len(transcript),
+             'matched_units': matched, 'unmatched_spans': unmatched[:20], 'unmatched_span_count': len(unmatched)}
+    return aligned, stats
+
+
+def _layout(units: list[dict], max_width: float, cjk: bool) -> list[list[dict]]:
+    """Greedy fill to find the line count, then the narrowest width that keeps it: lines come out balanced
+    ("and a case that fits / in your pocket.", not "and a case that fits in your / pocket.")."""
+    lines = _greedy(units, max_width, cjk)
+    if len(lines) < 2:
+        return lines
+    width = max(_width(_join([u['text'] for u in line], cjk), cjk) for line in lines)
+    while width > 1:
+        tighter = _greedy(units, width - 0.5, cjk)
+        if len(tighter) > len(lines):
+            break
+        lines, width = tighter, width - 0.5
+    return lines
+
+
+def _greedy(units: list[dict], max_width: float, cjk: bool) -> list[list[dict]]:
+    lines: list[list[dict]] = []
+    for unit in units:
+        if lines and _width(_join([u['text'] for u in lines[-1] + [unit]], cjk), cjk) <= max_width:
+            lines[-1].append(unit)
+        else:
+            lines.append([unit])
+    return lines
+
+
+def _tail(text: str) -> str:
+    stripped = text.rstrip(''.join(CLOSERS))
+    return stripped[-1] if stripped else ''
+
+
+def _chunk(units: list[dict], *, max_chars: int, max_lines: int, min_duration: float, max_duration: float, cjk: bool) -> list[list[dict]]:
+    chunks: list[list[dict]] = []
+    current: list[dict] = []
+    for index, unit in enumerate(units):
+        if current and (unit['end'] - current[0]['start'] > max_duration or len(_layout(current + [unit], max_chars, cjk)) > max_lines):
+            chunks.append(current)
+            current = []
+        current.append(unit)
+        duration = unit['end'] - current[0]['start']
+        gap = units[index + 1]['start'] - unit['end'] if index + 1 < len(units) else 0
+        fill = _width(_join([u['text'] for u in current], cjk), cjk) / (max_chars * max_lines)
+        tail = _tail(unit['text'])
+        if duration >= min_duration and (tail in SENTENCE_END or gap >= PAUSE_BREAK or (tail in SOFT_BREAK and fill >= 0.5)):
+            chunks.append(current)
+            current = []
+    if current:
+        chunks.append(current)
+    return chunks
+
+
+def _overlaps(box: tuple[float, float, float, float], faces: list[tuple[float, float, float, float]], pad: float) -> bool:
+    x, y, w, h = box
+    return any(x < fx + fw + pad and fx - pad < x + w and y < fy + fh + pad and fy - pad < y + h for fx, fy, fw, fh in faces)
+
+
+def _faces_in_span(frames: list[dict], start: float, end: float, scale: tuple[float, float]) -> list[tuple[float, float, float, float]]:
+    before = [f for f in frames if f['t'] < start]
+    chosen = [f for f in frames if start <= f['t'] <= end] + before[-1:]  # sparse sampling: the last frame before the span still holds
+    return [(f_['box'][0] * scale[0], f_['box'][1] * scale[1], f_['box'][2] * scale[0], f_['box'][3] * scale[1]) for f in chosen for f_ in f.get('faces', [])]
+
+
+def _srt_time(seconds: float) -> str:
+    ms = round(seconds * 1000)
+    return f'{ms // 3600000:02d}:{ms // 60000 % 60:02d}:{ms // 1000 % 60:02d},{ms % 1000:03d}'
+
+
+def captions_command(words_json: str, *, script: str | None = None, faces_json: str | None = None, out: str, width: int, height: int,
+                     max_chars: int | None = None, max_lines: int = 2, min_duration: float = 0.6, max_duration: float = 4.0,
+                     safe: str = 'auto', language: str | None = None) -> dict:
+    try:
+        import pysubs2
+    except ImportError as error:
+        raise RnError('captions needs pysubs2 (pip install pysubs2)') from error
+    if safe not in ('auto', *SAFE_MARGINS):
+        raise RnError(f'--safe must be one of auto, {", ".join(SAFE_MARGINS)}')
+    if width <= 0 or height <= 0 or max_lines < 1 or min_duration > max_duration:
+        raise RnError('captions: width/height must be positive, max_lines >= 1, min_duration <= max_duration')
+    try:
+        listen = json.loads(Path(words_json).read_text(encoding='utf-8'))
+    except (OSError, ValueError) as error:
+        raise RnError(f'cannot read words json {words_json}: {error}') from error
+    words = [w for w in listen.get('words', []) if str(w.get('word', '')).strip()]
+    if not words:
+        raise RnError(f'{words_json} has no words; run `rn listen --transcribe --json` first')
+    language = language or listen.get('language') or ''
+    cjk = _is_cjk_language(language, words)
+    warnings: list[str] = []
+
+    units = _transcript_units(words, cjk)
+    alignment = None
+    if script is not None:
+        try:
+            script_text = Path(script).read_text(encoding='utf-8')
+        except OSError as error:
+            raise RnError(f'cannot read script {script}: {error}') from error
+        script_units = _script_units(script_text, cjk)
+        if not script_units:
+            raise RnError(f'script {script} is empty')
+        units, alignment = _align_script(units, script_units)
+        if alignment['match_ratio'] < 0.5:
+            warnings.append(f"script matches only {alignment['match_ratio']:.0%} of the transcript; check it is the same take and language")
+
+    safe_name = safe if safe != 'auto' else ('tiktok' if width / height < 0.8 else 'youtube')
+    margins = SAFE_MARGINS[safe_name]
+    safe_left, safe_right = margins['left'] * width, width - margins['right'] * width
+    safe_width = safe_right - safe_left
+    max_chars = max_chars or max(4, round(BASE_CHARS['cjk' if cjk else 'latin'] * width / 1080))
+    em_per_char = 1.0 if cjk else LATIN_EM
+    font_size = round(min(height * (0.03 if height > width else 0.05), safe_width / (max_chars * em_per_char)))
+    font_name = FONTS.get(language.split('-')[0].lower(), 'Noto Sans') if language else ('Noto Sans CJK SC' if cjk else 'Noto Sans')
+
+    chunks = _chunk(units, max_chars=max_chars, max_lines=max_lines, min_duration=min_duration, max_duration=max_duration, cjk=cjk)
+    for chunk in chunks:
+        for unit in chunk:
+            if _width(unit['text'], cjk) > max_chars:
+                warnings.append(f"unit '{unit['text']}' at {unit['start']:.2f}s is wider than max_chars={max_chars}; kept whole")
+
+    frames: list[dict] = []
+    scale = (1.0, 1.0)
+    if faces_json:
+        try:
+            faces = json.loads(Path(faces_json).read_text(encoding='utf-8'))
+        except (OSError, ValueError) as error:
+            raise RnError(f'cannot read faces json {faces_json}: {error}') from error
+        frames = faces.get('frames', [])
+        meta = faces.get('meta', {})
+        scale = (width / meta.get('width', width), height / meta.get('height', height))
+
+    events: list[dict] = []
+    moved: list[dict] = []
+    line_height = font_size * 1.2
+    for index, chunk in enumerate(chunks):
+        lines = [_join([u['text'] for u in line], cjk) for line in _layout(chunk, max_chars, cjk)]
+        box_w = min(safe_width, max(_em(line) for line in lines) * font_size)
+        box_h = len(lines) * line_height
+        bands = {'bottom': height - margins['bottom'] * height - box_h, 'top': margins['top'] * height, 'middle': (height - box_h) / 2}
+        box_x = (width - box_w) / 2
+        span_faces = _faces_in_span(frames, chunk[0]['start'], chunk[-1]['end'], scale) if frames else []
+        band = 'bottom'
+        if span_faces and _overlaps((box_x, bands['bottom'], box_w, box_h), span_faces, 0.01 * height):
+            free = [b for b in ('top', 'middle') if not _overlaps((box_x, bands[b], box_w, box_h), span_faces, 0.01 * height)]
+            if free:
+                band = free[0]
+                moved.append({'event': index, 'start': round(chunk[0]['start'], 3), 'end': round(chunk[-1]['end'], 3), 'from': 'bottom', 'to': band,
+                              'reason': 'face box overlaps the bottom caption band'})
+            else:
+                warnings.append(f'event {index} ({chunk[0]["start"]:.2f}s): faces overlap every caption band; left at bottom')
+        events.append({'start': chunk[0]['start'], 'end': chunk[-1]['end'], 'lines': lines, 'text': _join([u['text'] for u in chunk], cjk),
+                       'words': [{'text': u['text'], 'start': round(u['start'], 3), 'end': round(u['end'], 3)} for u in chunk],
+                       'position': {'band': band, 'x': round(box_x), 'y': round(bands[band]), 'w': round(box_w), 'h': round(box_h),
+                                    'anchor': {'bottom': 'bottom-center', 'top': 'top-center', 'middle': 'middle-center'}[band]},
+                       'moved_for_face': band != 'bottom'})
+    # Hold short captions up to min_duration, never into the next caption.
+    for index, event in enumerate(events):
+        next_start = events[index + 1]['start'] if index + 1 < len(events) else float('inf')
+        event['end'] = round(min(max(event['end'], event['start'] + min_duration), next_start), 3)
+        event['start'] = round(event['start'], 3)
+        if event['end'] - event['start'] < min_duration - 1e-6:
+            warnings.append(f"event {index} at {event['start']:.2f}s is {event['end'] - event['start']:.2f}s (< min_duration): the next caption follows too closely")
+
+    ass_path = Path(out)
+    srt_path, json_path = ass_path.with_suffix('.srt'), ass_path.with_suffix('.json')
+    ass_path.parent.mkdir(parents=True, exist_ok=True)
+
+    subs = pysubs2.SSAFile()
+    subs.info.update({'PlayResX': str(width), 'PlayResY': str(height), 'WrapStyle': '2'})  # WrapStyle 2: only our own line breaks
+    subs.styles = {'Default': pysubs2.SSAStyle(
+        fontname=font_name, fontsize=font_size, bold=True, primarycolor=pysubs2.Color(255, 255, 255, 0), outlinecolor=pysubs2.Color(0, 0, 0, 0),
+        backcolor=pysubs2.Color(0, 0, 0, 128), outline=max(2, round(font_size * 0.07)), shadow=1, alignment=pysubs2.Alignment.BOTTOM_CENTER,
+        marginl=round(safe_left), marginr=round(width - safe_right), marginv=round(margins['bottom'] * height))}
+    for event in events:
+        override = ''
+        if event['position']['band'] != 'bottom':
+            position = event['position']
+            an, y = (8, position['y']) if position['band'] == 'top' else (5, position['y'] + position['h'] / 2)
+            override = f"{{\\an{an}\\pos({round(width / 2)},{round(y)})}}"
+        subs.append(pysubs2.SSAEvent(start=round(event['start'] * 1000), end=round(event['end'] * 1000), style='Default', text=override + '\\N'.join(event['lines'])))
+    subs.save(str(ass_path), encoding='utf-8')
+
+    srt_path.write_text(''.join(f"{i}\n{_srt_time(e['start'])} --> {_srt_time(e['end'])}\n" + '\n'.join(e['lines']) + '\n\n' for i, e in enumerate(events, 1)), encoding='utf-8')
+    result = {'ass': str(ass_path), 'srt': str(srt_path), 'json': str(json_path), 'event_count': len(events), 'language': language or None,
+              'script_alignment': alignment, 'moved_for_faces': moved, 'warnings': warnings, 'safe': safe_name,
+              'font': font_name, 'font_size': font_size, 'max_chars': max_chars, 'max_lines': max_lines}
+    json_path.write_text(json.dumps({'meta': {k: result[k] for k in ('language', 'safe', 'font', 'font_size', 'max_chars', 'max_lines')} | {'width': width, 'height': height},
+                                     'events': events}, ensure_ascii=False, indent=1), encoding='utf-8')
+    return result
+
+
+def summary_lines(result: dict) -> list[str]:
+    lines = [f"captions: {result['event_count']} events, language {result['language'] or 'auto'}, safe={result['safe']}, "
+             f"{result['font']} {result['font_size']}px, max {result['max_chars']} chars x {result['max_lines']} lines",
+             f"  ass {result['ass']}  srt {result['srt']}  json {result['json']}"]
+    if result['script_alignment']:
+        stats = result['script_alignment']
+        lines.append(f"  script: {stats['match_ratio']:.0%} of {stats['script_units']} units matched Whisper; {stats['unmatched_span_count']} unmatched spans")
+        lines += [f"    {s['start']:.2f}-{s['end']:.2f}s script '{s['script']}' vs heard '{s['transcript']}'" for s in stats['unmatched_spans'][:5]]
+    lines += [f"  moved event {m['event']} ({m['start']:.2f}-{m['end']:.2f}s) {m['from']} -> {m['to']}: {m['reason']}" for m in result['moved_for_faces']]
+    lines += [f'  warning: {w}' for w in result['warnings']]
+    return lines

rn/capture.py

@@ -0,0 +1,97 @@
+"""rn capture: render an HTML page frame by frame to an RGBA PNG sequence (the EDL takes it as {"frames": ...}).
+
+Contract (after Katana's render.py + page.html): the page defines `window.renderFrame(i)` (may return a Promise) that
+draws frame i completely; the frame index IS the time, so nothing depends on the wall clock and any frame renders the
+same in any order or shard. Before the page's scripts run, `window.RN = {fps, frames, width, height, shard}` is set
+and the effects library is available as `window.RNFX` (rn fx). An optional `window.rnReady` Promise is awaited once
+(fonts, images, data). The page background stays transparent unless the page paints it.
+"""
+from __future__ import annotations
+
+import json
+import multiprocessing as mp
+import time
+from pathlib import Path
+
+from .ff import RnError
+
+READY_TIMEOUT_MS = 30_000
+FRAME_TIMEOUT_MS = 20_000
+
+
+def _init_script(fps: float, frames: int, width: int, height: int, shard: int) -> str:
+    from .fx import js_path
+    meta = json.dumps({'fps': fps, 'frames': frames, 'width': width, 'height': height, 'shard': shard})
+    return f'window.RN = {meta};\n' + js_path().read_text()
+
+
+def _shard(args: tuple) -> dict:
+    url, out_dir, indices, fps, frames, width, height, shard, scale = args
+    from playwright.sync_api import Error as PlaywrightError, sync_playwright
+
+    errors: list[str] = []
+    started = time.monotonic()
+    with sync_playwright() as playwright:
+        browser = playwright.chromium.launch(args=['--disable-gpu', '--font-render-hinting=none'])
+        try:
+            page = browser.new_page(viewport={'width': width, 'height': height}, device_scale_factor=scale)
+            page.on('pageerror', lambda error: errors.append(str(error)))
+            page.add_init_script(_init_script(fps, frames, width, height, shard))
+            page.goto(url, wait_until='load', timeout=READY_TIMEOUT_MS)
+            page.evaluate('async () => { if (window.rnReady) await window.rnReady; await document.fonts.ready; }')
+            if not page.evaluate('typeof window.renderFrame === "function"'):
+                raise RnError(f'{url}: the page does not define window.renderFrame(i)')
+            for index in indices:
+                page.evaluate('async (i) => { await window.renderFrame(i); }', index)
+                page.screenshot(path=str(Path(out_dir) / f'{index + 1:05d}.png'), omit_background=True,
+                                timeout=FRAME_TIMEOUT_MS, animations='disabled')
+                if errors:
+                    raise RnError(f'frame {index}: page error: {errors[0]}')
+        except PlaywrightError as error:
+            raise RnError(f'shard {shard}: {str(error).splitlines()[0]}') from None
+        finally:
+            browser.close()
+    return {'shard': shard, 'frames': len(indices), 'seconds': round(time.monotonic() - started, 2)}
+
+
+def capture_command(page: str, *, out: str, frames: int, width: int, height: int, fps: float, shards: int,
+                    start: int = 0, scale: float = 1.0) -> dict:
+    source = Path(page)
+    if not source.exists():
+        raise RnError(f'no such page: {page}')
+    if frames < 1 or width < 2 or height < 2:
+        raise RnError('--frames, --size must be positive')
+    try:
+        import playwright  # noqa: F401
+    except ImportError:
+        raise RnError("rn capture needs playwright (extra \"capture\"): uv tool install 'renoise-kit[all]' && playwright install chromium") from None
+    out_dir = Path(out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for stale in out_dir.glob('*.png'):
+        stale.unlink()
+    indices = list(range(start, start + frames))
+    shards = max(1, min(shards, len(indices)))
+    # Contiguous runs per shard: each Chromium boots once (~1-3 s), so short renders gain nothing from more shards.
+    size = -(-len(indices) // shards)
+    jobs = [(source.resolve().as_uri(), str(out_dir), indices[k * size:(k + 1) * size], fps, start + frames, width, height, k, scale)
+            for k in range(shards) if indices[k * size:(k + 1) * size]]
+    started = time.monotonic()
+    if len(jobs) == 1:
+        reports = [_shard(jobs[0])]
+    else:
+        with mp.get_context('spawn').Pool(len(jobs)) as pool:
+            reports = pool.map(_shard, jobs)
+    written = sorted(out_dir.glob('*.png'))
+    if len(written) != frames:
+        raise RnError(f'wrote {len(written)} frames, expected {frames}')
+    elapsed = time.monotonic() - started
+    return {'dir': str(out_dir), 'pattern': str(out_dir / '%05d.png'), 'first_number': start + 1, 'frames': frames,
+            'fps': fps, 'size': [round(width * scale), round(height * scale)], 'shards': reports,
+            'seconds': round(elapsed, 2), 'fps_rendered': round(frames / elapsed, 1) if elapsed else None,
+            'edl': {'frames': f'{out_dir.name}/%05d.png', 'fps': fps}}
+
+
+def summary_lines(result: dict) -> list[str]:
+    return [f'{result["pattern"]}  {result["frames"]} frames from #{result["first_number"]:05d}  '
+            f'{result["size"][0]}x{result["size"][1]}  {result["seconds"]}s ({result["fps_rendered"]} fps, {len(result["shards"])} shards)',
+            f'EDL: {json.dumps(result["edl"])}']