renoise-kit 0.5.0__py3-none-any.whl

rn/frames.py

@@ -0,0 +1,205 @@
+"""rn frame / rn sheet: exact frames by decoded index, and labelled contact sheets small enough to view."""
+from __future__ import annotations
+
+import io
+import math
+import shutil
+import tempfile
+from fractions import Fraction
+from pathlib import Path
+
+from .ff import RnError, probe, run, source_fps
+
+# sandbox_exec shows at most 4 images totalling 512 KB per call, so a page defaults to 125 KB.
+DEFAULT_MAX_KB = 125
+MAX_PER_PAGE = 24
+
+
+def _select_expr(indices: list[int]) -> str:
+    return '+'.join(f'eq(n\\,{index})' for index in indices)
+
+
+def extract(path: str | Path, indices: list[int], out_dir: Path, *, width: int | None = None) -> list[tuple[int, Path]]:
+    """Decodes from the start and keeps the frames whose decoded index is listed. Exact by construction:
+    no input seeking (which can land 1-2 frames off on x264) and no timestamp arithmetic.
+    ponytail: decode time grows with the source; fine for clips and references up to a few minutes."""
+    wanted = sorted(set(i for i in indices if i >= 0))
+    if not wanted:
+        raise RnError('no frames selected')
+    results: list[tuple[int, Path]] = []
+    for start in range(0, len(wanted), 200):  # keep the select expression a sane length
+        chunk = wanted[start:start + 200]
+        pattern = out_dir / f'f{start:06d}_%06d.png'
+        filters = f"select='{_select_expr(chunk)}'" + (f',scale={width}:-2:flags=bicubic' if width else '')
+        run(['ffmpeg', '-i', str(path), '-vf', filters, '-fps_mode', 'passthrough', '-frames:v', str(len(chunk)), '-y', str(pattern)])
+        produced = sorted(out_dir.glob(f'f{start:06d}_*.png'))
+        results.extend(zip(chunk, produced))
+    return results
+
+
+def frame_command(path: str, *, index: int | None, time: float | None, last: bool, out: str) -> dict:
+    info = probe(path)
+    video = info['video']
+    if not video:
+        raise RnError(f'{path}: no video stream')
+    if last:
+        info = probe(path, exact=True)
+        index = info['video']['frames'] - 1
+    elif time is not None:
+        index = math.floor(time * float(source_fps(info)) + 1e-6)
+    assert index is not None
+    with tempfile.TemporaryDirectory() as tmp:
+        got = extract(path, [index], Path(tmp))
+        if not got:
+            raise RnError(f'{path}: frame {index} does not exist (the clip has {video["frames"]} frames)')
+        Path(out).parent.mkdir(parents=True, exist_ok=True)
+        if Path(out).suffix.lower() in ('.jpg', '.jpeg'):
+            run(['ffmpeg', '-i', str(got[0][1]), '-q:v', '2', '-y', out])
+        else:
+            shutil.copyfile(got[0][1], out)
+    fps = source_fps(info)
+    return {'path': out, 'index': index, 'time': round(float(index / fps), 4)}
+
+
+def pick_indices(frames: int, fps: Fraction, *, every: int | None, rate: float | None, indices: list[int] | None,
+                 seconds: list[float] | None, count: int | None, around: list[float] | None = None, span: int = 3) -> list[int]:
+    if around:
+        # Dense frames on both sides of each time (a cut, a transition, a beat): span frames before and after.
+        centres = [math.floor(t * float(fps) + 1e-6) for t in around if t >= 0]
+        return sorted({i for c in centres for i in range(c - span, c + span + 1) if 0 <= i < frames})
+    if indices:
+        return [i for i in indices if 0 <= i < frames]
+    if seconds:
+        return sorted({min(frames - 1, math.floor(s * float(fps) + 1e-6)) for s in seconds if s >= 0})
+    if every:
+        return list(range(0, frames, every))
+    if rate:
+        step = float(fps) / rate
+        return sorted({min(frames - 1, round(k * step)) for k in range(math.ceil(frames / step))})
+    count = min(count or 16, frames)
+    if count <= 1:
+        return [0]
+    return sorted({round(k * (frames - 1) / (count - 1)) for k in range(count)})
+
+
+def _timecode(index: int, fps: Fraction) -> str:
+    seconds = float(index / fps)
+    return f'{int(seconds // 60):02d}:{seconds % 60:05.2f}'
+
+
+def _difference(current: Path, previous: Path | None):
+    """|frame - previous frame| as a heat image: motion, flicker and repeated (dead) frames stand out; x4 gain."""
+    from PIL import Image, ImageChops
+
+    image = Image.open(current).convert('RGB')
+    if previous is None:
+        return Image.new('RGB', image.size)
+    return ImageChops.difference(image, Image.open(previous).convert('RGB')).point(lambda v: min(255, v * 4))
+
+
+def _compose(tiles: list[tuple[int, Path]], fps: Fraction, columns: int, title: str, images=None, labels: list[str] | None = None):
+    from PIL import Image, ImageDraw, ImageFont
+
+    images = images or [Image.open(path).convert('RGB') for _, path in tiles]
+    labels = labels or [f'#{index}  {_timecode(index, fps)}' for index, _ in tiles]
+    tile_w, tile_h = images[0].size
+    label_h = max(14, tile_w // 14)
+    font = ImageFont.load_default(size=label_h - 3)
+    title_h = label_h + 4
+    rows = math.ceil(len(images) / columns)
+    sheet = Image.new('RGB', (columns * tile_w + (columns + 1) * 2, title_h + rows * (tile_h + label_h + 2) + 2), (24, 24, 24))
+    draw = ImageDraw.Draw(sheet)
+    draw.text((4, 2), title, fill=(255, 255, 255), font=font)
+    for position, (label, image) in enumerate(zip(labels, images)):
+        x = 2 + (position % columns) * (tile_w + 2)
+        y = title_h + (position // columns) * (tile_h + label_h + 2)
+        sheet.paste(image, (x, y + label_h))
+        draw.text((x + 2, y + 1), label, fill=(255, 220, 64), font=font)
+    return sheet
+
+
+def _save_under(sheet, path: Path, max_kb: int) -> int:
+    from PIL import Image
+
+    image = sheet
+    while True:
+        for quality in (82, 70, 58, 46, 36):
+            buffer = io.BytesIO()
+            image.save(buffer, 'JPEG', quality=quality, optimize=True)
+            if buffer.tell() <= max_kb * 1024:
+                path.write_bytes(buffer.getvalue())
+                return buffer.tell()
+        if image.width < 320:
+            path.write_bytes(buffer.getvalue())
+            return buffer.tell()
+        image = image.resize((int(image.width * 0.85), int(image.height * 0.85)), Image.LANCZOS)
+
+
+IMAGES = ('.png', '.jpg', '.jpeg', '.webp')  # what a folder sheet tiles
+
+
+def _folder_sheet(folder: Path, *, out: str | None, several: bool, width: int, columns: int, max_kb: int) -> list[dict]:
+    """A folder of stills (renders of chosen frames, generated keyframes) as labelled pages, in natural name order
+    (f792 before f1062)."""
+    import re
+    from PIL import Image, ImageOps
+    natural = lambda f: [int(part) if part.isdigit() else part for part in re.split(r'(\d+)', f.name)]  # noqa: E731
+    files = sorted((f for f in folder.iterdir() if f.suffix.lower() in IMAGES), key=natural)
+    if not files:
+        raise RnError(f'{folder}: no .png/.jpg/.webp images')
+    base = Path(out) if out else Path('sheets') / f'{folder.name}.jpg'
+    if several and out:
+        base = Path(out).with_name(f'{Path(out).stem}-{folder.name}{Path(out).suffix or ".jpg"}')
+    base.parent.mkdir(parents=True, exist_ok=True)
+    thumbs = []
+    for f in files:
+        with Image.open(f) as image:
+            image = image.convert('RGB')
+            thumbs.append(image.resize((width, max(1, round(image.height * width / image.width))), Image.LANCZOS))
+    tile_h = max(t.height for t in thumbs)
+    thumbs = [ImageOps.pad(t, (width, tile_h)) for t in thumbs]
+    pages = []
+    page_count = math.ceil(len(files) / MAX_PER_PAGE)
+    for page in range(page_count):
+        part = slice(page * MAX_PER_PAGE, (page + 1) * MAX_PER_PAGE)
+        target = base if page_count == 1 else base.with_name(f'{base.stem}-p{page + 1}{base.suffix or ".jpg"}')
+        names = [f.name for f in files[part]]
+        size = _save_under(_compose([], Fraction(1), columns, f'{folder.name}  {len(files)} images', thumbs[part], names), target, max_kb)
+        pages.append({'path': str(target), 'source': str(folder), 'files': names, 'indices': list(range(len(names))), 'bytes': size})
+    return pages
+
+
+def sheet_command(paths: list[str], *, out: str | None, every: int | None, rate: float | None, indices: list[int] | None,
+                  seconds: list[float] | None, count: int | None, width: int, columns: int, max_kb: int,
+                  around: list[float] | None = None, span: int = 3, diff: bool = False) -> dict:
+    pages = []
+    for path in paths:
+        if Path(path).is_dir():
+            pages += _folder_sheet(Path(path), out=out, several=len(paths) > 1, width=width, columns=columns, max_kb=max_kb)
+            continue
+        info = probe(path)
+        if not info['video'] or info['video']['still']:
+            raise RnError(f'{path}: not a video')
+        fps = source_fps(info)
+        frames = info['video']['frames']
+        chosen = pick_indices(frames, fps, every=every, rate=rate, indices=indices, seconds=seconds, count=count, around=around, span=span)
+        if not chosen:
+            raise RnError(f'{path}: no frames in range (the clip has {frames} frames)')
+        stem = Path(path).stem
+        base = Path(out) if out else Path('sheets') / f'{stem}.jpg'
+        if len(paths) > 1 and out:
+            base = Path(out).with_name(f'{Path(out).stem}-{stem}{Path(out).suffix or ".jpg"}')
+        base.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory() as tmp:
+            wanted = sorted({j for i in chosen for j in ((i - 1, i) if diff else (i,)) if j >= 0})
+            extracted = dict(extract(path, wanted, Path(tmp), width=width))
+            tiles = [(i, extracted[i]) for i in chosen if i in extracted]
+            page_count = math.ceil(len(tiles) / MAX_PER_PAGE)
+            for page in range(page_count):
+                part = tiles[page * MAX_PER_PAGE:(page + 1) * MAX_PER_PAGE]
+                target = base if page_count == 1 else base.with_name(f'{base.stem}-p{page + 1}{base.suffix or ".jpg"}')
+                title = f'{Path(path).name}  {fps}fps  {frames}f  frames {part[0][0]}-{part[-1][0]}' + ('  |difference to previous| x4' if diff else '')
+                images = [_difference(p, extracted.get(i - 1)) for i, p in part] if diff else None
+                size = _save_under(_compose(part, fps, columns, title, images), target, max_kb)
+                pages.append({'path': str(target), 'source': path, 'indices': [index for index, _ in part], 'bytes': size})
+    return {'pages': pages}

rn/fx/__init__.py

@@ -0,0 +1,223 @@
+"""Edit effects for numpy frames: readable source to call, copy, change or ignore (not a closed vocabulary).
+
+Defaults are engine defaults, not design defaults. Images are H x W x 3 or x 4 uint8 in RGB order
+(OpenCV gives BGR: convert with img[..., ::-1] first). Alpha is preserved. Every function returns a new array.
+Deterministic: randomness only from hash/seeded RNG keyed by frame index + seed, so a frame renders the same
+in any order, shard or rerun. `i` is the frame index, `t` seconds. fx.js (RNFX) is the browser twin.
+"""
+from __future__ import annotations
+
+import inspect
+import math
+from pathlib import Path
+
+from rn.ff import RnError
+
+try:
+    import numpy as np
+except ImportError:  # pragma: no cover
+    np = None
+
+
+def _np():
+    if np is None:
+        raise RnError('rn.fx needs numpy (pip install numpy)')
+    return np
+
+
+def hash(a: int, b: int = 0, c: int = 0) -> float:  # noqa: A001
+    """Integer mix -> [0,1); same inputs always give the same number."""
+    m = 0xFFFFFFFF
+    h = ((a ^ 0x9E3779B9) * 0x85EBCA6B ^ (b + 0x7F4A7C15) * 0xC2B2AAE3 ^ (c + 0x165667B1) * 0x27D4EB2F) & m
+    h = (h ^ (h >> 15)) * 0x2C1B3C6D & m
+    h = (h ^ (h >> 12)) * 0x297A2D39 & m
+    return ((h ^ (h >> 15)) & m) / 4294967296
+
+
+def rng(seed: int):
+    """Generator of floats in [0,1) (mulberry32)."""
+    m, s = 0xFFFFFFFF, seed & 0xFFFFFFFF
+    while True:
+        s = (s + 0x6D2B79F5) & m
+        t = ((s ^ (s >> 15)) * (1 | s)) & m
+        t = ((t + ((t ^ (t >> 7)) * (61 | t) & m)) ^ t) & m
+        yield ((t ^ (t >> 14)) & m) / 4294967296
+
+
+def _color(value) -> tuple[int, int, int]:
+    if isinstance(value, str):
+        v = value.lstrip('#')
+        if len(v) == 3:
+            v = ''.join(ch * 2 for ch in v)
+        return int(v[0:2], 16), int(v[2:4], 16), int(v[4:6], 16)
+    return tuple(value)[:3]
+
+
+def _blend(base, layer, op: str, alpha):
+    """base/layer float 0..255 (H,W,3); alpha scalar or (H,W,1) opacity of the layer."""
+    if op == 'soft-light':
+        b, s = base / 255, layer / 255
+        d = np.where(b <= 0.25, ((16 * b - 12) * b + 4) * b, np.sqrt(b))
+        mixed = 255 * np.where(s <= 0.5, b - (1 - 2 * s) * b * (1 - b), b + (2 * s - 1) * (d - b))
+    elif op == 'screen':
+        mixed = 255 - (255 - base) * (255 - layer) / 255
+    elif op == 'add':
+        mixed = base + layer
+    elif op == 'multiply':
+        mixed = base * layer / 255
+    elif op == 'normal':
+        mixed = layer
+    else:
+        raise RnError(f'unknown blend op {op!r} (soft-light, screen, add, multiply, normal)')
+    return base + (mixed - base) * alpha
+
+
+def _run(img, fn):
+    """Applies fn to the float RGB part; passes alpha through untouched."""
+    _np()
+    if img.ndim != 3 or img.shape[2] not in (3, 4) or img.dtype != np.uint8:
+        raise RnError('rn.fx expects an H x W x 3|4 uint8 array')
+    rgb = fn(img[..., :3].astype(np.float32))
+    out = img.copy()
+    out[..., :3] = np.clip(rgb + 0.5, 0, 255).astype(np.uint8)
+    return out
+
+
+def _fill(img, color, alpha):
+    return _run(img, lambda rgb: rgb + (np.array(_color(color), np.float32) - rgb) * alpha)
+
+
+def grain(img, i: int, *, amount=0.3, cell=2, mono=True, seed=7, op='soft-light'):
+    """Film grain. amount=opacity, cell=grain size px, mono=gray noise, op=blend mode."""
+    _np()
+    h, w = img.shape[:2]
+    gen = np.random.default_rng([seed, int(i)])
+    shape = (-(-h // cell), -(-w // cell), 1 if mono else 3)
+    noise = gen.random(shape, dtype=np.float32) * 255
+    noise = np.repeat(np.repeat(noise, cell, 0), cell, 1)[:h, :w]
+    return _run(img, lambda rgb: _blend(rgb, np.broadcast_to(noise, rgb.shape), op, amount))
+
+
+def vignette(img, *, amount=0.35, inner=0.45, outer=0.95, color='#000'):
+    """Darkens edges. inner/outer = start/full radius as a fraction of the half diagonal."""
+    _np()
+    h, w = img.shape[:2]
+    yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+    d = np.hypot(xx - w / 2, yy - h / 2) / (math.hypot(w, h) / 2)
+    mask = np.clip((d - inner) / (outer - inner), 0, 1)[..., None] * amount
+    return _fill(img, color, mask)
+
+
+def leak(img, i: int, *, color='#ff7a30', color2='#ffd27a', amount=0.55, x=0.85, y=0.2, r=0.6, drift=0.1, seed=3, op='screen', fps=30):
+    """Drifting light leak. x,y = centre (0..1), r = radius as a fraction of the long side, drift = wander as a fraction of size."""
+    _np()
+    h, w = img.shape[:2]
+    ph = hash(seed, 0, 0) * 6.283
+    cx = (x + math.sin(i / fps * 0.9 + ph) * drift) * w
+    cy = (y + math.cos(i / fps * 0.7 + ph) * drift) * h
+    yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+    d = (np.hypot(xx - cx, yy - cy) / (r * max(w, h)))[..., None]
+    fall = np.clip(1 - d, 0, 1) ** 2
+    c1, c2 = np.array(_color(color), np.float32), np.array(_color(color2), np.float32)
+    layer = c1 + (c2 - c1) * np.clip(1 - d / 0.35, 0, 1)
+    return _run(img, lambda rgb: _blend(rgb, layer, op, fall * amount))
+
+
+def flash(img, t: float, *, at=0.0, duration=0.1, color='#fff', amount=1.0):
+    """Full-frame colour fading out over `duration` s from `at`. color '#000' gives a dip."""
+    u = (t - at) / duration
+    return img.copy() if u < 0 or u >= 1 else _fill(img, color, amount * (1 - u))
+
+
+def letterbox(img, *, top=0.1, bottom=0.1, color='#000'):
+    """Bars as fractions of the height."""
+    _np()
+    out = img.copy()
+    h = img.shape[0]
+    out[: round(h * top), ..., :3] = _color(color)
+    out[h - round(h * bottom):, ..., :3] = _color(color)
+    return out
+
+
+def rgb_split(img, *, px=6):
+    """Red shifted right, blue left by px (edge pixels clamp)."""
+    _np()
+    px = int(round(px))
+    w = img.shape[1]
+    out = img.copy()
+    out[..., 0] = img[:, np.clip(np.arange(w) - px, 0, w - 1), 0]
+    out[..., 2] = img[:, np.clip(np.arange(w) + px, 0, w - 1), 2]
+    return out
+
+
+def glitch(img, i: int, *, amount=0.5, slices=8, seed=5):
+    """Horizontal slice displacement. amount = share of slices hit and how far they move."""
+    _np()
+    h, w = img.shape[:2]
+    bh = -(-h // slices)
+    out = img.copy()
+    for k in range(slices):
+        if hash(seed, i, k) >= amount:
+            continue
+        dx = int((hash(seed, i, k + 100) - 0.5) * amount * 0.3 * w)
+        out[k * bh:(k + 1) * bh] = np.roll(img[k * bh:(k + 1) * bh], dx, axis=1)
+    return out
+
+
+def strobe(img, i: int, *, every=2, color='#fff', amount=1.0):
+    """Colour overlay on every `every`-th frame."""
+    return img.copy() if i % every else _fill(img, color, amount)
+
+
+def punch(t: float, *, at=0.0, amount=0.07, decay=0.25) -> float:
+    """Scale for a punch-in at `at` s that is exactly 1 again after `decay` s. Feed it to apply_transform."""
+    e = max(0.0, 1 - (t - at) / decay)
+    return 1.0 if t < at else 1 + amount * e * e
+
+
+def shake(i: int, t: float, *, at=0.0, amp=(16, 12), decay=0.25, seed=9) -> tuple[float, float]:
+    """(dx, dy) px offset, amp=(x,y) px, exactly 0 after `decay` s. Feed it to apply_transform."""
+    e = 0.0 if t < at else max(0.0, 1 - (t - at) / decay)
+    return (hash(seed, i, 1) * 2 - 1) * amp[0] * e, (hash(seed, i, 2) * 2 - 1) * amp[1] * e
+
+
+def apply_transform(img, scale=1.0, dx=0.0, dy=0.0):
+    """Centre scale + translate; always covers the frame (scale >= 1, offset clamped so no edge shows)."""
+    _np()
+    from PIL import Image
+    h, w = img.shape[:2]
+    s = max(1.0, float(scale))
+    dx = max(-(s - 1) * w / 2, min((s - 1) * w / 2, dx))
+    dy = max(-(s - 1) * h / 2, min((s - 1) * h / 2, dy))
+    coeffs = (1 / s, 0, w / 2 - (w / 2 + dx) / s, 0, 1 / s, h / 2 - (h / 2 + dy) / s)
+    out = Image.fromarray(img).transform((w, h), Image.AFFINE, coeffs, Image.BILINEAR)
+    return np.asarray(out).copy()
+
+
+_JS_NAME = {'rgb_split': 'rgbSplit'}
+_WHAT = {
+    'grain': 'film grain from per-frame seeded noise',
+    'vignette': 'darkened edges',
+    'leak': 'drifting radial light leak',
+    'flash': 'fading full-frame flash (or dip with a dark colour)',
+    'letterbox': 'top/bottom bars',
+    'rgb_split': 'red/blue channel offset',
+    'glitch': 'horizontal slice displacement',
+    'strobe': 'colour overlay on every Nth frame',
+    'punch': 'punch-in scale that settles back to 1 (number)',
+    'shake': 'decaying camera shake offset (dx, dy)',
+}
+
+
+def catalog() -> list[dict]:
+    """One entry per effect: {name, js, py, params (defaults), what}."""
+    entries = []
+    for name, what in _WHAT.items():
+        params = {k: p.default for k, p in inspect.signature(globals()[name]).parameters.items() if p.default is not inspect.Parameter.empty}
+        entries.append({'name': name, 'js': f'RNFX.{_JS_NAME.get(name, name)}', 'py': f'rn.fx.{name}', 'params': params, 'what': what})
+    return entries
+
+
+def js_path() -> Path:
+    """Path of fx.js (copy or read it to adapt)."""
+    return Path(__file__).with_name('fx.js')

rn/fx/fx.js

@@ -0,0 +1,150 @@
+/* RNFX: edit effects for renderFrame pages (Canvas2D). Readable source: call it, copy it, change it, ignore it.
+ * Defaults are engine defaults, not design defaults; pick values for the piece in front of you.
+ * Deterministic: randomness comes only from hash(seed, frame index, ...), so any frame renders the same
+ * in any order, shard or rerun. Never use Math.random() in a frame.
+ * Time: functions taking `i` use the frame index; those taking `t` use seconds (t = i / fps).
+ * fps / size come from opts, else window.RN = {fps, frames, width, height}, else the canvas itself. */
+(function () {
+  const RN = () => window.RN || {};
+  const size = (ctx, o) => [o.width || RN().width || ctx.canvas.width, o.height || RN().height || ctx.canvas.height];
+
+  // hash(a,b,c) -> [0,1): integer mix, same inputs always give the same number.
+  function hash(a, b, c) {
+    let h = Math.imul((a | 0) ^ 0x9e3779b9, 0x85ebca6b) ^ Math.imul((b | 0) + 0x7f4a7c15, 0xc2b2ae35) ^ Math.imul((c | 0) + 0x165667b1, 0x27d4eb2f);
+    h = Math.imul(h ^ (h >>> 15), 0x2c1b3c6d); h = Math.imul(h ^ (h >>> 12), 0x297a2d39); h ^= h >>> 15;
+    return (h >>> 0) / 4294967296;
+  }
+  // rng(seed) -> () => [0,1): mulberry32 stream.
+  function rng(seed) {
+    let s = seed | 0;
+    return () => { s = (s + 0x6d2b79f5) | 0; let t = Math.imul(s ^ (s >>> 15), 1 | s); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+  }
+  const EASE = {
+    linear: (t) => t, in2: (t) => t * t, out2: (t) => 1 - (1 - t) * (1 - t), out3: (t) => 1 - Math.pow(1 - t, 3),
+    inout2: (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2),
+    outBack: (t) => 1 + 2.70158 * Math.pow(t - 1, 3) + 1.70158 * Math.pow(t - 1, 2),
+  };
+  // ease(name, t): t clamped to [0,1].
+  const ease = (name, t) => EASE[name](Math.min(1, Math.max(0, t)));
+  // envelope(t, at, attack, hold, release): 0 before `at`, ramps to 1 over attack, holds, ramps to 0 over release.
+  function envelope(t, at, attack = 0.05, hold = 0, release = 0.2) {
+    const u = t - at;
+    if (u < 0) return 0;
+    if (u < attack) return u / attack;
+    if (u < attack + hold) return 1;
+    const r = u - attack - hold;
+    return r < release ? 1 - r / release : 0;
+  }
+
+  const tiles = {};
+  // grain: film grain. amount=opacity, cell=grain size px, mono=gray noise, op=composite mode.
+  function grain(ctx, i, o = {}) {
+    const { amount = 0.3, cell = 2, mono = true, seed = 7, op = 'soft-light' } = o;
+    const [w, h] = size(ctx, o), T = 256, n = Math.ceil(T / cell), key = seed + ':' + cell + ':' + mono;
+    if (!tiles[key]) {
+      tiles[key] = [0, 1, 2, 3].map((k) => {  // 4 cached tiles; frames pick one and offset it
+        const small = document.createElement('canvas'); small.width = small.height = n;
+        const sc = small.getContext('2d'), img = sc.createImageData(n, n), r = rng(seed * 131 + k);
+        for (let p = 0; p < n * n; p++) {
+          const v = r() * 255;
+          img.data[p * 4] = v; img.data[p * 4 + 1] = mono ? v : r() * 255; img.data[p * 4 + 2] = mono ? v : r() * 255; img.data[p * 4 + 3] = 255;
+        }
+        sc.putImageData(img, 0, 0);
+        const tile = document.createElement('canvas'); tile.width = tile.height = T;
+        const tc = tile.getContext('2d'); tc.imageSmoothingEnabled = false; tc.drawImage(small, 0, 0, T, T);
+        return tile;
+      });
+    }
+    const tile = tiles[key][Math.floor(hash(seed, i, 1) * 4)];
+    // Grain only textures what is already drawn: on a transparent overlay, soft-light over empty pixels would paint
+    // the noise itself and grey out the whole layer. Keep the frame's own alpha by masking with a copy of it.
+    const before = document.createElement('canvas'); before.width = ctx.canvas.width; before.height = ctx.canvas.height;
+    before.getContext('2d').drawImage(ctx.canvas, 0, 0);
+    ctx.save();
+    ctx.globalCompositeOperation = op; ctx.globalAlpha = amount;
+    ctx.translate(Math.floor(hash(seed, i, 2) * T), Math.floor(hash(seed, i, 3) * T));
+    ctx.fillStyle = ctx.createPattern(tile, 'repeat');
+    ctx.fillRect(-T, -T, w + T, h + T);
+    ctx.setTransform(1, 0, 0, 1, 0, 0); ctx.globalAlpha = 1; ctx.globalCompositeOperation = 'destination-in';
+    ctx.drawImage(before, 0, 0);
+    ctx.restore();
+  }
+
+  // vignette: darkens edges. inner/outer = start/full radius as fraction of the half diagonal.
+  function vignette(ctx, o = {}) {
+    const { amount = 0.35, inner = 0.45, outer = 0.95, color = '#000' } = o;
+    const [w, h] = size(ctx, o), R = Math.hypot(w, h) / 2;
+    const g = ctx.createRadialGradient(w / 2, h / 2, inner * R, w / 2, h / 2, outer * R);
+    g.addColorStop(0, 'rgba(0,0,0,0)'); g.addColorStop(1, color);
+    ctx.save(); ctx.globalAlpha = amount; ctx.fillStyle = g; ctx.fillRect(0, 0, w, h); ctx.restore();
+  }
+
+  // leak: drifting light leak. x,y = centre (0..1), r = radius as fraction of the long side, drift = wander as fraction of width.
+  function leak(ctx, i, o = {}) {
+    const { color = '#ff7a30', color2 = '#ffd27a', amount = 0.55, x = 0.85, y = 0.2, r = 0.6, drift = 0.1, seed = 3, op = 'screen' } = o;
+    const [w, h] = size(ctx, o), fps = o.fps || RN().fps || 30, ph = hash(seed, 0, 0) * 6.283;
+    const cx = (x + Math.sin(i / fps * 0.9 + ph) * drift) * w, cy = (y + Math.cos(i / fps * 0.7 + ph) * drift) * h, R = r * Math.max(w, h);
+    const g = ctx.createRadialGradient(cx, cy, 0, cx, cy, R);
+    g.addColorStop(0, color2); g.addColorStop(0.35, color); g.addColorStop(1, 'rgba(0,0,0,0)');
+    ctx.save(); ctx.globalCompositeOperation = op; ctx.globalAlpha = amount; ctx.fillStyle = g; ctx.fillRect(0, 0, w, h); ctx.restore();
+  }
+
+  // flash: full-frame colour that fades out over `duration` s from `at`. Use color '#000' for a dip.
+  function flash(ctx, t, o = {}) {
+    const { at = 0, duration = 0.1, color = '#fff', amount = 1 } = o, u = (t - at) / duration;
+    if (u < 0 || u >= 1) return;
+    const [w, h] = size(ctx, o);
+    ctx.save(); ctx.globalAlpha = amount * (1 - u); ctx.fillStyle = color; ctx.fillRect(0, 0, w, h); ctx.restore();
+  }
+
+  // letterbox: bars as fractions of the height.
+  function letterbox(ctx, o = {}) {
+    const { top = 0.1, bottom = 0.1, color = '#000' } = o, [w, h] = size(ctx, o);
+    ctx.save(); ctx.fillStyle = color; ctx.fillRect(0, 0, w, h * top); ctx.fillRect(0, h * (1 - bottom), w, h * bottom); ctx.restore();
+  }
+
+  // rgbSplit: red shifted left, blue right by px (reads the canvas back, so call it on the finished frame).
+  function rgbSplit(ctx, o = {}) {
+    const px = o.px === undefined ? 6 : o.px, [w, h] = size(ctx, o);
+    const src = ctx.getImageData(0, 0, w, h), out = ctx.createImageData(w, h), s = src.data, d = out.data;
+    for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+      const p = (y * w + x) * 4, rx = Math.min(w - 1, Math.max(0, Math.round(x + px))), bx = Math.min(w - 1, Math.max(0, Math.round(x - px)));
+      d[p] = s[(y * w + rx) * 4]; d[p + 1] = s[p + 1]; d[p + 2] = s[(y * w + bx) * 4 + 2]; d[p + 3] = s[p + 3];
+    }
+    ctx.putImageData(out, 0, 0);
+  }
+
+  // glitch: horizontal slice displacement. amount = share of slices hit and how far they move.
+  function glitch(ctx, i, o = {}) {
+    const { amount = 0.5, slices = 8, seed = 5 } = o, [w, h] = size(ctx, o);
+    const snap = document.createElement('canvas'); snap.width = w; snap.height = h; snap.getContext('2d').drawImage(ctx.canvas, 0, 0);
+    const bh = Math.ceil(h / slices);
+    for (let k = 0; k < slices; k++) {
+      if (hash(seed, i, k) >= amount) continue;
+      const dx = (hash(seed, i, k + 100) - 0.5) * amount * 0.3 * w;
+      ctx.clearRect(0, k * bh, w, bh); ctx.drawImage(snap, 0, k * bh, w, bh, dx, k * bh, w, bh);
+    }
+  }
+
+  // strobe: colour overlay on every `every`-th frame.
+  function strobe(ctx, i, o = {}) {
+    const { every = 2, color = '#fff', amount = 1 } = o;
+    if (i % every) return;
+    const [w, h] = size(ctx, o);
+    ctx.save(); ctx.globalAlpha = amount; ctx.fillStyle = color; ctx.fillRect(0, 0, w, h); ctx.restore();
+  }
+
+  // punch: scale for a punch-in at `at` s that settles to 1 after `decay` s. Apply with ctx.scale around the centre.
+  function punch(t, o = {}) {
+    const { at = 0, amount = 0.07, decay = 0.25 } = o, e = Math.max(0, 1 - (t - at) / decay);
+    return t < at ? 1 : 1 + amount * e * e;
+  }
+
+  // shake: {dx, dy} px offset, amp=[x,y] px, decaying to 0 after `decay` s. Apply with ctx.translate.
+  function shake(i, t, o = {}) {
+    const { at = 0, amp = [16, 12], decay = 0.25, seed = 9 } = o, e = t < at ? 0 : Math.max(0, 1 - (t - at) / decay);
+    return { dx: (hash(seed, i, 1) * 2 - 1) * amp[0] * e, dy: (hash(seed, i, 2) * 2 - 1) * amp[1] * e };
+  }
+
+  window.RNFX = { hash, rng, ease, envelope, grain, vignette, leak, flash, letterbox, rgbSplit, glitch, strobe, punch, shake };
+})();