renoise-kit 0.5.0__py3-none-any.whl

rn/export.py

@@ -0,0 +1,200 @@
+"""rn export: an EDL as an editable project for other editors: OpenTimelineIO (.otio), Final Cut Pro X (.fcpxml) or
+Premiere / Resolve / FCP 7 (.xml), with media referenced by absolute path. Cuts, trims, speed, transitions, nesting, overlay
+and audio placement in time carry over; what NLE interchange cannot express (position and size, keys, blend, masks, raw
+filters, gain curves) is kept as "rn" metadata and listed in the result.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+from .edl import Clip, Edit, load
+from .ff import RnError, probe
+
+ADAPTERS = {'.otio': 'otio_json', '.fcpxml': 'fcpx_xml', '.xml': 'fcp_xml'}
+_SEQ = re.compile(r'%0?(\d*)d')
+
+
+def _rt(otio, frames: float, rate: float):
+    return otio.opentime.RationalTime(frames, rate)
+
+
+def _plain(value):
+    """OTIO metadata is a C++ any-dictionary: JSON types only (no tuples, None, Fractions or Paths)."""
+    if isinstance(value, dict):
+        return {str(k): _plain(v) for k, v in value.items() if v is not None}
+    if isinstance(value, (list, tuple)):
+        return [_plain(v) for v in value if v is not None]
+    if isinstance(value, (bool, int, float, str)):
+        return value
+    return str(value)
+
+
+def _lost(clip: Clip) -> dict:
+    """What an NLE file cannot carry for this clip, kept as metadata."""
+    keep = {k: getattr(clip, k) for k in ('keys', 'vf', 'af', 'blend') if getattr(clip, k)}
+    if clip.mask is not None:
+        keep['mask'] = {'source': str(clip.mask.source), 'mode': clip.mask_mode, 'invert': clip.mask_invert}
+    if (clip.x, clip.y, clip.w, clip.h, clip.opacity) != (0, 0, None, None, 1.0):
+        keep['place'] = {'x': clip.x, 'y': clip.y, 'w': clip.w, 'h': clip.h, 'opacity': clip.opacity}
+    if clip.fade_in or clip.fade_out:
+        keep['fades'] = [clip.fade_in, clip.fade_out]
+    return _plain(keep)
+
+
+STILL_HOURS = 1  # stills are endless in an NLE; FCP X still wants a range
+
+
+def _available(otio, frames: float, rate: float):
+    return otio.opentime.TimeRange(_rt(otio, 0, rate), _rt(otio, frames, rate))
+
+
+def _reference(otio, clip: Clip, rate: float):
+    """Media with its available range (Final Cut X refuses a reference without one). Not for solids (see _item)."""
+    if clip.kind == 'sequence':
+        pattern = clip.source
+        match = _SEQ.search(pattern.name)
+        count = sum(1 for f in pattern.parent.iterdir() if f.name.endswith(pattern.name[match.end():]))
+        return otio.schema.ImageSequenceReference(
+            target_url_base=str(pattern.parent.resolve()) + '/', name_prefix=pattern.name[:match.start()],
+            name_suffix=pattern.name[match.end():], start_frame=clip.seq_start, frame_step=1, rate=float(clip.src_fps),
+            frame_zero_padding=int(match.group(1) or 0), available_range=_available(otio, count, float(clip.src_fps)))
+    reference = otio.schema.ExternalReference(target_url=str(clip.source.resolve()))
+    if clip.kind == 'image':
+        reference.available_range = _available(otio, STILL_HOURS * 3600 * rate, rate)
+    else:
+        video = probe(clip.source)['video']
+        src_rate = float(clip.src_fps)
+        reference.available_range = _available(otio, video['frames'] or round((video['duration'] or 0) * src_rate), src_rate)
+    return reference
+
+
+def _item(otio, clip: Clip, edit: Edit, head: int, tail: int, lost: list):
+    """One clip on a track: `head`/`tail` timeline frames are given to the transitions on either side."""
+    rate = float(edit.fps)
+    frames = clip.frames - head - tail
+    meta = _lost(clip)
+    if clip.kind == 'color':  # no interchange format carries a solid (FCP X has no generator reference): a gap, colour kept
+        meta['color'] = clip.color
+    if meta:
+        lost.append({'clip': clip.id or clip.where, 'kept_as_metadata': sorted(meta)})
+    if clip.kind == 'edit':
+        stack = _stack(otio, load(clip.source), lost)
+        start = clip.start_s + head / rate * clip.speed
+        stack.source_range = otio.opentime.TimeRange(_rt(otio, start * rate, rate), _rt(otio, frames, rate))
+        stack.name = clip.id or clip.source.stem
+        stack.metadata['rn'] = _plain(meta)
+        return stack
+    if clip.kind == 'color':
+        return otio.schema.Gap(source_range=otio.opentime.TimeRange(duration=_rt(otio, frames, rate)), metadata={'rn': _plain(meta)})
+    src_rate = float(clip.src_fps) if clip.src_fps else rate
+    start = (clip.start_s + head / rate * clip.speed) if clip.kind in ('video', 'sequence') else head / rate
+    item = otio.schema.Clip(name=clip.id or (clip.source.name if clip.source else clip.color), media_reference=_reference(otio, clip, rate),
+                            source_range=otio.opentime.TimeRange(_rt(otio, round(start * src_rate), src_rate),
+                                                                 _rt(otio, frames * src_rate / rate, src_rate)))
+    if clip.speed != 1:
+        item.effects.append(otio.schema.LinearTimeWarp(time_scalar=clip.speed))
+    item.metadata['rn'] = _plain({**meta, 'meta': clip.meta})
+    return item
+
+
+def _lanes(items: list, start_of, length_of) -> list[list]:
+    """Greedy: overlapping items go to separate lanes (an NLE track holds one item at a time)."""
+    lanes: list[list] = []
+    for item in sorted(items, key=start_of):
+        lane = next((l for l in lanes if start_of(l[-1]) + length_of(l[-1]) <= start_of(item)), None)
+        if lane is None:
+            lanes.append([item])
+        else:
+            lane.append(item)
+    return lanes
+
+
+def _stack(otio, edit: Edit, lost: list):
+    rate = float(edit.fps)
+    stack = otio.schema.Stack(name=edit.path.stem)
+    main = otio.schema.Track(name='V1', kind=otio.schema.TrackKind.Video)
+    for i, clip in enumerate(edit.base):
+        incoming = clip.transition_frames
+        outgoing = edit.base[i + 1].transition_frames if i + 1 < len(edit.base) else 0
+        if incoming:
+            main.append(otio.schema.Transition(name=clip.transition, transition_type=otio.schema.TransitionTypes.SMPTE_Dissolve,
+                                               in_offset=_rt(otio, incoming // 2, rate), out_offset=_rt(otio, incoming - incoming // 2, rate),
+                                               metadata={'rn': {'xfade': clip.transition}}))
+        # A transition's overlap is split at the cut: half from the end of one clip, half from the start of the next.
+        main.append(_item(otio, clip, edit, incoming - incoming // 2, outgoing // 2, lost))
+    stack.append(main)
+    for n, lane in enumerate(_lanes(edit.overlays, lambda c: c.timeline_start, lambda c: c.frames), start=2):
+        track = otio.schema.Track(name=f'V{n}', kind=otio.schema.TrackKind.Video)
+        position = 0
+        for clip in lane:
+            if clip.timeline_start > position:
+                track.append(otio.schema.Gap(source_range=otio.opentime.TimeRange(duration=_rt(otio, clip.timeline_start - position, rate))))
+            track.append(_item(otio, clip, edit, 0, 0, lost))
+            position = clip.timeline_start + clip.frames
+        stack.append(track)
+    lengths = {}
+    for item in edit.audio:
+        available = probe(item.source)['audio']['duration'] or 0
+        lengths[id(item)] = min(item.duration or available - item.start_s, edit.duration - item.at)
+    for n, lane in enumerate(_lanes(edit.audio, lambda a: a.at, lambda a: lengths[id(a)]), start=1):
+        track = otio.schema.Track(name=f'A{n}', kind=otio.schema.TrackKind.Audio)
+        position = 0.0
+        for item in lane:
+            if item.at > position:
+                track.append(otio.schema.Gap(source_range=otio.opentime.TimeRange(duration=_rt(otio, round((item.at - position) * rate), rate))))
+            seconds = lengths[id(item)]
+            meta = {k: v for k, v in (('gain_db', item.gain_db), ('fade_in', item.fade_in), ('fade_out', item.fade_out),
+                                      ('af', item.af), ('keys', item.keys), ('role', item.role)) if v}
+            source = otio.schema.ExternalReference(target_url=str(item.source.resolve()),
+                                                   available_range=_available(otio, round((probe(item.source)['audio']['duration'] or 0) * rate), rate))
+            track.append(otio.schema.Clip(name=item.id or item.source.name, media_reference=source,
+                                          source_range=otio.opentime.TimeRange(_rt(otio, round(item.start_s * rate), rate), _rt(otio, round(seconds * rate), rate)),
+                                          metadata={'rn': _plain({**meta, 'meta': item.meta})}))
+            position = item.at + round(seconds * rate) / rate
+        stack.append(track)
+    return stack
+
+
+def export_command(edl_path: str, out: str, *, srt: str | None) -> dict:
+    import opentimelineio as otio
+
+    target = Path(out)
+    adapter = ADAPTERS.get(target.suffix.lower())
+    if not adapter:
+        raise RnError(f'{out}: export to {", ".join(ADAPTERS)}')
+    edit = load(edl_path)
+    lost: list = []
+    stack = _stack(otio, edit, lost)
+    timeline = otio.schema.Timeline(name=edit.path.stem, global_start_time=_rt(otio, 0, float(edit.fps)))
+    timeline.tracks = stack
+    timeline.metadata['rn'] = _plain({'width': edit.width, 'height': edit.height, 'fps': edit.fps})
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        otio.adapters.write_to_file(timeline, str(target), adapter_name=adapter)
+    except Exception as error:  # adapter plugins raise their own types
+        raise RnError(f'{adapter} could not write {out}: {error} (install the export extra for .fcpxml / .xml)') from None
+    result = {'path': str(target), 'adapter': adapter, 'frames': edit.total_frames, 'fps': str(edit.fps),
+              'tracks': [{'name': t.name, 'kind': t.kind, 'items': len(t)} for t in stack], 'lost': lost}
+    if srt:
+        if not edit.subtitles:
+            raise RnError('--srt: the edit has no "subtitles"')
+        if edit.subtitles.suffix.lower() == '.srt':
+            shutil.copyfile(edit.subtitles, srt)
+        else:
+            import pysubs2
+            pysubs2.load(str(edit.subtitles)).save(srt, format_='srt')
+        result['srt'] = srt
+    return result
+
+
+def summary_lines(result: dict) -> list[str]:
+    lines = [f'{result["path"]} ({result["adapter"]})  {result["frames"]} frames at {result["fps"]} fps',
+             '  ' + ', '.join(f'{t["name"]} {t["items"]} items' for t in result['tracks'])]
+    if result['lost']:
+        lines.append(f'  not expressible in NLE files, kept as "rn" metadata: '
+                     + '; '.join(f'{l["clip"]}: {", ".join(l["kept_as_metadata"])}' for l in result['lost'][:10]))
+    if 'srt' in result:
+        lines.append(f'  subtitles: {result["srt"]}')
+    return lines

rn/faces.py

@@ -0,0 +1,135 @@
+"""rn faces: per-frame face boxes and landmarks (YuNet), in source pixels."""
+from __future__ import annotations
+
+import os
+import tempfile
+from collections import Counter
+from fractions import Fraction
+from pathlib import Path
+
+from .ff import RnError
+from .frames import _compose, _save_under
+
+DEFAULT_MODEL = '/opt/media-sandbox/models/face_detection_yunet_2023mar.onnx'  # baked into the sandbox
+# Outside the sandbox: fetched once into ~/.cache/rn (OpenCV zoo, MIT).
+MODEL_URL = 'https://github.com/opencv/opencv_zoo/raw/main/models/face_detection_yunet/face_detection_yunet_2023mar.onnx'
+MODEL_SHA256 = '8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4'
+DETECT_LONG_SIDE = 960  # larger frames are detected at this size, then mapped back to source pixels
+SHEET_FRAMES = 12
+
+
+def _face(row, scale: float) -> dict:
+    """YuNet row: x y w h, right eye, left eye, nose, right mouth corner, left mouth corner (all as seen in the image), score."""
+    x, y, w, h, *marks, score = (float(v) for v in row[:15])
+    point = lambda i: [round(marks[2 * i] / scale, 1), round(marks[2 * i + 1] / scale, 1)]  # noqa: E731
+    return {'box': [round(v / scale, 1) for v in (x, y, w, h)], 'score': round(score, 3),
+            'eyes': [point(0), point(1)], 'nose': point(2), 'mouth': [point(3), point(4)]}
+
+
+def faces_command(path: str, *, every: int = 1, model: str | None = None, min_score: float = 0.6,
+                  out_sheet: str | None = None, max_kb: int = 125) -> dict:
+    """Measures where faces are in every `every`-th decoded frame. Measurement only: it never alters, blurs or crops a face.
+    Use the boxes to keep text/captions off faces, or to place separate graphics that follow a subject.
+    Coordinates are source pixels; `f` is the exact decoded frame index. `eyes` and `mouth` are ordered left-to-right as seen in the image."""
+    import cv2
+
+    model_path = model or os.environ.get('RN_YUNET_MODEL')
+    if not model_path:
+        from .assets import fetch_checked
+        model_path = DEFAULT_MODEL if Path(DEFAULT_MODEL).is_file() else str(
+            fetch_checked(MODEL_URL, MODEL_SHA256, Path.home() / '.cache' / 'rn' / Path(DEFAULT_MODEL).name, name='face model'))
+    if not Path(model_path).is_file():
+        raise RnError(f'face model not found: {model_path} (set RN_YUNET_MODEL or pass --model)')
+    if every < 1:
+        raise RnError('--every must be >= 1')
+    capture = cv2.VideoCapture(str(path))
+    if not capture.isOpened():
+        raise RnError(f'{path}: cannot open video')
+    fps = capture.get(cv2.CAP_PROP_FPS) or 0.0
+    detector = cv2.FaceDetectorYN.create(model_path, '', (320, 320), min_score)
+    width = height = 0
+    scale = 1.0
+    sampled: list[dict] = []
+    index = 0
+    while True:
+        ok, frame = capture.read()
+        if not ok:
+            break
+        if index == 0:
+            height, width = frame.shape[:2]
+            scale = min(1.0, DETECT_LONG_SIDE / max(width, height))
+        if index % every == 0:
+            small = frame if scale == 1.0 else cv2.resize(frame, None, fx=scale, fy=scale, interpolation=cv2.INTER_AREA)
+            detector.setInputSize((small.shape[1], small.shape[0]))
+            _, rows = detector.detect(small)
+            sampled.append({'f': index, 't': round(index / fps, 4) if fps else None,
+                            'faces': [_face(row, scale) for row in (rows if rows is not None else [])]})
+        index += 1
+    capture.release()
+    if index == 0:
+        raise RnError(f'{path}: no decodable video frames')
+
+    with_faces = [s for s in sampled if s['faces']]
+    boxes = [f['box'] for s in with_faces for f in s['faces']]
+    union = None
+    if boxes:
+        x0, y0 = min(b[0] for b in boxes), min(b[1] for b in boxes)
+        x1, y1 = max(b[0] + b[2] for b in boxes), max(b[1] + b[3] for b in boxes)
+        union = [round(x0, 1), round(y0, 1), round(x1 - x0, 1), round(y1 - y0, 1)]
+    result = {
+        'meta': {'path': str(path), 'width': width, 'height': height, 'fps': round(fps, 4), 'frames': index, 'every': every, 'model': model_path},
+        'frames': sampled,
+        'summary': {
+            'sampled': len(sampled), 'with_faces': len(with_faces),
+            'max_faces': max((len(s['faces']) for s in sampled), default=0),
+            'union_box': union,
+            'union_box_fraction': [round(union[0] / width, 4), round(union[1] / height, 4), round(union[2] / width, 4), round(union[3] / height, 4)] if union else None,
+            'face_count_histogram': {str(k): v for k, v in sorted(Counter(len(s['faces']) for s in sampled).items())},
+        },
+    }
+    if out_sheet:
+        result['sheet'] = _write_sheet(path, sampled, Fraction(fps).limit_denominator(1001) or Fraction(1), out_sheet, max_kb)
+    return result
+
+
+def _write_sheet(path: str, sampled: list[dict], fps: Fraction, out_sheet: str, max_kb: int) -> dict:
+    import cv2
+
+    count = min(SHEET_FRAMES, len(sampled))
+    picks = {sampled[round(k * (len(sampled) - 1) / max(1, count - 1))]['f']: sampled[round(k * (len(sampled) - 1) / max(1, count - 1))] for k in range(count)}
+    capture = cv2.VideoCapture(str(path))
+    tiles: list[tuple[int, Path]] = []
+    with tempfile.TemporaryDirectory() as tmp:
+        index = 0
+        while len(tiles) < len(picks):
+            ok, frame = capture.read()
+            if not ok:
+                break
+            if index in picks:
+                shrink = min(1.0, 480 / frame.shape[1])
+                frame = cv2.resize(frame, None, fx=shrink, fy=shrink, interpolation=cv2.INTER_AREA)
+                for face in picks[index]['faces']:
+                    x, y, w, h = (int(v * shrink) for v in face['box'])
+                    cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2)
+                tile = Path(tmp) / f'{index:08d}.png'
+                cv2.imwrite(str(tile), frame)
+                tiles.append((index, tile))
+            index += 1
+        capture.release()
+        target = Path(out_sheet)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        size = _save_under(_compose(tiles, fps, 4, f'{Path(path).name}  faces  {len(tiles)} frames'), target, max_kb)
+    return {'path': str(target), 'indices': [i for i, _ in tiles], 'bytes': size}
+
+
+def summary_lines(result: dict) -> list[str]:
+    meta, summary = result['meta'], result['summary']
+    lines = [f'{meta["path"]}: {meta["width"]}x{meta["height"]} {meta["fps"]}fps {meta["frames"]} frames, sampled every {meta["every"]} ({summary["sampled"]} sampled)',
+             f'faces in {summary["with_faces"]}/{summary["sampled"]} sampled frames, max {summary["max_faces"]} at once; histogram {summary["face_count_histogram"]}']
+    if summary['union_box']:
+        x, y, w, h = summary['union_box']
+        fx, fy, fw, fh = summary['union_box_fraction']
+        lines.append(f'union box [x={x} y={y} w={w} h={h}] px = [x={fx} y={fy} w={fw} h={fh}] of frame')
+    if result.get('sheet'):
+        lines.append(f'sheet: {result["sheet"]["path"]} ({result["sheet"]["bytes"] // 1024} KB)')
+    return lines

rn/ff.py

@@ -0,0 +1,183 @@
+"""ffmpeg / ffprobe plumbing shared by every command."""
+from __future__ import annotations
+
+import json
+import re
+import struct
+import subprocess
+from fractions import Fraction
+from functools import lru_cache
+from pathlib import Path
+
+
+class RnError(Exception):
+    """A failure the agent can act on; the CLI prints it as one line."""
+
+
+def run(args: list[str], *, quiet: bool = True, cwd: str | Path | None = None) -> subprocess.CompletedProcess:
+    """Runs ffmpeg (or ffprobe); raises RnError with the tail of stderr on failure."""
+    flags = ['-nostdin', *(['-v', 'error'] if quiet else [])] if args[0] == 'ffmpeg' else []
+    command = [args[0], '-hide_banner', *flags, *args[1:]]
+    result = subprocess.run(command, capture_output=True, text=True, cwd=cwd)
+    if result.returncode != 0:
+        lines = result.stderr.strip().splitlines()
+        # The cause is usually an earlier line than the generic 'Task finished with error' tail.
+        causes = [line for line in lines if any(k in line for k in ('rror', 'nvalid', 'not match', 'No such', 'Unable', 'failed'))]
+        tail = '\n'.join((causes[:3] + lines[-2:]) if causes else lines[-6:])
+        raise RnError(f'{args[0]} failed: {tail or "exit " + str(result.returncode)}')
+    return result
+
+
+@lru_cache(maxsize=None)
+def has_filter(name: str) -> bool:
+    """Whether this ffmpeg build has a filter (Homebrew's plain ffmpeg, for one, has no libass `subtitles`)."""
+    filters = subprocess.run(['ffmpeg', '-hide_banner', '-filters'], capture_output=True, text=True).stdout
+    return any(line.split()[1:2] == [name] for line in filters.splitlines())
+
+
+def ffprobe_json(path: str | Path, *extra: str) -> dict:
+    result = run(['ffprobe', '-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', *extra, str(path)])
+    return json.loads(result.stdout)
+
+
+def rational(value: str | None) -> Fraction | None:
+    if not value or value in ('0/0', 'N/A'):
+        return None
+    try:
+        return Fraction(value)
+    except (ValueError, ZeroDivisionError):
+        return None
+
+
+def fps_text(fps: Fraction) -> str:
+    return str(fps.numerator) if fps.denominator == 1 else f'{fps.numerator}/{fps.denominator}'
+
+
+def mp4_faststart(path: str | Path) -> bool | None:
+    """True when the moov atom precedes mdat (playable before fully downloaded); None for non-MP4."""
+    with open(path, 'rb') as file:
+        while True:
+            header = file.read(8)
+            if len(header) < 8:
+                return None
+            size, kind = struct.unpack('>I4s', header)
+            if size == 1:
+                size = struct.unpack('>Q', file.read(8))[0]
+                body = size - 16
+            elif size == 0:
+                return None
+            else:
+                body = size - 8
+            if kind == b'moov':
+                return True
+            if kind == b'mdat':
+                return False
+            file.seek(body, 1)
+
+
+def probe(path: str | Path, *, exact: bool = False) -> dict:
+    """Facts an edit depends on. Frame count comes from counting packets (or decoding with exact=True),
+    never from the container duration, which an audio track can stretch."""
+    path = Path(path)
+    if not path.exists():
+        raise RnError(f'no such file: {path}')
+    info = ffprobe_json(path, '-count_frames' if exact else '-count_packets', '-select_streams', 'v:0')
+    data = ffprobe_json(path)
+    video_stream = next((s for s in info.get('streams', []) if s.get('codec_type') == 'video'), None)
+    audio_stream = next((s for s in data.get('streams', []) if s.get('codec_type') == 'audio'), None)
+    fmt = data.get('format', {})
+    result: dict = {
+        'path': str(path),
+        'format': fmt.get('format_name'),
+        'duration': _float(fmt.get('duration')),
+        'faststart': mp4_faststart(path) if 'mp4' in (fmt.get('format_name') or '') or 'mov' in (fmt.get('format_name') or '') else None,
+        'video': None,
+        'audio': None,
+    }
+    if video_stream:
+        fps = rational(video_stream.get('avg_frame_rate')) or rational(video_stream.get('r_frame_rate'))
+        # Constant rate when the average rate equals the base rate; a VFR phone clip averages below it.
+        cfr = rational(video_stream.get('avg_frame_rate')) == rational(video_stream.get('r_frame_rate'))
+        frames = video_stream.get('nb_read_frames') if exact else video_stream.get('nb_read_packets')
+        frames = int(frames) if frames not in (None, 'N/A') else None
+        single_image = (video_stream.get('codec_name') in ('png', 'mjpeg', 'webp', 'bmp', 'tiff')) and (frames or 0) <= 1
+        sar = video_stream.get('sample_aspect_ratio')
+        # ffmpeg's native vp8/vp9 decoders drop the alpha side channel that WebM carries as alpha_mode=1.
+        vpx_alpha = str((video_stream.get('tags') or {}).get('alpha_mode') or (video_stream.get('tags') or {}).get('ALPHA_MODE') or '') == '1'
+        rotation = 0
+        for side in video_stream.get('side_data_list', []) or []:
+            if 'rotation' in side:
+                rotation = int(side['rotation'])
+        result['video'] = {
+            'codec': video_stream.get('codec_name'),
+            'profile': video_stream.get('profile'),
+            'width': video_stream.get('width'),
+            'height': video_stream.get('height'),
+            'sar': sar if sar and sar != '0:1' else '1:1',
+            'pix_fmt': video_stream.get('pix_fmt'),
+            'fps': fps_text(fps) if fps and not single_image else None,
+            'fps_float': round(float(fps), 6) if fps and not single_image else None,
+            'frames': frames,
+            'duration': None if single_image else (_float(video_stream.get('duration')) or (float(frames / fps) if frames and fps else None)),
+            'color_space': video_stream.get('color_space'),
+            'color_transfer': video_stream.get('color_transfer'),
+            'color_primaries': video_stream.get('color_primaries'),
+            'rotation': rotation,
+            'alpha': vpx_alpha or (video_stream.get('pix_fmt') or '').startswith(('yuva', 'rgba', 'argb', 'bgra', 'abgr', 'gbrap', 'ya')),
+            'alpha_decoder': ({'vp9': 'libvpx-vp9', 'vp8': 'libvpx'}.get(video_stream.get('codec_name')) if vpx_alpha else None),
+            'still': single_image,
+            'cfr': cfr and not single_image,
+        }
+    if audio_stream:
+        result['audio'] = {
+            'codec': audio_stream.get('codec_name'),
+            'sample_rate': int(audio_stream['sample_rate']) if audio_stream.get('sample_rate') else None,
+            'channels': audio_stream.get('channels'),
+            'duration': _float(audio_stream.get('duration')),
+        }
+    return result
+
+
+def _float(value) -> float | None:
+    try:
+        return round(float(value), 6)
+    except (TypeError, ValueError):
+        return None
+
+
+def source_fps(info: dict) -> Fraction:
+    video = info.get('video') or {}
+    if not video.get('fps'):
+        raise RnError(f'{info["path"]}: no video frame rate (is it an image? use "image" instead of "src")')
+    return Fraction(video['fps'])
+
+
+_MATRIX_BY_TAG = {'bt709': 'bt709', 'smpte170m': 'bt601', 'bt470bg': 'bt601', 'bt2020nc': 'bt2020', 'bt2020c': 'bt2020',
+                  'smpte240m': 'smpte240m', 'fcc': 'fcc'}
+
+
+def source_matrix(video: dict) -> str:
+    """The YUV matrix to decode a source with. Tagged sources use their tag; untagged ones follow player convention
+    (HD and up = BT.709, SD = BT.601; JPEG/JFIF is always BT.601). RGB sources ignore it. Both assemble and finish
+    use this, so one clip never looks different depending on the command."""
+    tagged = _MATRIX_BY_TAG.get(video.get('color_space') or '')
+    if tagged:
+        return tagged
+    if (video.get('pix_fmt') or '').startswith('yuvj'):
+        return 'bt601'
+    return 'bt709' if (video.get('height') or 0) >= 720 else 'bt601'
+
+
+def to_bt709(matrix: str) -> str:
+    """scale options converting from `matrix` (RGB inputs: any) to limited-range BT.709 YUV."""
+    return f'in_color_matrix={matrix}:out_color_matrix=bt709:out_range=tv'
+
+
+HEX_COLOR = re.compile(r'^#?[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$')
+
+
+def ff_color(value: str) -> str:
+    """'#112233' -> '0x112233' for lavfi; named colors pass through."""
+    if HEX_COLOR.match(value):
+        return '0x' + value.lstrip('#')
+    return value

rn/fonts.py

@@ -0,0 +1,87 @@
+"""rn fonts: what is actually installed, from fontconfig. A missing weight makes browsers and libass fall back
+silently (Katana's sandbox only had some families in ExtraBold), so check the weight and script here before using a face."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from .ff import RnError
+
+# fontconfig weight -> CSS weight (fontconfig.h FC_WEIGHT_*).
+_CSS = [(0, 100), (40, 200), (50, 300), (80, 400), (100, 500), (180, 600), (200, 700), (205, 800), (210, 900)]
+_SCRIPTS = {'latin': ('en',), 'zh-hans': ('zh-cn', 'zh-sg'), 'zh-hant': ('zh-tw', 'zh-hk'), 'ja': ('ja',), 'ko': ('ko',),
+            'th': ('th',), 'ar': ('ar',), 'he': ('he',), 'hi': ('hi',), 'ru': ('ru',)}
+
+
+def css_weight(fc_weight: float) -> int:
+    return min(_CSS, key=lambda pair: abs(pair[0] - fc_weight))[1]
+
+
+def _license(path: str) -> str | None:
+    try:
+        from fontTools.ttLib import TTFont
+    except ImportError:
+        return None
+    try:
+        font = TTFont(path, fontNumber=0, lazy=True)
+        names = font['name']
+        text = names.getDebugName(13) or names.getDebugName(14)
+    except Exception:  # unreadable or exotic font: no license info rather than a failure
+        return None
+    return ' '.join(text.split())[:120] if text else None
+
+
+def installed() -> dict[str, dict]:
+    if not shutil.which('fc-list'):
+        raise RnError('fc-list not found: install fontconfig (brew install fontconfig, apt install fontconfig)')
+    output = subprocess.run(['fc-list', '--format', '%{family[0]}\t%{style[0]}\t%{weight}\t%{variable}\t%{file}\t%{lang}\n'],
+                            capture_output=True, text=True, check=True).stdout
+    families: dict[str, dict] = {}
+    for line in output.splitlines():
+        parts = line.split('\t')
+        if len(parts) != 6 or not parts[0] or parts[0].startswith('.'):
+            continue
+        family, style, weight, variable, path, langs = parts
+        entry = families.setdefault(family, {'family': family, 'weights': set(), 'styles': set(), 'variable': False,
+                                             'scripts': set(), 'files': set()})
+        try:
+            entry['weights'].add(css_weight(float(weight)))
+        except ValueError:
+            pass
+        entry['styles'].add(style)
+        entry['variable'] |= variable == 'True'
+        entry['files'].add(path)
+        codes = set(langs.split('|'))
+        entry['scripts'] |= {name for name, keys in _SCRIPTS.items() if codes & set(keys)}
+        if 'emoji' in family.lower():
+            entry['scripts'].add('emoji')
+    return families
+
+
+def fonts_command(*, family: str | None, script: str | None, licenses: bool) -> dict:
+    if script and script not in (*_SCRIPTS, 'emoji'):
+        raise RnError(f'--script: one of {", ".join([*_SCRIPTS, "emoji"])}')
+    rows = []
+    for entry in sorted(installed().values(), key=lambda e: e['family'].lower()):
+        if family and family.lower() not in entry['family'].lower():
+            continue
+        if script and script not in entry['scripts']:
+            continue
+        files = sorted(entry['files'])
+        row = {'family': entry['family'], 'weights': sorted(entry['weights']), 'styles': sorted(entry['styles']),
+               'variable': entry['variable'], 'scripts': sorted(entry['scripts']), 'files': files}
+        if licenses:
+            row['license'] = _license(files[0])
+        rows.append(row)
+    if family and not rows:
+        raise RnError(f'no installed family matches "{family}"; run rn fonts to list them, or download one into your project')
+    return {'count': len(rows), 'fonts': rows}
+
+
+def summary_lines(result: dict) -> list[str]:
+    lines = []
+    for row in result['fonts']:
+        weights = ','.join(str(w) for w in row['weights']) + (' (variable)' if row['variable'] else '')
+        lines.append(f'{row["family"]}: {weights}  [{" ".join(row["scripts"]) or "-"}]' + (f'  {row["license"]}' if row.get('license') else ''))
+    lines.append(f'{result["count"]} families')
+    return lines