rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/score/compose.ts

@@ -0,0 +1,240 @@
+// composition helpers for a score's `code` and `play` lines: they only build pattern strings in the grammar of
+// pattern.ts, so a score stays plain note data once evaluated. Chords are written per bar, bars split by '|', a bar
+// holding several chords splits evenly: 'C | Am | F G | C'.
+
+import { noteToMidi } from './pattern.ts'
+
+const NAMES = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']
+
+export function midiToNote(midi: number): string {
+    const oct = Math.floor(midi / 12) - 1
+    if (oct < 0 || oct > 8) throw new Error(`note ${midi} outside octaves 0..8`)
+    return `${NAMES[midi % 12]}${oct}`
+}
+
+/** joins pattern fragments into one row string */
+export function seq(...parts: string[]): string {
+    return parts.join(' ')
+}
+
+export function rep(part: string, n: number): string {
+    return Array.from({ length: n }, () => part).join(' ')
+}
+
+function splitMods(tok: string): { mods: string; body: string } {
+    const i = tok.lastIndexOf(':')
+    return i === -1 ? { mods: '', body: tok } : { mods: tok.slice(0, i + 1), body: tok.slice(i + 1) }
+}
+
+/** shifts every note token by `semis` (plain rows or `mel` shorthand), modifiers, holds, rests and drums kept */
+export function transpose(text: string, semis: number): string {
+    return text
+        .split(/\s+/)
+        .filter((t) => t !== '')
+        .map((tok) => {
+            const { mods, body } = splitMods(tok)
+            const [note = '', len] = body.split('/')
+            const midi = noteToMidi(note)
+            return midi === null ? tok : mods + midiToNote(midi + semis) + (len === undefined ? '' : `/${len}`)
+        })
+        .join(' ')
+}
+
+/**
+ * durations shorthand: `E5/4` is E5 held 4 rows, `-/2` two rows of silence,
+ * a bare token lasts `unit` rows. Modifiers glue before the note:
+ * `v10:E5/4`, `@bell:C6/2`. Drum letters work the same way.
+ */
+export function mel(text: string, unit = 1): string {
+    const out: string[] = []
+    for (const tok of text.split(/\s+/)) {
+        if (tok === '' || tok === '|') continue
+        const slash = tok.lastIndexOf('/')
+        const head = slash === -1 ? tok : tok.slice(0, slash)
+        const len = slash === -1 ? unit : Number(tok.slice(slash + 1))
+        if (!Number.isInteger(len) || len < 1) throw new Error(`mel token "${tok}": bad length`)
+        const { body } = splitMods(head)
+        out.push(head)
+        for (let i = 1; i < len; i++) out.push(body === '-' ? '-' : '.')
+    }
+    return out.join(' ')
+}
+
+// chord qualities as semitone stacks above the root
+const QUALITIES: Record<string, number[]> = {
+    '': [0, 4, 7],
+    m: [0, 3, 7],
+    '7': [0, 4, 7, 10],
+    m7: [0, 3, 7, 10],
+    maj7: [0, 4, 7, 11],
+    dim: [0, 3, 6],
+    dim7: [0, 3, 6, 9],
+    aug: [0, 4, 8],
+    sus4: [0, 5, 7],
+    sus2: [0, 2, 7],
+    add9: [0, 4, 7, 14],
+    m9: [0, 3, 7, 10, 14],
+    '6': [0, 4, 7, 9],
+    m6: [0, 3, 7, 9],
+    '5': [0, 7],
+}
+
+export interface Chord {
+    /** pitch class 0..11 of the bass note (the slash note when given) */
+    bass: number
+    root: number
+    tones: number[]
+}
+
+/** 'C', 'F#m7', 'Bbmaj7', 'G/B' */
+export function parseChord(sym: string): Chord {
+    const [main = '', slash] = sym.split('/')
+    const m = /^([A-G])([#b]?)(.*)$/.exec(main)
+    if (!m) throw new Error(`chord "${sym}": no root`)
+    const pc = (l: string, a: string) => ((noteToMidi(`${l}${a}4`) ?? 0) + 120) % 12
+    const root = pc(m[1] ?? 'C', m[2] ?? '')
+    const q = QUALITIES[m[3] ?? '']
+    if (!q) throw new Error(`chord "${sym}": unknown quality "${m[3]}"`)
+    let bass = root
+    if (slash !== undefined) {
+        const s = /^([A-G])([#b]?)$/.exec(slash)
+        if (!s) throw new Error(`chord "${sym}": bad slash bass`)
+        bass = pc(s[1] ?? 'C', s[2] ?? '')
+    }
+    return { root, bass, tones: q }
+}
+
+interface Seg {
+    chord: Chord
+    rows: number
+}
+
+/** the chord chart as segments; `bar` is rows per bar */
+export function chart(text: string, bar = 16): Seg[] {
+    const segs: Seg[] = []
+    for (const b of text.split('|')) {
+        const syms = b.split(/\s+/).filter((s) => s !== '')
+        if (syms.length === 0) continue
+        if (bar % syms.length !== 0) throw new Error(`chart bar "${b}" does not split ${bar} rows evenly`)
+        for (const s of syms) segs.push({ chord: parseChord(s), rows: bar / syms.length })
+    }
+    return segs
+}
+
+/** lowest midi of pitch class `pc` at or above the C of `oct` */
+function at(pc: number, oct: number): number {
+    return 12 * (oct + 1) + pc
+}
+
+export type BassStyle =
+    | 'hold' // root held the whole segment
+    | 'half' // root, then fifth at half
+    | 'quarter' // root on every beat
+    | 'octave' // eighths bouncing root, octave
+    | 'drive' // straight eighths on the root, octave jump on the last
+    | 'gallop' // eighth + two sixteenths per beat
+    | 'walk' // quarters root, third, fifth, a step to the next root
+    | 'waltz' // root on the beat, chord fifth on beats 2 and 3 (3 beat bars)
+    | 'pulse' // root on beats 1 and 3, rests between
+
+/** a bass line over a chart, in octave `oct` (2 = the usual register) */
+export function bass(text: string, style: BassStyle, oct = 2, bar = 16, beat = 4): string {
+    const segs = chart(text, bar)
+    const out: string[] = []
+    segs.forEach((seg, i) => {
+        const r = at(seg.chord.bass, oct)
+        const fifth = at(seg.chord.root, oct) + 7
+        const third = at(seg.chord.root, oct) + (seg.chord.tones[1] ?? 4)
+        const next = segs[(i + 1) % segs.length]?.chord.bass ?? seg.chord.bass
+        const rows: string[] = []
+        const put = (row: number, midi: number | '-') => {
+            rows[row] = midi === '-' ? '-' : midiToNote(midi)
+        }
+        for (let k = 0; k < seg.rows; k++) rows.push('.')
+        switch (style) {
+            case 'hold':
+                put(0, r)
+                break
+            case 'half':
+                put(0, r)
+                if (seg.rows >= 2) put(seg.rows / 2, fifth > r + 9 ? fifth - 12 : fifth)
+                break
+            case 'quarter':
+                for (let k = 0; k < seg.rows; k += beat) put(k, r)
+                break
+            case 'octave':
+                for (let k = 0; k < seg.rows; k += beat / 2) put(k, (k / (beat / 2)) % 2 === 0 ? r : r + 12)
+                break
+            case 'drive':
+                for (let k = 0; k < seg.rows; k += beat / 2) put(k, k === seg.rows - beat / 2 && seg.rows >= bar ? r + 12 : r)
+                break
+            case 'gallop':
+                for (let k = 0; k < seg.rows; k += beat) {
+                    put(k, r)
+                    if (k + 2 < seg.rows) put(k + 2, r)
+                    if (k + 3 < seg.rows) put(k + 3, k + beat >= seg.rows ? r + 12 : r)
+                }
+                break
+            case 'walk': {
+                const target = at(next, oct)
+                const approach = target > r ? target - 1 : target + 1
+                const steps = [r, third, fifth > r + 9 ? fifth - 12 : fifth, approach]
+                for (let k = 0, j = 0; k < seg.rows; k += beat, j++) put(k, steps[Math.min(j, 3)] ?? r)
+                if (seg.rows <= beat * 2) {
+                    rows.fill('.')
+                    put(0, r)
+                    if (seg.rows > beat) put(beat, approach)
+                }
+                break
+            }
+            case 'waltz':
+                for (let k = 0; k < seg.rows; k += beat) put(k, k === 0 ? r : fifth > r + 9 ? fifth - 12 : fifth)
+                break
+            case 'pulse':
+                for (let k = 0; k < seg.rows; k += beat * 2) {
+                    put(k, r)
+                    if (k + beat < seg.rows) put(k + beat, '-')
+                }
+                break
+        }
+        out.push(...rows)
+    })
+    return out.join(' ')
+}
+
+/**
+ * an arpeggio over a chart: `shape` indexes the chord tones upward (0 root,
+ * 1 third, 2 fifth, 3 the root an octave up for a triad...), one index per
+ * step of `step` rows, cycling through the segment.
+ */
+export function arp(text: string, shape: number[], oct = 4, step = 2, bar = 16): string {
+    const out: string[] = []
+    for (const seg of chart(text, bar)) {
+        const n = seg.chord.tones.length
+        for (let k = 0, j = 0; k < seg.rows; k += step, j++) {
+            const idx = shape[j % shape.length] ?? 0
+            const iv = (seg.chord.tones[idx % n] ?? 0) + 12 * Math.floor(idx / n)
+            out.push(midiToNote(at(seg.chord.root, oct) + iv))
+            for (let h = 1; h < step && k + h < seg.rows; h++) out.push('.')
+        }
+    }
+    return out.join(' ')
+}
+
+/**
+ * one voice of a held chord: tone `which` of each chord, placed at or above
+ * `floor` (a midi note), re-struck per segment. Stack two or three pad tracks
+ * on different tones for a full chord.
+ */
+export function voice(text: string, which: number, floor: number, bar = 16, restrike = 0): string {
+    const out: string[] = []
+    for (const seg of chart(text, bar)) {
+        const n = seg.chord.tones.length
+        const iv = (seg.chord.tones[which % n] ?? 0) + 12 * Math.floor(which / n)
+        let m = seg.chord.root + iv
+        while (m < floor) m += 12
+        const note = midiToNote(m)
+        for (let k = 0; k < seg.rows; k++) out.push(k === 0 || (restrike > 0 && k % restrike === 0) ? note : '.')
+    }
+    return out.join(' ')
+}

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/palette.ts

@@ -0,0 +1,188 @@
+import type { InstrumentDef } from './pattern.ts'
+
+/** one cycle of a wave from its harmonic levels (the fundamental first), for an instrument's `wave` */
+export function additive(levels: number[], samples = 64): number[] {
+    return Array.from({ length: samples }, (_, i) =>
+        levels.reduce((sum, level, k) => sum + level * Math.sin((2 * Math.PI * (k + 1) * i) / samples), 0),
+    )
+}
+
+// the default instrument palette; a score spreads one and overrides what it needs: `lead: { ...INST.lead, duty: 0.25 }`.
+// With no `export const instruments` in its code, a score plays these
+export const INST = {
+    lead: {
+        osc: 'pulse',
+        duty: 0.5,
+        vol: 0.4,
+        env: { a: 0.015, d: 0.15, s: 0.65, r: 0.1 },
+        vibrato: { delay: 0.18, depth: 0.12, rate: 5.5 },
+        reverb: 0.2,
+    },
+    lead25: {
+        osc: 'pulse',
+        duty: 0.25,
+        vol: 0.38,
+        env: { a: 0.015, d: 0.12, s: 0.6, r: 0.1 },
+        vibrato: { delay: 0.2, depth: 0.12, rate: 5.5 },
+        reverb: 0.2,
+    },
+    flute: {
+        osc: 'triangle',
+        vol: 0.55,
+        env: { a: 0.03, d: 0.2, s: 0.75, r: 0.15 },
+        vibrato: { delay: 0.25, depth: 0.15, rate: 5 },
+        reverb: 0.35,
+    },
+    ocarina: {
+        osc: 'triangle',
+        vol: 0.5,
+        env: { a: 0.045, d: 0.2, s: 0.8, r: 0.2 },
+        vibrato: { delay: 0.3, depth: 0.12, rate: 4.8 },
+        reverb: 0.35,
+    },
+    // odd harmonics, as a clarinet's
+    reed: {
+        osc: 'wave',
+        wave: additive([1, 0.05, 0.45, 0.04, 0.2, 0.02, 0.08]),
+        tone: 2600,
+        vol: 0.4,
+        env: { a: 0.03, d: 0.2, s: 0.75, r: 0.14 },
+        vibrato: { delay: 0.3, depth: 0.1, rate: 5 },
+        reverb: 0.3,
+    },
+    // a soft electric piano: a round body, a touch of the fourth harmonic for the tine
+    keys: {
+        osc: 'wave',
+        wave: additive([1, 0.4, 0.1, 0.14, 0.03]),
+        vol: 0.34,
+        env: { a: 0.004, d: 0.55, s: 0.1, r: 0.3 },
+        reverb: 0.3,
+    },
+    glock: {
+        osc: 'wave',
+        wave: additive([1, 0, 0, 0.25]),
+        vol: 0.3,
+        env: { a: 0.002, d: 0.9, s: 0, r: 0.6 },
+        reverb: 0.45,
+    },
+    cello: {
+        osc: 'saw',
+        tone: 1500,
+        vol: 0.26,
+        env: { a: 0.09, d: 0.3, s: 0.85, r: 0.3 },
+        detune: 7,
+        unison: 2,
+        vibrato: { delay: 0.35, depth: 0.1, rate: 5 },
+        reverb: 0.35,
+    },
+    bell: { osc: 'sine', vol: 0.4, env: { a: 0.002, d: 0.6, s: 0.1, r: 0.5 }, reverb: 0.4 },
+    pluck: { osc: 'pulse', duty: 0.125, vol: 0.3, env: { a: 0.002, d: 0.12, s: 0.15, r: 0.05 }, reverb: 0.2 },
+    arp: { osc: 'pulse', duty: 0.25, vol: 0.22, env: { a: 0.002, d: 0.08, s: 0.3, r: 0.03 }, pan: 0.25, reverb: 0.15 },
+    harmony: {
+        osc: 'pulse',
+        duty: 0.25,
+        vol: 0.28,
+        env: { a: 0.01, d: 0.15, s: 0.55, r: 0.1 },
+        pan: -0.3,
+        reverb: 0.25,
+    },
+    pad: {
+        osc: 'saw',
+        vol: 0.16,
+        env: { a: 0.35, d: 0.4, s: 0.7, r: 0.6 },
+        detune: 8,
+        unison: 2,
+        filter: { type: 'lowpass', freq: 1400, q: 0.7 },
+        reverb: 0.5,
+    },
+    strings: {
+        osc: 'saw',
+        vol: 0.2,
+        env: { a: 0.12, d: 0.3, s: 0.8, r: 0.3 },
+        detune: 6,
+        unison: 2,
+        filter: { type: 'lowpass', freq: 2600, q: 0.8 },
+        vibrato: { delay: 0.3, depth: 0.08, rate: 5 },
+        reverb: 0.4,
+    },
+    brass: {
+        osc: 'saw',
+        vol: 0.3,
+        env: { a: 0.03, d: 0.2, s: 0.7, r: 0.12 },
+        filter: { type: 'lowpass', freq: 2200, q: 1.2 },
+        vibrato: { delay: 0.25, depth: 0.1, rate: 5.5 },
+        reverb: 0.25,
+    },
+    bass: { osc: 'triangle', vol: 0.65, env: { a: 0.002, d: 0.06, s: 0.9, r: 0.05 } },
+    bassPulse: {
+        osc: 'pulse',
+        duty: 0.5,
+        vol: 0.3,
+        env: { a: 0.002, d: 0.1, s: 0.7, r: 0.04 },
+        filter: { type: 'lowpass', freq: 900 },
+    },
+    bassSaw: {
+        osc: 'saw',
+        vol: 0.32,
+        env: { a: 0.002, d: 0.12, s: 0.6, r: 0.05 },
+        filter: { type: 'lowpass', freq: 700, q: 2 },
+    },
+    kick: {
+        osc: 'sine',
+        vol: 0.75,
+        env: { a: 0, d: 0.16, s: 0, r: 0.03 },
+        sweep: { semis: -24, time: 0.07 },
+        pitch: 52,
+    },
+    snare: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.35,
+        env: { a: 0, d: 0.12, s: 0, r: 0.04 },
+        filter: { type: 'bandpass', freq: 1800, q: 0.8 },
+        reverb: 0.15,
+    },
+    hat: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.1,
+        env: { a: 0, d: 0.03, s: 0, r: 0.012 },
+        filter: { type: 'highpass', freq: 6500 },
+    },
+    openhat: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.09,
+        env: { a: 0, d: 0.18, s: 0, r: 0.06 },
+        filter: { type: 'highpass', freq: 5500 },
+    },
+    crash: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.18,
+        env: { a: 0, d: 0.9, s: 0, r: 0.3 },
+        filter: { type: 'highpass', freq: 4000 },
+        reverb: 0.3,
+    },
+    tom: { osc: 'sine', vol: 0.55, env: { a: 0, d: 0.18, s: 0, r: 0.05 }, sweep: { semis: -7, time: 0.15 } },
+    shaker: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.08,
+        env: { a: 0.005, d: 0.04, s: 0, r: 0.01 },
+        filter: { type: 'highpass', freq: 8000 },
+    },
+    // a pure sine under the bass register, felt more than heard; play it in octave 1 or 2
+    sub: { osc: 'sine', vol: 0.7, env: { a: 0.01, d: 0.2, s: 0.85, r: 0.12 } },
+    clap: {
+        osc: 'noise',
+        noise: 'white',
+        vol: 0.3,
+        env: { a: 0.002, d: 0.14, s: 0, r: 0.06 },
+        filter: { type: 'bandpass', freq: 1200, q: 1.4 },
+        reverb: 0.3,
+    },
+} satisfies Record<string, InstrumentDef>
+
+/** the drum kit letters most songs use */
+export const KIT = { k: 'kick', s: 'snare', h: 'hat', o: 'openhat', c: 'crash', x: 'shaker' }