rvlib-shipkit 2.2.0 → 2.4.0

package/src/trailer/score/synth.ts

@@ -0,0 +1,383 @@
+// 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 { Stem } from './gm-render.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
+    }
+}
+
+/** a GM stem into the bus at its instrument's volume and pan, and its share into the room */
+function mixStem(bus: Bus, st: Stem, inst: InstrumentDef | undefined): void {
+    if (!inst) return
+    const n = Math.min(bus.l.length, st.left.length)
+    const pan = inst.pan !== undefined && inst.pan !== 0 ? (Math.max(-1, Math.min(1, inst.pan)) + 1) / 2 : null
+    const gl = inst.vol * (pan === null ? 1 : Math.SQRT2 * Math.cos((pan * Math.PI) / 2))
+    const gr = inst.vol * (pan === null ? 1 : Math.SQRT2 * Math.sin((pan * Math.PI) / 2))
+    const send = bus.sendL && inst.reverb && inst.reverb > 0 ? inst.reverb : 0
+    for (let i = 0; i < n; i++) {
+        const l = st.left[i]! * gl
+        const r = st.right[i]! * gr
+        bus.l[i] = bus.l[i]! + l
+        bus.r[i] = bus.r[i]! + r
+        if (send > 0) {
+            bus.sendL![i] = bus.sendL![i]! + l * send
+            bus.sendR![i] = bus.sendR![i]! + r * send
+        }
+    }
+}
+
+/** 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, stems: readonly Stem[] = []): 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 && inst.osc !== 'gm') playNote(bus, waves, inst, note)
+    }
+    for (const st of stems) mixStem(bus, st, score.instruments[st.instrument])
+    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/sound/audio.ts

@@ -0,0 +1,148 @@
+// what a made sound is, as numbers and one picture, since nobody hears a build: its length, peak, loudness, onsets
+// and its waveform png; and the trims a generator applies (the silence before, the tail, the first hit). ffmpeg does
+// the reading and the writing (trailer/ffmpeg.ts)
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { ffmpeg, loudness } from '../ffmpeg.ts'
+
+export const SOUND_RATE = 48000
+/** the envelope's window */
+const WIN_S = 0.01
+
+/** the file's samples, both channels, at SOUND_RATE */
+export async function decode(file: string): Promise<{ left: Float32Array; right: Float32Array }> {
+    const dir = mkdtempSync(join(tmpdir(), 'sk-sound-'))
+    try {
+        const raw = join(dir, 'pcm.f32')
+        await ffmpeg(['-y', '-v', 'error', '-i', file, '-ac', '2', '-ar', String(SOUND_RATE), '-f', 'f32le', raw])
+        const b = readFileSync(raw)
+        const all = new Float32Array(b.buffer, b.byteOffset, Math.floor(b.byteLength / 4))
+        const n = all.length >> 1
+        const left = new Float32Array(n)
+        const right = new Float32Array(n)
+        for (let i = 0; i < n; i++) {
+            left[i] = all[i * 2]!
+            right[i] = all[i * 2 + 1]!
+        }
+        return { left, right }
+    } finally {
+        rmSync(dir, { recursive: true, force: true })
+    }
+}
+
+const db = (x: number): number => (x > 1e-9 ? 20 * Math.log10(x) : -180)
+
+/** each window's RMS in dBFS, the louder channel */
+export function envelope(s: { left: Float32Array; right: Float32Array }): number[] {
+    const w = Math.round(WIN_S * SOUND_RATE)
+    const out: number[] = []
+    for (let a = 0; a < s.left.length; a += w) {
+        let l = 0
+        let r = 0
+        const b = Math.min(s.left.length, a + w)
+        for (let i = a; i < b; i++) {
+            l += s.left[i]! ** 2
+            r += s.right[i]! ** 2
+        }
+        out.push(db(Math.sqrt(Math.max(l, r) / Math.max(1, b - a))))
+    }
+    return out
+}
+
+/** the sample peak in dBFS */
+export function peakOf(s: { left: Float32Array; right: Float32Array }): number {
+    let p = 0
+    for (let i = 0; i < s.left.length; i++) p = Math.max(p, Math.abs(s.left[i]!), Math.abs(s.right[i]!))
+    return db(p)
+}
+
+/** the windows a new sound starts on: a rise of 9 dB over the 50 ms before, within 35 dB of the loudest window, 80 ms
+ *  after the last onset at least */
+export function onsets(env: readonly number[]): number[] {
+    const top = Math.max(...env)
+    const out: number[] = []
+    for (let i = 0; i < env.length; i++) {
+        if (env[i]! < top - 35) continue
+        const before = i === 0 ? -180 : Math.min(...env.slice(Math.max(0, i - 5), i))
+        if (env[i]! - before < 9) continue
+        if (out.length > 0 && i - out.at(-1)! < 8) continue
+        out.push(i)
+    }
+    return out
+}
+
+export interface Trim {
+    start: number
+    end: number
+    /** seconds of fade at the end */
+    fade: number
+}
+
+/** where a made sound starts and ends: the silence before cut (40 dB under its loudest window), the tail cut where it
+ *  stays `tailDb` under it; `hit`: only its first hit, also cut just before the next onset, its fade a share of it */
+export function trimOf(env: readonly number[], o: { tailDb: number; hit?: boolean }): Trim {
+    const top = Math.max(...env)
+    const first = Math.max(0, env.findIndex((x) => x >= top - 40) - 1)
+    let last = env.length - 1
+    while (last > first && env[last]! < top - o.tailDb) last--
+    if (!o.hit) return { start: first * WIN_S, end: (last + 1) * WIN_S, fade: 0.03 }
+    const next = onsets(env).find((i) => i > first + 2)
+    if (next !== undefined) last = Math.min(last, next - 2)
+    // the quiet floor between the hit and the next one is tail too
+    while (last > first && env[last]! < top - o.tailDb) last--
+    const len = (last + 1 - first) * WIN_S
+    return { start: first * WIN_S, end: (last + 1) * WIN_S, fade: Math.min(0.12, Math.max(0.02, len * 0.15)) }
+}
+
+/** the trimmed sound written as a 48 kHz 16 bit stereo wav */
+export async function writeTrimmed(src: string, out: string, t: Trim): Promise<void> {
+    const len = Math.max(0.02, t.end - t.start)
+    const fade = Math.min(t.fade, len / 2)
+    const af = [`atrim=${t.start.toFixed(3)}:${t.end.toFixed(3)}`, 'asetpts=PTS-STARTPTS', `afade=t=out:st=${(len - fade).toFixed(3)}:d=${fade.toFixed(3)}`].join(',')
+    await ffmpeg(['-y', '-v', 'error', '-i', src, '-af', af, '-ac', '2', '-ar', String(SOUND_RATE), '-c:a', 'pcm_s16le', out])
+}
+
+/** the true peak no made sound passes */
+const CEILING_DBTP = -1.5
+
+/** the trimmed sound written at its level: `lufs` its integrated loudness (a sound too short to measure, under 0.4 s,
+ *  set by its peak at -3 dBFS), `peak` its sample peak; never past -1.5 dBTP. A measured static gain, so a short line
+ *  lands where a long one does */
+export async function finish(src: string, out: string, t: Trim, level: { lufs: number } | { peak: number }): Promise<void> {
+    const trimmed = `${out}.trim.wav`
+    try {
+        await writeTrimmed(src, trimmed, t)
+        const peak = peakOf(await decode(trimmed))
+        const m = await loudness(trimmed)
+        const gain = 'peak' in level ? Math.min(level.peak - peak, CEILING_DBTP - m.truePeak) : m.lufs > -70 && t.end - t.start >= 0.4 ? Math.min(level.lufs - m.lufs, CEILING_DBTP - m.truePeak) : -3 - peak
+        await ffmpeg(['-y', '-v', 'error', '-i', trimmed, '-af', `volume=${gain.toFixed(2)}dB`, '-c:a', 'pcm_s16le', out])
+    } finally {
+        rmSync(trimmed, { force: true })
+    }
+}
+
+export interface Measures {
+    seconds: number
+    peak: number
+    lufs: number
+    /** seconds of each onset */
+    onsets: number[]
+}
+
+/** a sound as numbers */
+export async function measure(file: string): Promise<Measures> {
+    const s = await decode(file)
+    const env = envelope(s)
+    const { lufs } = await loudness(file)
+    return { seconds: +(s.left.length / SOUND_RATE).toFixed(3), peak: +peakOf(s).toFixed(1), lufs: +lufs.toFixed(1), onsets: onsets(env).map((i) => +(i * WIN_S).toFixed(2)) }
+}
+
+/** the measures as one line */
+export const measureLine = (m: Measures): string =>
+    `${m.seconds.toFixed(2)} s, peak ${m.peak.toFixed(1)} dBFS, ${Number.isFinite(m.lufs) ? m.lufs.toFixed(1) : '-inf'} LUFS, ${m.onsets.length} onset${m.onsets.length === 1 ? '' : 's'}${m.onsets.length ? ` at ${m.onsets.slice(0, 8).join(', ')}${m.onsets.length > 8 ? ' …' : ''} s` : ''}`
+
+/** the waveform as a png, 1200 by 240 */
+export async function waveformPng(file: string, png: string): Promise<void> {
+    await ffmpeg(['-y', '-v', 'error', '-i', file, '-filter_complex', 'showwavespic=s=1200x240:split_channels=1:colors=#f0c674|#81a2be', '-frames:v', '1', png])
+}

package/src/trailer/sound/brand.ts

@@ -0,0 +1,42 @@
+// the voices a brand declares for its trailers (`.shipkit/identity/brand.ts`, its `trailer.voice` and
+// `trailer.voices`): an ElevenLabs voice, a clip comfy-ts clones, or a voice comfy-ts designs from words. Pure
+export type TrailerVoice =
+    /** ElevenLabs, paid: a voice id of the account or its library */
+    | { eleven: string; model?: string; stability?: number; similarity?: number; speed?: number; language?: string }
+    /** comfy-ts clones a clean 5 to 10 s clip (repo relative); its transcript, default the text of `<clip>.txt` */
+    | { clone: string; transcript?: string; engine?: string; language?: string }
+    /** comfy-ts designs the voice once from its description (the reference reads `line`), then clones it, free */
+    | { design: string; line?: string; seed?: number; engine?: string; language?: string }
+
+export interface TrailerSoundInput {
+    /** the comfy-ts module folder the free generators run (its tts-voice-clone, tts-voice-design, stable-audio,
+     *  ace-step): `comfy-ts run <comfy>/<module>` */
+    comfy?: string
+    /** argv printing the ElevenLabs key on stdout, as a secret manager read (ELEVENLABS_API_KEY wins); never the key */
+    elevenKey?: string[]
+    /** the voice every `voice "<line>"` reads */
+    voice?: TrailerVoice
+    /** more voices, by name, for `voice "<line>" by <name>` */
+    voices?: Record<string, TrailerVoice>
+}
+
+/** a repo with no voice: the house narrator, designed by comfy-ts */
+export const HOUSE_VOICE: TrailerVoice = {
+    design: 'a warm, clear narrator in their thirties, natural and unhurried, close to the microphone, studio quality',
+    line: 'Every story starts somewhere. This one starts right here, with you, and it is only getting better.',
+    seed: 7,
+}
+
+const kinds = (v: TrailerVoice): string[] => ['eleven', 'clone', 'design'].filter((k) => k in v && typeof (v as Record<string, unknown>)[k] === 'string')
+
+/** the voice a line reads with: `by` one of the brand's voices, else its voice, else the house narrator */
+export function voiceOf(brand: TrailerSoundInput | undefined, by?: string): TrailerVoice {
+    const v = by === undefined ? (brand?.voice ?? HOUSE_VOICE) : brand?.voices?.[by]
+    if (!v) {
+        const names = Object.keys(brand?.voices ?? {})
+        throw new Error(`no voice ${by} in the brand: ${names.length ? `its voices are ${names.join(', ')}` : 'it names none (trailer.voices in .shipkit/identity/brand.ts)'}`)
+    }
+    const k = kinds(v)
+    if (k.length !== 1) throw new Error(`the brand's voice${by ? ` ${by}` : ''} names ${k.length ? k.join(' and ') : 'nothing'}: one of eleven (a voice id), clone (a clip) or design (a description)`)
+    return v
+}

package/src/trailer/sound/comfy.ts

@@ -0,0 +1,38 @@
+// a comfy-ts module run on the GPU box: its vars as flags, the file at `out`, its progress on stderr, a loud failure
+// that names the box when it is down. The modules sit in the folder the brand names (`trailer.comfy`)
+import { killGroup } from './run.ts'
+
+/** the module `name` of the folder `comfy`, or a loud error when no folder is named */
+export function comfyModule(comfy: string | undefined, name: string): string {
+    if (!comfy) throw new Error(`no comfy-ts module folder for ${name}: name it in the brand (trailer.comfy) or pass --comfy <folder>`)
+    return `${comfy}/${name}`
+}
+
+/** a module run that has not answered in this long is killed, loud */
+const COMFY_TIMEOUT_S = 15 * 60
+
+export async function comfyRun(module: string, vars: Record<string, string | number | boolean | undefined>, out: string): Promise<void> {
+    const args = ['comfy-ts', 'run', module]
+    for (const [k, v] of Object.entries(vars)) if (v !== undefined) args.push(`--${k}`, String(v))
+    args.push('--out', out, '--json')
+    const p = Bun.spawn(args, { stdout: 'pipe', stderr: 'inherit', detached: true })
+    let timedOut = false
+    const timer = setTimeout(() => {
+        timedOut = true
+        killGroup(p.pid)
+    }, COMFY_TIMEOUT_S * 1000)
+    const text = await new Response(p.stdout).text()
+    const code = await p.exited.finally(() => clearTimeout(timer))
+    if (timedOut) throw new Error(`comfy-ts run ${module} did not answer in ${COMFY_TIMEOUT_S} s and was killed. Is the GPU box up?`)
+    const last = text.trim().split('\n').at(-1) ?? ''
+    let res: { ok?: boolean; error?: string } = {}
+    try {
+        res = JSON.parse(last) as typeof res
+    } catch {
+        // not json: the tail below says what happened
+    }
+    if (code !== 0 || res.ok === false) {
+        const why = res.error ?? text.trim().split('\n').slice(-3).join(' ')
+        throw new Error(`comfy-ts run ${module} failed (exit ${code}): ${why || 'no output'}. Is the GPU box up?`)
+    }
+}