rvlib-shipkit 2.2.0 → 2.4.0

package/src/trailer/score/dsp.ts

@@ -0,0 +1,272 @@
+// the signal blocks the score's synth is made of, each a pure function over Float32Arrays: the ADSR points, the biquad
+// (the Web Audio formulas, so an instrument sounds as it does in a browser synth), the compressor, the soft ceiling and
+// an FFT convolution for the room. Hot loops sit in top level functions over their arrays, no closure per sample
+
+/** [seconds from note start, gain] points; the last one is 0 at release end. A note released during its attack or
+ *  decay releases from the level it reached, never from the peak, so a short note never clicks */
+export function envPoints(env: { a: number; d: number; s: number; r: number }, dur: number, peak: number): [number, number][] {
+    const a = Math.max(0.001, env.a)
+    const d = Math.max(0, env.d)
+    const s = Math.max(0, Math.min(1, env.s)) * peak
+    const r = Math.max(0.005, env.r)
+    const off = Math.max(0, dur)
+    const pts: [number, number][] = [[0, 0]]
+    if (off <= a) pts.push([off, peak * (off / a)])
+    else {
+        pts.push([a, peak])
+        if (off <= a + d) pts.push([off, d === 0 ? s : peak + (s - peak) * ((off - a) / d)])
+        else {
+            pts.push([a + d, s])
+            pts.push([off, s])
+        }
+    }
+    const last = pts[pts.length - 1]
+    pts.push([(last?.[0] ?? off) + r, 0])
+    return pts.filter((p, i) => i === 0 || p[0] !== pts[i - 1]?.[0] || p[1] !== pts[i - 1]?.[1])
+}
+
+/** multiplies `buf` (its first sample at `t0` seconds after the note start) by the envelope's points */
+export function applyEnvelope(buf: Float32Array, n: number, t0: number, rate: number, pts: readonly [number, number][]): void {
+    let k = 1
+    for (let i = 0; i < n; i++) {
+        const t = t0 + i / rate
+        while (k < pts.length - 1 && t > pts[k]![0]) k++
+        const p = pts[k - 1]!
+        const q = pts[k]!
+        const g = t >= q[0] ? q[1] : q[0] === p[0] ? q[1] : p[1] + (q[1] - p[1]) * ((t - p[0]) / (q[0] - p[0]))
+        buf[i] = buf[i]! * (t < 0 ? 0 : g)
+    }
+}
+
+export type FilterType = 'lowpass' | 'highpass' | 'bandpass'
+
+/** a biquad in place, Web Audio's coefficients: lowpass and highpass read q in dB, bandpass as a plain q */
+export function biquad(buf: Float32Array, n: number, rate: number, type: FilterType, freq: number, q: number): void {
+    const f = Math.max(1, Math.min(rate / 2 - 1, freq))
+    const w0 = (2 * Math.PI * f) / rate
+    const cw = Math.cos(w0)
+    const sw = Math.sin(w0)
+    let b0: number, b1: number, b2: number
+    let alpha: number
+    if (type === 'bandpass') {
+        alpha = sw / (2 * Math.max(1e-4, q))
+        b0 = alpha
+        b1 = 0
+        b2 = -alpha
+    } else {
+        alpha = sw / (2 * 10 ** (q / 20))
+        const sign = type === 'lowpass' ? 1 : -1
+        b0 = (1 - sign * cw) / 2
+        b1 = sign * (1 - sign * cw)
+        b2 = b0
+    }
+    const a0 = 1 + alpha
+    biquadRun(buf, n, b0 / a0, b1 / a0, b2 / a0, (-2 * cw) / a0, (1 - alpha) / a0)
+}
+
+function biquadRun(buf: Float32Array, n: number, b0: number, b1: number, b2: number, a1: number, a2: number): void {
+    let z1 = 0
+    let z2 = 0
+    for (let i = 0; i < n; i++) {
+        const x = buf[i]!
+        const y = b0 * x + z1
+        z1 = b1 * x - a1 * y + z2
+        z2 = b2 * x - a2 * y
+        buf[i] = y
+    }
+}
+
+const CEILING = 0.98
+const KNEE = 0.7
+
+/** linear below the knee, tanh into the ceiling above it (slope 1 at the knee, so the join is smooth) */
+export function softClip(x: number): number {
+    const a = Math.abs(x)
+    if (a <= KNEE) return x
+    return Math.sign(x) * (KNEE + (CEILING - KNEE) * Math.tanh((a - KNEE) / (CEILING - KNEE)))
+}
+
+export interface CompressorDef {
+    /** dB */
+    threshold: number
+    /** dB */
+    knee: number
+    ratio: number
+    /** seconds */
+    attack: number
+    release: number
+}
+
+const lin = (db: number): number => 10 ** (db / 20)
+const dbOf = (x: number): number => 20 * Math.log10(Math.max(1e-12, x))
+
+/** the static curve of a browser compressor: a knee shaped by `k`, then the ratio's line; the knee's `k` is searched so
+ *  the curve meets the ratio's slope at the knee's top, and the output is lifted by its makeup gain */
+function staticCurve(c: CompressorDef): { saturate: (x: number) => number; makeup: number } {
+    const linThr = lin(c.threshold)
+    const kneeThrDb = c.threshold + c.knee
+    const kneeThr = lin(kneeThrDb)
+    const slope = 1 / c.ratio
+    const kneeCurve = (x: number, k: number): number => (x < linThr ? x : linThr + (1 - Math.exp(-k * (x - linThr))) / k)
+    const slopeAt = (x: number, k: number): number => {
+        if (x < linThr) return 1
+        const x2 = x * 1.001
+        return (dbOf(kneeCurve(x2, k)) - dbOf(kneeCurve(x, k))) / (dbOf(x2) - dbOf(x))
+    }
+    let lo = 0.1
+    let hi = 10000
+    let k = 5
+    for (let i = 0; i < 15; i++) {
+        if (slopeAt(kneeThr, k) < slope) hi = k
+        else lo = k
+        k = Math.sqrt(lo * hi)
+    }
+    const yKneeDb = dbOf(kneeCurve(kneeThr, k))
+    const saturate = (x: number): number => (x < kneeThr ? kneeCurve(x, k) : lin(yKneeDb + slope * (dbOf(x) - kneeThrDb)))
+    return { saturate, makeup: (1 / saturate(1)) ** 0.6 }
+}
+
+/** a stereo compressor in place, 6 ms of lookahead: the gain follows the louder channel, falling at `attack` and
+ *  rising at `release`, in dB */
+export function compress(l: Float32Array, r: Float32Array, rate: number, c: CompressorDef): void {
+    const { saturate, makeup } = staticCurve(c)
+    const n = l.length
+    // the curve sampled in dB of input, 0.05 dB a step, from -60 dB up to +24 dB
+    const lo = -60
+    const step = 0.05
+    const table = new Float32Array(Math.ceil((24 - lo) / step) + 2)
+    for (let i = 0; i < table.length; i++) {
+        const x = lin(lo + i * step)
+        table[i] = dbOf(saturate(x) / x)
+    }
+    compressRun(l, r, n, Math.round(0.006 * rate), Math.exp(-1 / (Math.max(1e-4, c.attack) * rate)), Math.exp(-1 / (Math.max(1e-4, c.release) * rate)), table, lo, step, makeup)
+}
+
+function compressRun(l: Float32Array, r: Float32Array, n: number, delay: number, att: number, rel: number, table: Float32Array, lo: number, step: number, makeup: number): void {
+    const dl = new Float32Array(delay)
+    const dr = new Float32Array(delay)
+    let env = 0
+    const last = table.length - 1
+    for (let i = 0; i < n; i++) {
+        const x = Math.max(Math.abs(l[i]!), Math.abs(r[i]!))
+        let target = 0
+        if (x > 1e-3) {
+            const p = (20 * Math.log10(x) - lo) / step
+            const j = Math.min(last - 1, Math.max(0, p | 0))
+            const f = Math.min(1, Math.max(0, p - j))
+            target = table[j]! + (table[j + 1]! - table[j]!) * f
+        }
+        env = target < env ? target + (env - target) * att : target + (env - target) * rel
+        const g = makeup * 10 ** (env / 20)
+        const k = i % delay
+        const yl = dl[k]!
+        const yr = dr[k]!
+        dl[k] = l[i]!
+        dr[k] = r[i]!
+        l[i] = yl * g
+        r[i] = yr * g
+    }
+}
+
+/** an in place radix 2 FFT; `inverse` scales by 1/n */
+export function fft(re: Float64Array, im: Float64Array, inverse: boolean): void {
+    const n = re.length
+    for (let i = 1, j = 0; i < n; i++) {
+        let bit = n >> 1
+        for (; j & bit; bit >>= 1) j ^= bit
+        j ^= bit
+        if (i < j) {
+            const tr = re[i]!
+            re[i] = re[j]!
+            re[j] = tr
+            const ti = im[i]!
+            im[i] = im[j]!
+            im[j] = ti
+        }
+    }
+    const sign = inverse ? 1 : -1
+    for (let len = 2; len <= n; len <<= 1) {
+        const ang = (sign * 2 * Math.PI) / len
+        const wr = Math.cos(ang)
+        const wi = Math.sin(ang)
+        const half = len >> 1
+        for (let i = 0; i < n; i += len) {
+            let cr = 1
+            let ci = 0
+            for (let k = 0; k < half; k++) {
+                const a = i + k
+                const b = a + half
+                const xr = re[b]! * cr - im[b]! * ci
+                const xi = re[b]! * ci + im[b]! * cr
+                re[b] = re[a]! - xr
+                im[b] = im[a]! - xi
+                re[a] = re[a]! + xr
+                im[a] = im[a]! + xi
+                const nr = cr * wr - ci * wi
+                ci = cr * wi + ci * wr
+                cr = nr
+            }
+        }
+    }
+    if (inverse) for (let i = 0; i < n; i++) {
+        re[i] = re[i]! / n
+        im[i] = im[i]! / n
+    }
+}
+
+/** adds `gain` times (inL, inR) convolved with the stereo impulse (irL, irR) to (outL, outR): overlap add, both
+ *  channels in one complex transform a block */
+export function convolveInto(inL: Float32Array, inR: Float32Array, irL: Float32Array, irR: Float32Array, outL: Float32Array, outR: Float32Array, gain: number): void {
+    const m = irL.length
+    let size = 1
+    while (size < 4 * m) size <<= 1
+    const block = size - m + 1
+    // the two impulses' spectra from one transform of irL + i irR, split by conjugate symmetry
+    const hr = new Float64Array(size)
+    const hi = new Float64Array(size)
+    hr.set(irL)
+    hi.set(irR)
+    fft(hr, hi, false)
+    const lr = new Float64Array(size)
+    const li = new Float64Array(size)
+    const rr = new Float64Array(size)
+    const ri = new Float64Array(size)
+    for (let k = 0; k < size; k++) {
+        const j = (size - k) % size
+        lr[k] = (hr[k]! + hr[j]!) / 2
+        li[k] = (hi[k]! - hi[j]!) / 2
+        rr[k] = (hi[k]! + hi[j]!) / 2
+        ri[k] = (hr[j]! - hr[k]!) / 2
+    }
+    const xr = new Float64Array(size)
+    const xi = new Float64Array(size)
+    const yr = new Float64Array(size)
+    const yi = new Float64Array(size)
+    const n = outL.length
+    for (let at = 0; at < inL.length; at += block) {
+        const len = Math.min(block, inL.length - at)
+        xr.fill(0)
+        xi.fill(0)
+        let loud = false
+        for (let i = 0; i < len; i++) {
+            xr[i] = inL[at + i]!
+            xi[i] = inR[at + i]!
+            if (xr[i] !== 0 || xi[i] !== 0) loud = true
+        }
+        if (!loud) continue
+        fft(xr, xi, false)
+        spectrumTimes(xr, xi, lr, li, yr, yi)
+        fft(yr, yi, true)
+        for (let i = 0; i < size && at + i < n; i++) outL[at + i] = outL[at + i]! + gain * yr[i]!
+        spectrumTimes(xr, xi, rr, ri, yr, yi)
+        fft(yr, yi, true)
+        for (let i = 0; i < size && at + i < n; i++) outR[at + i] = outR[at + i]! + gain * yi[i]!
+    }
+}
+
+function spectrumTimes(ar: Float64Array, ai: Float64Array, br: Float64Array, bi: Float64Array, or: Float64Array, oi: Float64Array): void {
+    for (let k = 0; k < ar.length; k++) {
+        or[k] = ar[k]! * br[k]! - ai[k]! * bi[k]!
+        oi[k] = ar[k]! * bi[k]! + ai[k]! * br[k]!
+    }
+}

package/src/trailer/score/gm-render.ts

@@ -0,0 +1,43 @@
+// a score's General MIDI tracks as stems: each GM instrument's notes written as a .mid, rendered by FluidSynth with
+// its own room off, read back for the synth to mix into the score's bus (its pan, its send to the room, the master)
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fluidRender, readWav } from '../sound/fluid.ts'
+import { stemMidi } from './midi.ts'
+import type { CompiledScore } from './score.ts'
+
+/** fluidsynth's gain for a stem: a GM instrument at vol 0.8 then sits near a synth one of the palette (measured on one
+ *  arpeggio: GM piano -26.9 dBFS at gain 1, the palette's keys -19.5) */
+const STEM_GAIN = 2.2
+
+export interface Stem {
+    instrument: string
+    left: Float32Array
+    right: Float32Array
+}
+
+/** the score's GM instruments that play a note before `end` */
+export const gmInstruments = (score: CompiledScore, end: number): string[] =>
+    [...new Set(score.notes.filter((n) => n.time < end && score.instruments[n.instrument]?.osc === 'gm').map((n) => n.instrument))]
+
+/** one stem a GM instrument, `rate` samples a second, its notes up to `end` seconds of the render */
+export function gmStems(score: CompiledScore, end: number, rate: number): Stem[] {
+    const names = gmInstruments(score, end)
+    if (names.length === 0) return []
+    const dir = mkdtempSync(join(tmpdir(), 'sk-gm-'))
+    try {
+        return names.map((name, i) => {
+            const v = score.instruments[name]!.gm!
+            const mid = join(dir, `${i}.mid`)
+            const wav = join(dir, `${i}.wav`)
+            writeFileSync(mid, stemMidi(score.notes.filter((n) => n.instrument === name), v, end))
+            fluidRender(mid, wav, { rate, room: false, gain: STEM_GAIN })
+            const w = readWav(wav)
+            if (w.rate !== rate) throw new Error(`fluidsynth rendered ${name} at ${w.rate} Hz, not ${rate}`)
+            return { instrument: name, left: w.left, right: w.right }
+        })
+    } finally {
+        rmSync(dir, { recursive: true, force: true })
+    }
+}

package/src/trailer/score/gm.ts

@@ -0,0 +1,90 @@
+// the General MIDI instruments a score track plays through the soundfont: the 128 programs and the drum keys by name,
+// and `gm()`, the instrument data a `gm:<name>` track or a code block names. Pure: FluidSynth renders them (gm-render.ts)
+import type { InstrumentDef } from './pattern.ts'
+
+/** the 128 programs in order, each a short kebab name */
+export const GM_PROGRAMS = [
+    'acoustic-grand', 'bright-acoustic', 'electric-grand', 'honky-tonk', 'electric-piano-1', 'electric-piano-2', 'harpsichord', 'clavinet',
+    'celesta', 'glockenspiel', 'music-box', 'vibraphone', 'marimba', 'xylophone', 'tubular-bells', 'dulcimer',
+    'drawbar-organ', 'percussive-organ', 'rock-organ', 'church-organ', 'reed-organ', 'accordion', 'harmonica', 'tango-accordion',
+    'nylon-guitar', 'steel-guitar', 'jazz-guitar', 'clean-guitar', 'muted-guitar', 'overdrive-guitar', 'distortion-guitar', 'guitar-harmonics',
+    'acoustic-bass', 'finger-bass', 'pick-bass', 'fretless-bass', 'slap-bass-1', 'slap-bass-2', 'synth-bass-1', 'synth-bass-2',
+    'violin', 'viola', 'cello', 'contrabass', 'tremolo-strings', 'pizzicato-strings', 'harp', 'timpani',
+    'strings', 'slow-strings', 'synth-strings-1', 'synth-strings-2', 'choir-aahs', 'voice-oohs', 'synth-choir', 'orchestra-hit',
+    'trumpet', 'trombone', 'tuba', 'muted-trumpet', 'french-horn', 'brass-section', 'synth-brass-1', 'synth-brass-2',
+    'soprano-sax', 'alto-sax', 'tenor-sax', 'baritone-sax', 'oboe', 'english-horn', 'bassoon', 'clarinet',
+    'piccolo', 'flute', 'recorder', 'pan-flute', 'blown-bottle', 'shakuhachi', 'whistle', 'ocarina',
+    'square-lead', 'saw-lead', 'calliope-lead', 'chiff-lead', 'charang-lead', 'voice-lead', 'fifths-lead', 'bass-lead',
+    'new-age-pad', 'warm-pad', 'polysynth-pad', 'choir-pad', 'bowed-pad', 'metallic-pad', 'halo-pad', 'sweep-pad',
+    'rain-fx', 'soundtrack-fx', 'crystal-fx', 'atmosphere-fx', 'brightness-fx', 'goblins-fx', 'echoes-fx', 'sci-fi-fx',
+    'sitar', 'banjo', 'shamisen', 'koto', 'kalimba', 'bagpipe', 'fiddle', 'shanai',
+    'tinkle-bell', 'agogo', 'steel-drums', 'woodblock', 'taiko-drum', 'melodic-tom', 'synth-drum', 'reverse-cymbal',
+    'guitar-fret-noise', 'breath-noise', 'seashore', 'bird-tweet', 'telephone-ring', 'helicopter', 'applause', 'gunshot',
+] as const
+
+/** the drum keys of channel 10 (35 to 81), by name */
+export const GM_DRUMS: Readonly<Record<string, number>> = {
+    'kick-2': 35, kick: 36, 'side-stick': 37, snare: 38, clap: 39, 'electric-snare': 40, 'low-floor-tom': 41, 'closed-hat': 42,
+    'high-floor-tom': 43, 'pedal-hat': 44, 'low-tom': 45, 'open-hat': 46, 'low-mid-tom': 47, 'high-mid-tom': 48, crash: 49, 'high-tom': 50,
+    ride: 51, china: 52, 'ride-bell': 53, tambourine: 54, splash: 55, cowbell: 56, 'crash-2': 57, vibraslap: 58,
+    'ride-2': 59, 'high-bongo': 60, 'low-bongo': 61, 'mute-high-conga': 62, 'open-high-conga': 63, 'low-conga': 64, 'high-timbale': 65, 'low-timbale': 66,
+    'high-agogo': 67, 'low-agogo': 68, cabasa: 69, maracas: 70, 'short-whistle': 71, 'long-whistle': 72, 'short-guiro': 73, 'long-guiro': 74,
+    claves: 75, 'high-woodblock': 76, 'low-woodblock': 77, 'mute-cuica': 78, 'open-cuica': 79, 'mute-triangle': 80, 'open-triangle': 81,
+}
+
+/** the drum kits of bank 128 by program: standard 0, room 8, power 16, electronic 24, 808 25, jazz 32, brush 40, orchestra 48 */
+export const GM_KITS = { standard: 0, room: 8, power: 16, electronic: 24, tr808: 25, jazz: 32, brush: 40, orchestra: 48 } as const
+
+/** a GM program or a drum of a kit */
+export interface GmVoice {
+    program: number
+    /** a drum: its key on channel 10, `program` its kit */
+    drum?: number
+}
+
+export interface GmOptions {
+    /** 0..1, default 0.8 */
+    vol?: number
+    pan?: number
+    reverb?: number
+    /** a drum's kit: a number or a name of GM_KITS */
+    kit?: number | keyof typeof GM_KITS
+}
+
+/** a program or a drum by name or number: `acoustic-grand`, 48, `kick`; null when no such name */
+export function gmVoice(name: string | number, kit: GmOptions['kit'] = 0): GmVoice | null {
+    const k = typeof kit === 'number' ? kit : GM_KITS[kit]
+    if (typeof name === 'number' || /^\d+$/.test(name)) {
+        const n = Number(name)
+        return Number.isInteger(n) && n >= 0 && n < 128 ? { program: n } : null
+    }
+    const p = (GM_PROGRAMS as readonly string[]).indexOf(name)
+    if (p >= 0) return { program: p }
+    const d = GM_DRUMS[name]
+    return d === undefined || k === undefined ? null : { program: k, drum: d }
+}
+
+/** the instrument a track plays through the soundfont: `gm('strings', { vol: 0.7, pan: -0.3 })`, `gm(48)`, `gm('kick', { kit: 'brush' })` */
+export function gm(name: string | number, o: GmOptions = {}): InstrumentDef {
+    const v = gmVoice(name, o.kit)
+    if (!v) throw new Error(`gm ${name}: no General MIDI program or drum of that name (sk sound gm lists them)`)
+    return {
+        osc: 'gm',
+        gm: v,
+        vol: o.vol ?? 0.8,
+        env: { a: 0, d: 0, s: 1, r: 0 },
+        ...(o.pan !== undefined ? { pan: o.pan } : {}),
+        ...(o.reverb !== undefined ? { reverb: o.reverb } : {}),
+    }
+}
+
+/** the GM name an instrument name `gm:<name>` holds, else null */
+export const gmName = (instrument: string): string | null => (instrument.startsWith('gm:') ? instrument.slice(3) : null)
+
+/** the programs and drums as lines: what `sk sound gm` prints */
+export function gmTable(): string[] {
+    const rows = GM_PROGRAMS.map((n, i) => `${String(i).padStart(3)} ${n}`)
+    const drums = Object.entries(GM_DRUMS).map(([n, k]) => `${String(k).padStart(3)} ${n}`)
+    const kits = Object.entries(GM_KITS).map(([n, k]) => `${String(k).padStart(3)} ${n}`)
+    return ['programs (track x gm:<name>, gm(<name or number>)):', ...rows, '', 'drums (drums k=gm:<name>, gm(<name>, { kit })):', ...drums, '', 'kits (gm(<drum>, { kit: <name or number> })):', ...kits]
+}

package/src/trailer/score/midi.ts

@@ -0,0 +1,143 @@
+// the score as a Standard MIDI File: `scoreMidi` writes the whole score for a DAW (a track per score track, the
+// sections' tempos and meters), `stemMidi` one GM instrument's notes at a fixed clock for FluidSynth to render.
+// Pure: bytes out, no file here
+import type { ScheduledNote, CompiledScore } from './score.ts'
+import type { InstrumentDef } from './pattern.ts'
+import { SCORE_LEAD } from '../grammar.ts'
+
+interface Ev {
+    tick: number
+    /** a sort key inside one tick: note offs first, then meta and program changes, then note ons */
+    order: number
+    data: number[]
+}
+
+const vlq = (n: number): number[] => {
+    const out = [n & 0x7f]
+    for (let v = n >> 7; v > 0; v >>= 7) out.unshift((v & 0x7f) | 0x80)
+    return out
+}
+
+const u32 = (n: number): number[] => [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]
+
+function chunk(type: string, body: number[]): number[] {
+    return [...Buffer.from(type, 'latin1'), ...u32(body.length), ...body]
+}
+
+function trackChunk(events: Ev[], name: string | null, end: number): number[] {
+    const sorted = [...events].sort((a, b) => a.tick - b.tick || a.order - b.order)
+    const body: number[] = []
+    let at = 0
+    if (name !== null) {
+        const bytes = [...Buffer.from(name, 'utf8')]
+        body.push(0, 0xff, 0x03, ...vlq(bytes.length), ...bytes)
+    }
+    for (const e of sorted) {
+        body.push(...vlq(Math.max(0, e.tick - at)), ...e.data)
+        at = Math.max(at, e.tick)
+    }
+    body.push(...vlq(Math.max(0, end - at)), 0xff, 0x2f, 0x00)
+    return chunk('MTrk', body)
+}
+
+/** a type 1 file: the conductor track, then each track */
+function smf(ppq: number, conductor: Ev[], tracks: { name: string; events: Ev[] }[], end: number): Uint8Array {
+    const head = chunk('MThd', [0, 1, 0, tracks.length + 1, (ppq >> 8) & 0xff, ppq & 0xff])
+    return new Uint8Array([...head, ...trackChunk(conductor, null, end), ...tracks.flatMap((t) => trackChunk(t.events, t.name, end))])
+}
+
+const velocity = (vol: number): number => Math.max(1, Math.min(127, Math.round(127 * vol)))
+
+/** what a synth instrument of the default palette is written as: its nearest GM program, a drum's key */
+const NEAREST: Readonly<Record<string, number>> = {
+    lead: 80, lead25: 80, flute: 73, ocarina: 79, reed: 71, keys: 4, glock: 9, cello: 42, bell: 14, pluck: 45, arp: 81, harmony: 81,
+    pad: 89, strings: 48, brass: 61, bass: 33, bassPulse: 38, bassSaw: 39, sub: 38,
+}
+const NEAREST_DRUM: Readonly<Record<string, number>> = { kick: 36, snare: 38, clap: 39, hat: 42, openhat: 46, crash: 49, tom: 45, shaker: 70 }
+
+/** a note as the file writes it: a drum on channel 10 at its key, else a program */
+function gmOf(name: string, inst: InstrumentDef | undefined, drum: boolean): { drum: true; key: number; kit: number } | { drum: false; program: number } {
+    if (inst?.gm) return inst.gm.drum !== undefined ? { drum: true, key: inst.gm.drum, kit: inst.gm.program } : { drum: false, program: inst.gm.program }
+    if (drum || inst?.osc === 'noise') return { drum: true, key: inst?.midi ?? NEAREST_DRUM[name] ?? 38, kit: 0 }
+    return { drum: false, program: inst?.midi ?? NEAREST[name] ?? 80 }
+}
+
+const PPQ = 480
+
+/** the whole score as a .mid: each score track a MIDI track, the sections' tempos and meters on the conductor track,
+ *  the score's time from its first section on; a note past the stop is cut there */
+export function scoreMidi(score: CompiledScore): Uint8Array {
+    const secs = score.sections
+    // each section's first tick, the score clock starting at the first section
+    const starts: { at: number; tick: number; bpm: number }[] = []
+    let tick = 0
+    for (const s of secs) {
+        starts.push({ at: s.at, tick, bpm: s.bpm })
+        tick += Math.round((s.seconds * s.bpm * PPQ) / 60)
+    }
+    const tickOf = (time: number): number => {
+        let k = 0
+        while (k + 1 < starts.length && starts[k + 1]!.at <= time + 1e-9) k++
+        const s = starts[k] ?? { at: SCORE_LEAD, tick: 0, bpm: 120 }
+        return Math.max(0, s.tick + Math.round(((time - s.at) * s.bpm * PPQ) / 60))
+    }
+    const stop = score.stop ?? Number.POSITIVE_INFINITY
+    const end = Math.min(tick, tickOf(stop))
+    const conductor: Ev[] = []
+    let meter = 0
+    let bpm = 0
+    for (const [i, s] of secs.entries()) {
+        const t = starts[i]!.tick
+        if (s.bpm !== bpm) conductor.push({ tick: t, order: 1, data: [0xff, 0x51, 0x03, ...u32(Math.round(60_000_000 / s.bpm)).slice(1)] })
+        if (s.meter !== meter) conductor.push({ tick: t, order: 1, data: [0xff, 0x58, 0x04, s.meter, 2, 24, 8] })
+        bpm = s.bpm
+        meter = s.meter
+    }
+    const byTrack = new Map<string, ScheduledNote[]>()
+    for (const n of score.notes) {
+        if (n.time >= stop) continue
+        byTrack.set(n.track, [...(byTrack.get(n.track) ?? []), n])
+    }
+    let next = 0
+    const tracks = [...byTrack.entries()].map(([name, notes]) => {
+        const channel = next === 9 ? ++next : next
+        next = Math.min(15, channel + 1)
+        const events: Ev[] = []
+        const program = new Map<number, number>()
+        for (const n of notes) {
+            const inst = score.instruments[n.instrument]
+            const g = gmOf(n.instrument, inst, n.midi === null)
+            const ch = g.drum ? 9 : channel
+            const want = g.drum ? g.kit : g.program
+            const a = tickOf(n.time)
+            if (program.get(ch) !== want && !(g.drum && want === 0 && !program.has(ch))) events.push({ tick: a, order: 1, data: [0xc0 | ch, want] })
+            program.set(ch, want)
+            const key = g.drum ? g.key : n.midi!
+            const b = Math.max(a + 1, Math.min(end, tickOf(Math.min(stop, n.time + n.dur))))
+            events.push({ tick: a, order: 2, data: [0x90 | ch, key, velocity(n.vol)] })
+            events.push({ tick: b, order: 0, data: [0x80 | ch, key, 0] })
+        }
+        return { name, events }
+    })
+    return smf(PPQ, conductor, tracks, end)
+}
+
+/** the clock a stem is written at: 120 bpm, so a tick is 1/1920 s */
+const STEM_PPQ = 960
+const STEM_TPS = (120 * STEM_PPQ) / 60
+
+/** one GM instrument's notes as a .mid at a fixed clock, its time the render's (lead counted), cut at `end` seconds */
+export function stemMidi(notes: readonly ScheduledNote[], v: { program: number; drum?: number }, end: number): Uint8Array {
+    const ch = v.drum !== undefined ? 9 : 0
+    const t = (s: number): number => Math.round(Math.min(s, end) * STEM_TPS)
+    const events: Ev[] = [{ tick: 0, order: 1, data: [0xc0 | ch, v.program] }]
+    for (const n of notes) {
+        if (n.time >= end) continue
+        const key = v.drum ?? n.midi ?? 60
+        const a = t(n.time)
+        events.push({ tick: a, order: 2, data: [0x90 | ch, key, velocity(n.vol)] })
+        events.push({ tick: Math.max(a + 1, t(n.time + n.dur)), order: 0, data: [0x80 | ch, key, 0] })
+    }
+    const conductor: Ev[] = [{ tick: 0, order: 1, data: [0xff, 0x51, 0x03, ...u32(500_000).slice(1)] }]
+    return smf(STEM_PPQ, conductor, [{ name: 'stem', events }], t(end))
+}