rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/score/synth.ts

@@ -0,0 +1,361 @@
+// the score rendered offline, in Bun: every note an oscillator (or noise) through its envelope, filter and pan into the
+// music bus, a send into the room (a convolution reverb), then the master chain (gain, compressor, limiter, soft
+// ceiling). The same graph and settings as the browser synth the language comes from, computed sample by sample, so a
+// score sounds alike in either. No browser, no audio device
+import { applyEnvelope, biquad, compress, convolveInto, envPoints, softClip } from './dsp.ts'
+import { type InstrumentDef, midiToHz } from './pattern.ts'
+import type { CompiledScore, ScheduledNote } from './score.ts'
+
+export const RATE = 48000
+/** the master's gain into the compressor */
+export const MASTER_GAIN = 0.45
+/** what a render keeps past its end: the last notes' release and the room */
+export const TAIL_S = 1.5
+/** the fade that closes a render at its end */
+const CLOSE_FADE_S = 1.2
+/** a dead stop: the score and its room cut over this long */
+const STOP_FADE_S = 0.01
+
+export interface Rendered {
+    rate: number
+    left: Float32Array
+    right: Float32Array
+}
+
+const TABLE = 2048
+const HARMONICS = 64
+/** one softened wave serves every note within a minor third */
+const BAND_SEMIS = 3
+const bandOf = (hz: number): number => Math.round((12 * Math.log2(Math.max(20, hz) / 440)) / BAND_SEMIS)
+const bandHz = (band: number): number => 440 * 2 ** ((band * BAND_SEMIS) / 12)
+/** the frequency above which a pulse, a saw or a wave loses its harmonics, unless the instrument sets its own */
+const TONE_HZ = 3000
+/** the pitch metal noise loops at, and the one drums and noise notes are relative to */
+const NOISE_REF_HZ = midiToHz(60)
+
+type Coefficients = { real: Float64Array; imag: Float64Array }
+
+function pulseCoefficients(duty: number): Coefficients {
+    const d = Math.max(0.05, Math.min(0.95, duty))
+    const real = new Float64Array(HARMONICS + 1)
+    const imag = new Float64Array(HARMONICS + 1)
+    for (let k = 1; k <= HARMONICS; k++) {
+        const c = (2 / (k * Math.PI)) * Math.sin(Math.PI * k * d)
+        real[k] = c * Math.cos(Math.PI * k * d)
+        imag[k] = c * Math.sin(Math.PI * k * d)
+    }
+    return { real, imag }
+}
+
+function waveCoefficients(samples: readonly number[]): Coefficients {
+    const n = samples.length
+    const h = Math.max(1, Math.min(32, Math.floor(n / 2)))
+    const real = new Float64Array(h + 1)
+    const imag = new Float64Array(h + 1)
+    for (let k = 1; k <= h; k++) {
+        let re = 0
+        let im = 0
+        for (let i = 0; i < n; i++) {
+            const ph = (2 * Math.PI * k * i) / n
+            re += (samples[i] ?? 0) * Math.cos(ph)
+            im += (samples[i] ?? 0) * Math.sin(ph)
+        }
+        real[k] = (2 * re) / n
+        imag[k] = (2 * im) / n
+    }
+    return { real, imag }
+}
+
+function sawCoefficients(): Coefficients {
+    const real = new Float64Array(HARMONICS + 1)
+    const imag = new Float64Array(HARMONICS + 1)
+    for (let k = 1; k <= HARMONICS; k++) imag[k] = (2 / (k * Math.PI)) * (k % 2 === 1 ? 1 : -1)
+    return { real, imag }
+}
+
+function triangleCoefficients(): Coefficients {
+    const real = new Float64Array(HARMONICS + 1)
+    const imag = new Float64Array(HARMONICS + 1)
+    for (let k = 1; k <= HARMONICS; k += 2) imag[k] = (8 / (Math.PI * Math.PI * k * k)) * (k % 4 === 1 ? 1 : -1)
+    return { real, imag }
+}
+
+/** one cycle, its harmonics past `top` Hz dropped (no alias), softened past `tone`, its peak brought to 1 as a browser
+ *  periodic wave is */
+function tableOf(c: Coefficients, hz: number, tone: number | null, rate: number): Float32Array {
+    const top = hz * 2 ** (2 / 12)
+    const out = new Float32Array(TABLE + 1)
+    for (let k = 1; k < c.real.length; k++) {
+        if (k * top >= rate / 2) break
+        const g = tone === null ? 1 : 1 / (1 + ((k * hz) / tone) ** 2)
+        const a = c.real[k]! * g
+        const b = c.imag[k]! * g
+        if (a === 0 && b === 0) continue
+        for (let i = 0; i < TABLE; i++) {
+            const ph = (2 * Math.PI * k * i) / TABLE
+            out[i] = out[i]! + a * Math.cos(ph) + b * Math.sin(ph)
+        }
+    }
+    let peak = 0
+    for (let i = 0; i < TABLE; i++) peak = Math.max(peak, Math.abs(out[i]!))
+    if (peak > 0) for (let i = 0; i < TABLE; i++) out[i] = out[i]! / peak
+    out[TABLE] = out[0]!
+    return out
+}
+
+/** white: one second of hiss; metal: a short 7 bit lfsr cycle that rings with a pitch, as the old sound chips' noise */
+function noiseBuffer(rate: number, metal: boolean): Float32Array {
+    if (!metal) {
+        const d = new Float32Array(rate)
+        let s = 0x1234
+        for (let i = 0; i < d.length; i++) {
+            s = (s * 1103515245 + 12345) & 0x7fffffff
+            d[i] = s / 0x3fffffff - 1
+        }
+        return d
+    }
+    const period = 127
+    const perStep = rate / (NOISE_REF_HZ * period)
+    const len = Math.max(1, Math.round(period * perStep))
+    const d = new Float32Array(len)
+    let reg = 0x7f
+    const bits: number[] = []
+    for (let i = 0; i < period; i++) {
+        const bit = (reg ^ (reg >> 1)) & 1
+        reg = (reg >> 1) | (bit << 6)
+        bits.push(reg & 1 ? 1 : -1)
+    }
+    for (let i = 0; i < len; i++) d[i] = bits[Math.floor(i / perStep) % period] ?? 0
+    return d
+}
+
+/** the room: a stereo burst of noise decaying over `seconds` */
+function impulse(seconds: number, rate: number): [Float32Array, Float32Array] {
+    const key = Math.round(seconds * 10) / 10
+    const len = Math.max(1, Math.floor(rate * Math.max(0.1, key)))
+    const out: [Float32Array, Float32Array] = [new Float32Array(len), new Float32Array(len)]
+    out.forEach((d, ch) => {
+        let s = 777 + ch * 31
+        for (let i = 0; i < len; i++) {
+            s = (s * 1103515245 + 12345) & 0x7fffffff
+            const decay = (1 - i / len) ** 2.5
+            const early = i < rate * 0.012 ? 0.4 : 1
+            d[i] = (s / 0x3fffffff - 1) * decay * early
+        }
+    })
+    return out
+}
+
+/** a browser convolver's own normalization of its impulse, so the room's level matches it */
+function impulseScale(ir: readonly Float32Array[], rate: number): number {
+    let power = 0
+    for (const d of ir) for (let i = 0; i < d.length; i++) power += d[i]! * d[i]!
+    power = Math.sqrt(power / (ir.length * (ir[0]?.length ?? 1)))
+    if (!Number.isFinite(power) || power < 0.000125) power = 0.000125
+    return (1 / power) * 0.00125 * (44100 / rate)
+}
+
+/** the waves a render reads, made once each */
+class Waves {
+    private tables = new Map<string, Float32Array>()
+    private waveIds = new Map<readonly number[], number>()
+    readonly white: Float32Array
+    readonly metal: Float32Array
+    constructor(readonly rate: number) {
+        this.white = noiseBuffer(rate, false)
+        this.metal = noiseBuffer(rate, true)
+    }
+    table(inst: InstrumentDef, hz: number): Float32Array {
+        const band = bandOf(hz)
+        const osc = inst.osc === 'wave' && !(inst.wave && inst.wave.length > 1) ? 'triangle' : inst.osc
+        const soft = osc === 'pulse' || osc === 'saw' || osc === 'wave'
+        const tone = soft ? (inst.tone ?? TONE_HZ) : null
+        let id = ''
+        if (osc === 'pulse') id = `p${Math.round((inst.duty ?? 0.5) * 100) / 100}`
+        else if (osc === 'wave') {
+            let w = this.waveIds.get(inst.wave!)
+            if (w === undefined) this.waveIds.set(inst.wave!, (w = this.waveIds.size))
+            id = `w${w}`
+        } else id = osc
+        const key = `${id}:${band}:${tone}`
+        let t = this.tables.get(key)
+        if (!t) {
+            const c =
+                osc === 'pulse' ? pulseCoefficients(Math.round((inst.duty ?? 0.5) * 100) / 100)
+                : osc === 'saw' ? sawCoefficients()
+                : osc === 'wave' ? waveCoefficients(inst.wave!)
+                : osc === 'triangle' ? triangleCoefficients()
+                : { real: new Float64Array(2), imag: Float64Array.of(0, 1) }
+            t = tableOf(c, bandHz(band), tone, this.rate)
+            this.tables.set(key, t)
+        }
+        return t
+    }
+}
+
+/** how a note's pitch moves from its start: held, swept (kicks, toms) or glided from the note before */
+interface Pitch {
+    from: number
+    to: number
+    /** seconds to go from `from` to `to`, exponentially; 0: held at `to` */
+    over: number
+}
+
+const pitchAt = (p: Pitch, t: number): number => (p.over <= 0 || t >= p.over ? p.to : p.from * (p.to / p.from) ** (Math.max(0, t) / p.over))
+
+/** one oscillator voice added into `buf`: a table read at a moving pitch, its detune and vibrato in cents */
+function oscillatorRun(buf: Float32Array, n: number, t0: number, rate: number, table: Float32Array, p: Pitch, cents: number, vib: InstrumentDef['vibrato'] | null, gain: number): void {
+    const LN = Math.LN2 / 1200
+    const steady = p.over <= 0 && !vib
+    const fixed = (p.to * Math.exp(cents * LN)) / rate
+    let phase = Math.max(0, t0) * (p.over <= 0 ? p.to : p.from) * Math.exp(cents * LN)
+    phase -= Math.floor(phase)
+    for (let i = 0; i < n; i++) {
+        const x = phase * TABLE
+        const j = x | 0
+        const v = table[j]!
+        buf[i] = buf[i]! + gain * (v + (table[j + 1]! - v) * (x - j))
+        let inc = fixed
+        if (!steady) {
+            const t = t0 + i / rate
+            let c = cents
+            if (vib) {
+                const on = Math.max(0, vib.delay)
+                const depth = t <= on ? 0 : vib.depth * 100 * Math.min(1, (t - on) / 0.12)
+                c += depth * Math.sin(2 * Math.PI * vib.rate * t)
+            }
+            inc = (pitchAt(p, t) * Math.exp(c * LN)) / rate
+        }
+        phase += inc
+        if (phase >= 1) phase -= Math.floor(phase)
+    }
+}
+
+/** a noise buffer looped at a moving playback rate, added into `buf` */
+function noiseRun(buf: Float32Array, n: number, t0: number, rate: number, src: Float32Array, p: Pitch): void {
+    let pos = 0
+    const len = src.length
+    for (let i = 0; i < n; i++) {
+        const j = pos | 0
+        const v = src[j % len]!
+        buf[i] = buf[i]! + v + (src[(j + 1) % len]! - v) * (pos - j)
+        pos += pitchAt(p, t0 + i / rate)
+        if (pos >= len) pos -= len
+    }
+}
+
+/** the music bus a render writes: the dry mix and the room's send, both stereo */
+interface Bus {
+    l: Float32Array
+    r: Float32Array
+    sendL: Float32Array | null
+    sendR: Float32Array | null
+}
+
+const scratch = { buf: new Float32Array(0) }
+
+/** one note into the bus: its source (oscillators or noise), its envelope, filter and pan, its send to the room */
+function playNote(bus: Bus, waves: Waves, inst: InstrumentDef, note: ScheduledNote): void {
+    const rate = waves.rate
+    const midi = note.midi ?? inst.pitch ?? 60
+    const hz = midiToHz(midi)
+    const peak = inst.vol * note.vol
+    if (peak <= 0) return
+    const pts = envPoints(inst.env, note.dur, peak)
+    const length = (pts[pts.length - 1]?.[0] ?? note.dur) + 0.02
+    const i0 = Math.max(0, Math.ceil(note.time * rate))
+    const i1 = Math.min(bus.l.length, Math.ceil((note.time + length) * rate))
+    const n = i1 - i0
+    if (n <= 0) return
+    if (scratch.buf.length < n) scratch.buf = new Float32Array(n)
+    const buf = scratch.buf
+    buf.fill(0, 0, n)
+    const t0 = i0 / rate - note.time
+    if (inst.osc === 'noise') {
+        const r0 = Math.max(0.05, Math.min(8, hz / NOISE_REF_HZ))
+        const pitch: Pitch = inst.sweep ? { from: r0, to: Math.max(0.02, r0 * 2 ** (inst.sweep.semis / 12)), over: Math.max(1e-4, inst.sweep.time) } : { from: r0, to: r0, over: 0 }
+        noiseRun(buf, n, t0, rate, inst.noise === 'metal' ? waves.metal : waves.white, pitch)
+    } else {
+        const voices = Math.max(1, Math.min(4, inst.unison ?? (inst.detune ? 2 : 1)))
+        const spread = inst.detune ?? 0
+        const pitch: Pitch = inst.sweep
+            ? { from: hz, to: Math.max(10, hz * 2 ** (inst.sweep.semis / 12)), over: Math.max(0.005, inst.sweep.time) }
+            : inst.glide && note.from !== null && note.from !== note.midi
+              ? { from: midiToHz(note.from), to: hz, over: inst.glide }
+              : { from: hz, to: hz, over: 0 }
+        const vib = inst.vibrato && inst.vibrato.depth > 0 ? inst.vibrato : null
+        const table = waves.table(inst, hz)
+        for (let v = 0; v < voices; v++) {
+            const cents = voices === 1 ? spread : spread * ((2 * v) / (voices - 1) - 1)
+            oscillatorRun(buf, n, t0, rate, table, pitch, cents, vib, 1 / Math.sqrt(voices))
+        }
+    }
+    applyEnvelope(buf, n, t0, rate, pts)
+    if (inst.filter) biquad(buf, n, rate, inst.filter.type, inst.filter.freq, inst.filter.q ?? 0.8)
+    const pan = inst.pan !== undefined && inst.pan !== 0 ? (Math.max(-1, Math.min(1, inst.pan)) + 1) / 2 : null
+    const gl = pan === null ? 1 : Math.cos((pan * Math.PI) / 2)
+    const gr = pan === null ? 1 : Math.sin((pan * Math.PI) / 2)
+    const send = bus.sendL && inst.reverb && inst.reverb > 0 ? inst.reverb : 0
+    mixRun(buf, n, i0, bus.l, bus.r, gl, gr)
+    if (send > 0) mixRun(buf, n, i0, bus.sendL!, bus.sendR!, gl * send, gr * send)
+}
+
+function mixRun(buf: Float32Array, n: number, at: number, l: Float32Array, r: Float32Array, gl: number, gr: number): void {
+    for (let i = 0; i < n; i++) {
+        const x = buf[i]!
+        l[at + i] = l[at + i]! + x * gl
+        r[at + i] = r[at + i]! + x * gr
+    }
+}
+
+/** the gain over the render: whole, then a dead stop or the closing fade at the end */
+function closeRun(l: Float32Array, r: Float32Array, rate: number, end: number, fade: number): void {
+    const a = Math.max(0, Math.floor(end * rate))
+    const b = Math.ceil((end + fade) * rate)
+    for (let i = a; i < l.length; i++) {
+        const g = i >= b ? 0 : Math.cos(((i - a) / (b - a)) * (Math.PI / 2))
+        l[i] = l[i]! * g
+        r[i] = r[i]! * g
+    }
+}
+
+/** `seconds` of the score from its start, rendered with a tail of TAIL_S: the notes starting before its end (and before
+ *  its stop, if any) played, closed with a fade at the end, or cut dead at its stop */
+export function renderScore(score: CompiledScore, seconds: number, rate = RATE): Rendered {
+    const n = Math.ceil(rate * (seconds + TAIL_S))
+    const room = score.reverb && score.reverb.mix > 0 ? score.reverb : null
+    const bus: Bus = { l: new Float32Array(n), r: new Float32Array(n), sendL: room ? new Float32Array(n) : null, sendR: room ? new Float32Array(n) : null }
+    const waves = new Waves(rate)
+    const end = Math.min(seconds, score.stop ?? Number.POSITIVE_INFINITY)
+    for (const note of score.notes) {
+        if (note.time >= end) break
+        const inst = score.instruments[note.instrument]
+        if (inst) playNote(bus, waves, inst, note)
+    }
+    if (room) {
+        const ir = impulse(room.seconds, rate)
+        convolveInto(bus.sendL!, bus.sendR!, ir[0], ir[1], bus.l, bus.r, impulseScale(ir, rate) * Math.min(1, room.mix * 1.6))
+    }
+    if (score.stop !== null && score.stop < seconds) closeRun(bus.l, bus.r, rate, score.stop, STOP_FADE_S)
+    else closeRun(bus.l, bus.r, rate, seconds, CLOSE_FADE_S)
+    master(bus.l, bus.r, rate)
+    return { rate, left: bus.l, right: bus.r }
+}
+
+/** the master chain: its gain, a gentle compressor, a fast limiter, then the soft ceiling */
+function master(l: Float32Array, r: Float32Array, rate: number): void {
+    for (let i = 0; i < l.length; i++) {
+        l[i] = l[i]! * MASTER_GAIN
+        r[i] = r[i]! * MASTER_GAIN
+    }
+    compress(l, r, rate, { threshold: -10, knee: 30, ratio: 4, attack: 0.003, release: 0.25 })
+    compress(l, r, rate, { threshold: -3, knee: 0, ratio: 20, attack: 0.001, release: 0.05 })
+    // a browser wave shaper clamps its input to [-1, 1] before its curve: the ceiling is softClip(1), never CEILING
+    for (let i = 0; i < l.length; i++) {
+        l[i] = softClip(Math.max(-1, Math.min(1, l[i]!)))
+        r[i] = softClip(Math.max(-1, Math.min(1, r[i]!)))
+    }
+}
+
+/** a sample this close to the ceiling is the soft clip working: distortion when it lasts */
+export const HOT = softClip(1) - 0.01

package/src/trailer/states.ts

@@ -0,0 +1,76 @@
+// what each frame of a take holds that a cut must not land on (wiki build/trailer.md, Film lines): a film command may
+// print `states <rle>`, each run of one state and its frames (`dialog*12,-*30`, `-` a plain frame, parts joined by `+`).
+// The stamp keeps it; the timeline names a shot whose edges cut into a change. Pure: no page, no file
+
+/** a frame with nothing on it a cut must mind */
+export const FREE = '-'
+
+/** `dialog*12,-*30`: each run of one state and its length */
+export function encodeStates(states: readonly string[]): string {
+    const runs: string[] = []
+    let i = 0
+    while (i < states.length) {
+        let j = i
+        while (j < states.length && states[j] === states[i]) j++
+        runs.push(`${states[i]}*${j - i}`)
+        i = j
+    }
+    return runs.join(',')
+}
+
+export function decodeStates(text: string): string[] {
+    const out: string[] = []
+    for (const run of text.split(',').filter(Boolean)) {
+        const at = run.lastIndexOf('*')
+        const n = Number(run.slice(at + 1))
+        if (at <= 0 || !Number.isInteger(n) || n < 1) throw new Error(`states: ${run} is no <state>*<frames>`)
+        for (let k = 0; k < n; k++) out.push(run.slice(0, at))
+    }
+    return out
+}
+
+/** the states a film's output says, its `states <rle>` word (on its own line or after ` · `); null when it says none */
+export function statesOf(said: string): string | null {
+    return /(?:^|\s·\s|\n)states (\S+)/.exec(said)?.[1] ?? null
+}
+
+/** frames at each edge of a shot where a change shows: a box rising or a change still playing reads as a flash */
+export const EDGE_FRAMES = 6
+
+export interface StatesRule {
+    /** parts that open on their own way in, never a change a cut minds */
+    ignore?: readonly string[]
+    /** parts that are a change under way: a shot never opens or ends on one */
+    underWay?: readonly string[]
+}
+
+/** what changes within EDGE_FRAMES of the shot's first or last frame (`first`, `last`: frames of the take), and a change
+ *  under way the shot opens or ends on: one line each, none when the edges are settled */
+export function edgeChanges(states: readonly string[], first: number, last: number, rule: StatesRule = {}): string[] {
+    const ignore = new Set(rule.ignore ?? [])
+    const parts = (s: string): string[] => (s === FREE ? [] : s.split('+').filter((x) => !ignore.has(x)))
+    const change = (from: string, to: string): string => {
+        const a = parts(from)
+        const b = parts(to)
+        return [...b.filter((x) => !a.includes(x)).map((x) => `${x} in`), ...a.filter((x) => !b.includes(x)).map((x) => `${x} out`)].join(', ')
+    }
+    const end = Math.min(last, states.length - 1)
+    if (first > end || first < 0) return []
+    const out: string[] = []
+    const seen = new Set<number>()
+    const at = (i: number): void => {
+        if (seen.has(i)) return
+        seen.add(i)
+        const after = i - first
+        const before = end - i + 1
+        out.push(`${change(states[i - 1]!, states[i]!)} ${after <= before ? `${after} frame${after === 1 ? '' : 's'} after its start` : `${before} frame${before === 1 ? '' : 's'} before its end`}`)
+    }
+    const moved = (i: number): boolean => change(states[i - 1]!, states[i]!) !== ''
+    for (let i = first + 1; i <= Math.min(end, first + EDGE_FRAMES); i++) if (moved(i)) at(i)
+    for (let i = Math.max(first + 1, end - EDGE_FRAMES + 1); i <= end; i++) if (moved(i)) at(i)
+    for (const u of rule.underWay ?? []) {
+        if (parts(states[first]!).includes(u)) out.unshift(`opens on a ${u}`)
+        if (end > first && parts(states[end]!).includes(u)) out.push(`ends on a ${u}`)
+    }
+    return out
+}

package/src/trailer/stitch.ts

@@ -0,0 +1,233 @@
+// the stitch: the cut rendered piece by piece (a piece = a section), each cached on its ffmpeg arguments and the size
+// and time of every file it reads, so an edit renders only the pieces it touches. The pieces join with no second
+// encode, the sound is mixed once (cached the same way) and muxed beside them, and the strip lays out each piece's row
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
+import { availableParallelism } from 'node:os'
+import { dirname, join } from 'node:path'
+import sharp from 'sharp'
+import { ffmpeg, loudnessKept } from './ffmpeg.ts'
+import { type Encoder, GRID_RADIUS, gridLayout, MIX_TRUE_PEAK, mixArgs, pieceArgs, type SplitMasks, splitPane, type StitchInput, THUMB_W } from './graph.ts'
+import type { TrailerLook } from './look.ts'
+import { type Piece, pieces } from './plan.ts'
+
+/** bump when the stitch changes what the same arguments make */
+const STITCH_VERSION = 1
+
+/** the files an ffmpeg command reads */
+const inputsOf = (args: string[]): string[] => args.flatMap((x, i) => (args[i - 1] === '-i' && existsSync(x) ? [x] : []))
+
+/** a render's key: its arguments (the outputs named alike) and every file it reads as it stands: a refilm rewrites a
+ *  take in place, so its size and time count */
+function keyOf(args: string[]): string {
+    const reads = inputsOf(args).map((f) => {
+        const s = statSync(f)
+        return [f, s.size, s.mtimeMs]
+    })
+    return new Bun.CryptoHasher('sha1').update(JSON.stringify([STITCH_VERSION, args, reads])).digest('hex').slice(0, 16)
+}
+
+/** a render kept under its key, one file per extension (the first always made, the others when the render has them):
+ *  made only when missing, written aside then moved in place, the first last */
+async function cached(dir: string, stem: string, exts: string[], make: (outs: string[]) => string[]): Promise<{ files: string[]; made: boolean }> {
+    return cachedAs(dir, stem, keyOf(make(exts.map((e) => `out.${e}`))), exts, make)
+}
+
+/** a render kept under a key its caller computed: for one whose inputs are rewritten by every build */
+export async function cachedAs(dir: string, stem: string, key: string, exts: string[], make: (outs: string[]) => string[]): Promise<{ files: string[]; made: boolean }> {
+    const files = exts.map((e) => join(dir, `${stem}-${key}.${e}`))
+    if (existsSync(files[0]!)) {
+        const now = new Date()
+        for (const f of files) if (existsSync(f)) utimesSync(f, now, now)
+        return { files, made: false }
+    }
+    mkdirSync(dir, { recursive: true })
+    const parts = exts.map((e) => join(dir, `${stem}-${key}.part.${e}`))
+    try {
+        await ffmpeg(make(parts), { nice: 10 })
+        for (let i = parts.length - 1; i >= 0; i--) if (existsSync(parts[i]!)) renameSync(parts[i]!, files[i]!)
+    } finally {
+        for (const f of parts) rmSync(f, { force: true })
+    }
+    return { files, made: true }
+}
+
+const n3 = (x: number): string => (+x.toFixed(4)).toString()
+
+/** a drawing's own temporary file beside `file`: two builds drawing one piece at once each rename their own */
+const partOf = (file: string): string => `${file}.${process.pid}-${Math.random().toString(36).slice(2, 8)}.part.png`
+
+async function drawSvg(file: string, svg: string): Promise<void> {
+    mkdirSync(dirname(file), { recursive: true })
+    const part = partOf(file)
+    await sharp(Buffer.from(svg)).png().toFile(part)
+    renameSync(part, file)
+}
+
+const colourKey = (look: Pick<TrailerLook, 'ground' | 'light' | 'edge'>): string => new Bun.CryptoHasher('sha1').update(JSON.stringify([look.ground, look.light, look.edge])).digest('hex').slice(0, 8)
+
+/** a grid's frame for `n` cells: the look's ground with a hole per cell, its corners rounded and rimmed in its light;
+ *  laid over the cells. Drawn once per layout and look and kept, so its file never changes a piece's key */
+export async function gridMask(dir: string, n: number, size: readonly [number, number], look: Pick<TrailerLook, 'ground' | 'light' | 'edge'>): Promise<string> {
+    const [W, H] = size
+    const file = join(dir, 'grid', `mask-${STITCH_VERSION}-${n}-${W}x${H}-${colourKey(look)}.png`)
+    if (existsSync(file)) return file
+    const r = H * GRID_RADIUS
+    const rim = Math.max(1.5, H * 0.0028)
+    const cells = gridLayout(n, W, H)
+    const holes = cells.map((c) => `<rect x="${c.x}" y="${c.y}" width="${c.w}" height="${c.h}" rx="${n3(r)}" fill="black"/>`).join('')
+    const rims = cells.map((c) => `<rect x="${c.x + rim / 2}" y="${c.y + rim / 2}" width="${c.w - rim}" height="${c.h - rim}" rx="${n3(r - rim / 2)}" fill="none" stroke="${look.light}" stroke-opacity="0.85" stroke-width="${n3(rim)}"/>`).join('')
+    await drawSvg(
+        file,
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}">
+<defs><radialGradient id="g" cx="50%" cy="45%" r="75%"><stop offset="0" stop-color="${look.ground[0]}"/><stop offset="1" stop-color="${look.ground[1]}"/></radialGradient>
+<mask id="m"><rect width="${W}" height="${H}" fill="white"/>${holes}</mask></defs>
+<rect width="${W}" height="${H}" fill="url(#g)" mask="url(#m)"/>${rims}</svg>`,
+    )
+    return file
+}
+
+/** a split's panes and seams for `n` panes at `angle`: each pane's shape, and the seams, a line of the look's light over
+ *  a soft shadow of its edge, its width a 150th of the frame's height. Drawn once and kept like the grid's frame */
+export async function splitMasks(dir: string, n: number, angle: number, size: readonly [number, number], look: Pick<TrailerLook, 'ground' | 'light' | 'edge'>): Promise<SplitMasks> {
+    const [W, H] = size
+    const stem = join(dir, 'split', `${STITCH_VERSION}-${n}-${n3(angle)}-${W}x${H}`)
+    const panes = Array.from({ length: n }, (_, j) => `${stem}-pane${j}.png`)
+    const seams = `${stem}-seams-${colourKey(look)}.png`
+    if ([...panes, seams].every((f) => existsSync(f))) return { panes, seams }
+    const poly = (pts: [number, number][]): string => pts.map(([x, y]) => `${n3(x)},${n3(y)}`).join(' ')
+    for (let j = 0; j < n; j++)
+        if (!existsSync(panes[j]!))
+            await drawSvg(panes[j]!, `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}"><rect width="${W}" height="${H}" fill="black"/><polygon points="${poly(splitPane(n, j, angle, W, H).points)}" fill="white"/></svg>`)
+    const t = Math.tan((angle * Math.PI) / 180)
+    // each seam drawn from well above the frame to well below it, so it crosses it whole
+    const lines = Array.from({ length: n - 1 }, (_, i) => (W * (i + 1)) / n)
+    const wLine = Math.max(2, H / 150)
+    const seg = (stroke: string, width: number): string =>
+        lines.map((x) => `<line x1="${n3(x + 1.5 * H * t)}" y1="${-H}" x2="${n3(x - 1.5 * H * t)}" y2="${2 * H}" stroke="${stroke}" stroke-width="${n3(width)}"/>`).join('')
+    await drawSvg(
+        seams,
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}"><defs><filter id="s" x="-50%" y="-50%" width="200%" height="200%"><feGaussianBlur stdDeviation="${n3(H / 90)}"/></filter></defs>` +
+            `<g filter="url(#s)" opacity="0.55">${seg(look.edge, wLine * 4)}</g>${seg(look.light, wLine)}</svg>`,
+    )
+    return { panes, seams }
+}
+
+/** runs the jobs, at most `n` at once */
+export async function pool<T>(jobs: (() => Promise<T>)[], n: number): Promise<T[]> {
+    const out: T[] = []
+    let next = 0
+    const lane = async (): Promise<void> => {
+        while (next < jobs.length) {
+            const i = next++
+            out[i] = await jobs[i]!()
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(n, jobs.length) }, lane))
+    return out
+}
+
+/** how many pieces render at once: a graph runs mostly on one core */
+const LANES = Math.max(1, Math.min(4, Math.floor(availableParallelism() / 2)))
+
+export interface Stitched {
+    /** the pieces, each with whether this run rendered it, its video and its row of the contact strip */
+    pieces: (Piece & { made: boolean; file: string; thumbs: string })[]
+    /** the sound was mixed again */
+    mixed: boolean
+    /** the mix file, null for a silent stitch */
+    mix: string | null
+}
+
+export interface StitchRun extends StitchInput {
+    out: string
+    /** where the rendered pieces and the mix are kept */
+    cache: string
+    encoder?: Encoder
+    /** no sound at all: a shot's preview */
+    silent?: boolean
+}
+
+async function renderPieces(a: StitchRun, ps: Piece[]): Promise<Stitched['pieces']> {
+    return pool(
+        ps.map((p) => async () => {
+            const { files, made } = await cached(a.cache, `${a.t.name}-${p.name}`, ['mp4', 'png'], ([video, row]) => pieceArgs(a, p, video!, a.encoder, row))
+            return { ...p, made, file: files[0]!, thumbs: files[1]! }
+        }),
+        LANES,
+    )
+}
+
+/** the mix, its true peak held under MIX_TRUE_PEAK after the aac encode: the encoder's band limit rings over a limited
+ *  harsh sound (a square wave measured +2.1 dB), so a mix that overshoots is made again that much lower */
+export async function renderMix(a: Pick<StitchRun, 't' | 'music' | 'sfx' | 'voices' | 'cache'>): Promise<{ file: string; made: boolean }> {
+    let trim = 0
+    let made = false
+    for (let pass = 0; ; pass++) {
+        const r = await cached(join(a.cache, 'mix'), `mix-${a.t.name}`, ['m4a'], ([out]) => mixArgs(a, out!, trim))
+        made ||= r.made
+        const { truePeak } = await loudnessKept(r.files[0]!)
+        if (truePeak <= MIX_TRUE_PEAK || pass === 2) return { file: r.files[0]!, made }
+        trim = +(trim - (truePeak - MIX_TRUE_PEAK) - 0.1).toFixed(2)
+    }
+}
+
+/** the pieces joined as they are, no encode, with the sound beside them: the whole mix copied, or a window of it (a
+ *  section alone) cut on its samples, so encoded again */
+async function joinPieces(files: string[], sound: { file: string; start?: number; seconds?: number } | null, out: string): Promise<void> {
+    mkdirSync(dirname(out), { recursive: true })
+    const list = `${out}.list.txt`
+    writeFileSync(list, files.map((f) => `file '${f.replaceAll("'", "'\\''")}'`).join('\n'))
+    const part = out.replace(/(\.\w+)$/, '.part$1')
+    const audio = sound ? [...(sound.start !== undefined ? ['-ss', n3(sound.start), '-t', n3(sound.seconds ?? 0)] : []), '-i', sound.file] : []
+    const acodec = sound?.start !== undefined ? ['-c:a', 'aac', '-b:a', '192k'] : ['-c:a', 'copy']
+    try {
+        await ffmpeg(['-f', 'concat', '-safe', '0', '-i', list, ...audio, '-map', '0:v', ...(sound ? ['-map', '1:a', ...acodec] : []), '-c:v', 'copy', '-movflags', '+faststart', part], { nice: 10 })
+        renameSync(part, out)
+    } finally {
+        rmSync(list, { force: true })
+        rmSync(part, { force: true })
+    }
+}
+
+/** the whole cut: every piece (rendered where the cache misses it), joined, with its sound */
+export async function stitch(a: StitchRun): Promise<Stitched> {
+    const [ps, mix] = await Promise.all([renderPieces(a, pieces(a.t)), a.silent ? null : renderMix(a)])
+    await joinPieces(ps.map((p) => p.file), mix ? { file: mix.file } : null, a.out)
+    return { pieces: ps, mixed: mix?.made ?? false, mix: mix?.file ?? null }
+}
+
+/** one piece alone (a section, `start` the shots before the first), with its window of the sound */
+export async function stitchPiece(a: StitchRun, name: string): Promise<Stitched> {
+    const p = pieces(a.t).find((x) => x.name === name)
+    if (!p) throw new Error(`no section ${name}: ${pieces(a.t).map((x) => x.name).join(', ')}`)
+    const [ps, mix] = await Promise.all([renderPieces(a, [p]), a.silent ? null : renderMix(a)])
+    await joinPieces(ps.map((x) => x.file), mix && { file: mix.file, start: p.from / a.t.fps, seconds: (p.to - p.from) / a.t.fps }, a.out)
+    return { pieces: ps, mixed: mix?.made ?? false, mix: mix?.file ?? null }
+}
+
+/** one frame from the middle of each shot, side by side, rows of six: the cut at a glance. Each piece drew its own
+ *  row as it rendered, so the strip only lays the rows out */
+export async function strip(ps: Pick<Stitched['pieces'][number], 'thumbs'>[], out: string): Promise<void> {
+    const rows = await Promise.all(ps.filter((p) => existsSync(p.thumbs)).map((p) => sharp(p.thumbs).removeAlpha().raw().toBuffer({ resolveWithObject: true })))
+    const h = rows[0]?.info.height ?? 0
+    const cells = rows.flatMap(({ data, info }) => Array.from({ length: Math.round(info.width / THUMB_W) }, (_, k) => ({ data, left: k * THUMB_W, width: info.width })))
+    if (cells.length === 0) return
+    const PAD = 6
+    const cols = Math.min(6, cells.length)
+    const W = cols * THUMB_W + (cols - 1) * PAD
+    const H = Math.ceil(cells.length / cols) * (h + PAD) - PAD
+    const grid = Buffer.alloc(W * H * 3)
+    cells.forEach((c, i) => {
+        const [x, y] = [(i % cols) * (THUMB_W + PAD), Math.floor(i / cols) * (h + PAD)]
+        for (let r = 0; r < h; r++) c.data.copy(grid, ((y + r) * W + x) * 3, (r * c.width + c.left) * 3, (r * c.width + c.left + THUMB_W) * 3)
+    })
+    await sharp(grid, { raw: { width: W, height: H, channels: 3 } }).png({ compressionLevel: 3 }).toFile(out)
+}
+
+/** which pieces a stitch rendered, in one phrase; the others came from the cache */
+export function rendered(d: Stitched): string {
+    const made = d.pieces.filter((p) => p.made).map((p) => p.name)
+    const all = d.pieces.length
+    const sound = d.mixed ? ', the sound mixed' : ''
+    return made.length === 0 ? `every section cached${sound}` : made.length === all ? `${all} section(s) rendered${sound}` : `rendered ${made.join(', ')}, ${all - made.length} of ${all} sections cached${sound}`
+}