rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/score/pattern.ts

@@ -0,0 +1,91 @@
+// the score's note grammar and its instruments: one token a grid row, an instrument as plain data the synth plays.
+// Pure: no audio here (synth.ts renders)
+
+/** oscillator families: chiptune roots (pulse, wave, noise) plus the smoother modern ones */
+export type Osc = 'pulse' | 'saw' | 'triangle' | 'sine' | 'wave' | 'noise'
+
+export interface InstrumentDef {
+    osc: Osc
+    /** 0..1 */
+    vol: number
+    /** ADSR in seconds, sustain as a 0..1 level */
+    env: { a: number; d: number; s: number; r: number }
+    /** pulse only: duty cycle 0.05..0.95 */
+    duty?: number
+    /** wave only: one cycle of samples in -1..1, any length */
+    wave?: number[]
+    /** pulse, saw and wave: the frequency in Hz above which the harmonics fall away, default 3000; higher is brighter */
+    tone?: number
+    /** noise only: 'white' hiss or 'metal' (short period, pitched) */
+    noise?: 'white' | 'metal'
+    /** detune in cents, and extra unison voices spread by it */
+    detune?: number
+    unison?: number
+    filter?: { type: 'lowpass' | 'highpass' | 'bandpass'; freq: number; q?: number }
+    /** depth in semitones, rate in Hz, delay in seconds from the note start */
+    vibrato?: { delay: number; depth: number; rate: number }
+    /** portamento between consecutive notes, seconds */
+    glide?: number
+    /** -1 left .. 1 right */
+    pan?: number
+    /** 0..1 send to the score's reverb */
+    reverb?: number
+    /** pitch slide from each note start: `semis` over `time` seconds (kicks, toms, zaps) */
+    sweep?: { semis: number; time: number }
+    /** the midi note a drum letter plays this instrument at, default 60 */
+    pitch?: number
+}
+
+// one token a row, whitespace separated, '|' ignored:
+//   C4 C#4 Db4    note (octave 0..8)       .    hold the previous note
+//   -             silence                  k    drum letter (from `drums`)
+// zero length modifiers glued before a row token: `@lead:C4` switches instrument, `v8:C4` sets the volume 0..15
+// (15 = the instrument's vol) from that note on
+type Row = { kind: 'note'; midi: number } | { kind: 'hold' } | { kind: 'off' } | { kind: 'drum'; letter: string }
+
+export interface RowEvent {
+    row: Row
+    instrument?: string
+    vol?: number
+}
+
+const NOTE_RE = /^([A-G])([#b]?)(\d)$/
+const SEMI: Record<string, number> = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 }
+
+export function noteToMidi(token: string): number | null {
+    const m = NOTE_RE.exec(token)
+    if (!m) return null
+    const [, letter, acc, oct] = m
+    const base = SEMI[letter ?? '']
+    if (base === undefined || oct === undefined) return null
+    return 12 * (Number(oct) + 1) + base + (acc === '#' ? 1 : acc === 'b' ? -1 : 0)
+}
+
+export function midiToHz(midi: number): number {
+    return 440 * 2 ** ((midi - 69) / 12)
+}
+
+export function parsePattern(text: string, drums: Record<string, string> = {}): RowEvent[] {
+    const out: RowEvent[] = []
+    for (const raw of text.split(/\s+/)) {
+        if (raw === '' || raw === '|') continue
+        const parts = raw.split(':')
+        const body = parts.pop() ?? ''
+        const ev: RowEvent = { row: { kind: 'off' } }
+        for (const mod of parts) {
+            if (mod.startsWith('@')) ev.instrument = mod.slice(1)
+            else if (/^v\d{1,2}$/.test(mod)) ev.vol = Number(mod.slice(1))
+            else throw new Error(`pattern token "${raw}": unknown modifier "${mod}"`)
+        }
+        if (body === '.') ev.row = { kind: 'hold' }
+        else if (body === '-') ev.row = { kind: 'off' }
+        else if (drums[body] !== undefined) ev.row = { kind: 'drum', letter: body }
+        else {
+            const midi = noteToMidi(body)
+            if (midi === null) throw new Error(`pattern token "${raw}": not a note, a drum letter, '.' or '-'`)
+            ev.row = { kind: 'note', midi }
+        }
+        out.push(ev)
+    }
+    return out
+}

package/src/trailer/score/score.ts

@@ -0,0 +1,214 @@
+// a trailer's score: its `code` block and `play` lines made one module, each section's tracks read in the pattern
+// grammar and timed at the section's own tempo, into the notes the synth plays. A track's instrument, volume and held
+// note carry across sections. The module is loaded synchronously (require), so a check reads every error at its line
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type Score, SCORE_LEAD, type Section, type TrailerError } from '../grammar.ts'
+import { INST } from './palette.ts'
+import { type InstrumentDef, parsePattern, type RowEvent } from './pattern.ts'
+
+export interface ScheduledNote {
+    track: string
+    /** the grid row it starts on, counted over the whole score */
+    row: number
+    rows: number
+    /** null for a drum hit, which plays its instrument's `pitch` */
+    midi: number | null
+    instrument: string
+    /** 0..1, the v modifier times the track volume */
+    vol: number
+    /** the track's note before, for glide */
+    from: number | null
+    /** seconds from the render's start, its lead counted */
+    time: number
+    dur: number
+}
+
+export interface CompiledScore {
+    instruments: Record<string, InstrumentDef>
+    reverb?: { seconds: number; mix: number }
+    /** every note sorted by time */
+    notes: ScheduledNote[]
+    /** the score's length, its lead counted */
+    seconds: number
+    /** where it cuts dead, its lead counted; null: it rings out */
+    stop: number | null
+    /** each section's span in the render, its lead counted */
+    sections: { name: string; at: number; seconds: number; notes: number }[]
+}
+
+const here = import.meta.dir
+// the helpers every `code` block and `play` line reads without importing them
+const PRELUDE = [
+    `import { arp, bass, chart, mel, midiToNote, parseChord, rep, seq, transpose, voice } from ${JSON.stringify(join(here, 'compose.ts'))}`,
+    `import { additive, INST, KIT } from ${JSON.stringify(join(here, 'palette.ts'))}`,
+    "const rest = (n: number): string => Array.from({ length: n }, () => '-').join(' ')",
+    'export const __plays: (() => unknown)[] = []',
+    'const __play = (i: number, f: () => unknown): void => void (__plays[i] = f)',
+]
+
+type Play = Section['plays'][number]
+
+/** the score as one module: the prelude, the code block, each play as a function; `lineOf` maps its lines to the file's */
+export function scoreModule(s: Score, sections: readonly Section[]): { text: string; lineOf: number[]; plays: Play[] } {
+    const out: string[] = []
+    const lineOf: number[] = []
+    const push = (text: string, line: number): void => {
+        out.push(text)
+        lineOf.push(line)
+    }
+    for (const l of PRELUDE) push(l, s.line)
+    // the code's lines from its own line on, the blank ones kept: a template string may hold one
+    for (const [i, l] of (s.code?.text.split('\n') ?? []).entries()) if (i >= (s.code?.line ?? 0)) push(l, i + 1)
+    const plays = sections.flatMap((sec) => sec.plays)
+    plays.forEach((pl, i) => {
+        // a plain quoted string is a melody
+        const expr = /^"[^"\\]*"$/.test(pl.expr) ? `mel(${pl.expr})` : pl.expr
+        const [first, ...more] = expr.split('\n')
+        push(`__play(${i}, () => (${first ?? ''}`, pl.line)
+        for (const [k, l] of more.entries()) push(l, pl.line + 1 + k)
+        push('))', pl.line)
+    })
+    return { text: `${out.join('\n')}\n`, lineOf, plays }
+}
+
+/** the module's line a load error names: a syntax error carries its place, a throw at the top level its stack */
+function errorLine(e: unknown, file: string): number | null {
+    const errs = (e as { errors?: { position?: { line?: number } }[] }).errors
+    const pos = errs?.[0]?.position?.line ?? (e as { position?: { line?: number } }).position?.line
+    if (pos !== undefined) return pos
+    const m = new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:(\\d+)`).exec((e as Error).stack ?? '')
+    return m ? Number(m[1]) : null
+}
+
+const firstLine = (e: unknown): string => {
+    const errs = (e as { errors?: unknown[] }).errors
+    return String(errs?.[0] ?? e).split('\n')[0]!.replace(/^(BuildMessage|Error): /, '')
+}
+
+/** the file a score's module text is kept in */
+export const scoreModuleFile = (text: string, dir: string): string => join(dir, `${Bun.hash(text).toString(36)}.ts`)
+
+/** the score's notes, or every error on its line; `dir` keeps the module files, each named by its text */
+export function compileScore(s: Score, sections: readonly Section[], dir: string): { score: CompiledScore | null; errors: TrailerError[] } {
+    const errors: TrailerError[] = []
+    const { text, lineOf, plays } = scoreModule(s, sections)
+    mkdirSync(dir, { recursive: true })
+    const file = scoreModuleFile(text, dir)
+    if (!existsSync(file)) writeFileSync(file, text)
+    let mod: { instruments?: unknown; __plays: (() => unknown)[] }
+    try {
+        mod = require(file)
+    } catch (e) {
+        const at = errorLine(e, file)
+        const line = at !== null ? (lineOf[at - 1] ?? s.line) : (s.code?.line ?? s.line)
+        return { score: null, errors: [{ line, message: `the score's TypeScript fails: ${firstLine(e)}` }] }
+    }
+    const instruments = mod.instruments ?? INST
+    if (typeof instruments !== 'object' || instruments === null)
+        return { score: null, errors: [{ line: s.code?.line ?? s.line, message: 'the code block\'s instruments is no record: export const instruments = { … }' }] }
+    const inst = instruments as Record<string, InstrumentDef>
+    const names = (): string => Object.keys(inst).join(', ')
+    const values = new Map(plays.map((pl, i) => [pl, mod.__plays[i]]))
+
+    const tracks = s.tracks
+    for (const tr of tracks) if (!inst[tr.instrument]) errors.push({ line: tr.line, message: `track ${tr.name}: no instrument ${tr.instrument} (${names()})` })
+    for (const [letter, name] of Object.entries(s.drums)) if (!inst[name]) errors.push({ line: s.line, message: `drums ${letter}=${name}: no instrument ${name} (${names()})` })
+
+    const state = new Map(tracks.map((tr) => [tr.name, { instrument: tr.instrument, vol: 15, open: null as ScheduledNote | null, prev: null as number | null }]))
+    const notes: ScheduledNote[] = []
+    const spans: CompiledScore['sections'] = []
+    let row0 = 0
+    const close = (st: { open: ScheduledNote | null }, time: number, row: number): void => {
+        if (!st.open) return
+        st.open.dur = time - st.open.time
+        st.open.rows = row - st.open.row
+        st.open = null
+    }
+    for (const sec of sections) {
+        const { bpm, grid, meter } = sec.clock ?? s.clock
+        const rowsExact = (sec.seconds * bpm * grid) / 60
+        const rows = Math.round(rowsExact)
+        const spr = 60 / bpm / grid
+        const bars = (n: number): string => `${+(n / grid / meter).toFixed(3)} bars`
+        const before = notes.length
+        spans.push({ name: sec.name, at: SCORE_LEAD + sec.at, seconds: sec.seconds, notes: 0 })
+        if (Math.abs(rowsExact - rows) > 1e-6) {
+            errors.push({ line: sec.line, message: `section ${sec.name}: ${+sec.seconds.toFixed(4)} s is ${+rowsExact.toFixed(3)} rows of its grid (${grid} a beat), never a whole number` })
+            continue
+        }
+        if (s.stop && sec.at >= s.stop.at - 1e-9 && sec.plays.length > 0) {
+            for (const pl of sec.plays) errors.push({ line: pl.line, message: `play ${pl.track}: section ${sec.name} starts after the score stops (line ${s.stop.line}), so it is never heard` })
+            continue
+        }
+        const drums = { ...s.drums, ...sec.drums }
+        for (const [letter, name] of Object.entries(sec.drums)) if (!inst[name]) errors.push({ line: sec.line, message: `drums ${letter}=${name}: no instrument ${name} (${names()})` })
+        const byTrack = new Map<string, { line: number; text: string }>()
+        for (const pl of sec.plays) {
+            let v: unknown
+            try {
+                v = values.get(pl)?.()
+            } catch (e) {
+                errors.push({ line: pl.line, message: `play ${pl.track}: ${firstLine(e)}` })
+                continue
+            }
+            if (pl.track === '*') {
+                if (typeof v !== 'object' || v === null || Object.values(v).some((x) => typeof x !== 'string')) {
+                    errors.push({ line: pl.line, message: 'play * wants a record of tracks, each its rows as text' })
+                    continue
+                }
+                for (const [k, x] of Object.entries(v as Record<string, string>)) {
+                    if (!state.has(k)) errors.push({ line: pl.line, message: `play *: no track ${k} (${tracks.map((x) => x.name).join(', ')})` })
+                    else if (byTrack.has(k)) errors.push({ line: pl.line, message: `play *: section ${sec.name} already plays ${k}` })
+                    else byTrack.set(k, { line: pl.line, text: x })
+                }
+            } else if (typeof v !== 'string') errors.push({ line: pl.line, message: `play ${pl.track}: wants its rows as text, got ${typeof v}` })
+            else if (byTrack.has(pl.track)) errors.push({ line: pl.line, message: `play ${pl.track}: section ${sec.name} already plays it` })
+            else byTrack.set(pl.track, { line: pl.line, text: v })
+        }
+        for (const tr of tracks) {
+            const st = state.get(tr.name)!
+            const src = byTrack.get(tr.name)
+            let events: RowEvent[]
+            try {
+                events = src ? parsePattern(src.text, drums) : Array.from({ length: rows }, (): RowEvent => ({ row: { kind: 'off' } }))
+            } catch (e) {
+                errors.push({ line: src!.line, message: `play ${tr.name}: ${firstLine(e)}` })
+                continue
+            }
+            if (events.length !== rows) {
+                errors.push({ line: src!.line, message: `play ${tr.name}: ${events.length} rows, ${bars(events.length)}; section ${sec.name} is ${rows} rows, ${bars(rows)}` })
+                continue
+            }
+            events.forEach((ev, r) => {
+                const time = SCORE_LEAD + sec.at + r * spr
+                if (ev.instrument !== undefined) {
+                    if (!inst[ev.instrument]) errors.push({ line: src!.line, message: `play ${tr.name}: no instrument ${ev.instrument} (${names()})` })
+                    st.instrument = ev.instrument
+                }
+                if (ev.vol !== undefined) st.vol = Math.max(0, Math.min(15, ev.vol))
+                const k = ev.row
+                if (k.kind === 'hold') return
+                close(st, time, row0 + r)
+                if (k.kind === 'off') return
+                const vol = (st.vol / 15) * tr.volume
+                if (k.kind === 'drum') st.open = { track: tr.name, row: row0 + r, rows: 1, midi: null, instrument: drums[k.letter] ?? st.instrument, vol, from: null, time, dur: spr }
+                else {
+                    st.open = { track: tr.name, row: row0 + r, rows: 1, midi: k.midi, instrument: st.instrument, vol, from: st.prev, time, dur: spr }
+                    st.prev = k.midi
+                }
+                notes.push(st.open)
+            })
+        }
+        spans.at(-1)!.notes = notes.length - before
+        row0 += rows
+    }
+    const last = sections.at(-1)
+    const seconds = SCORE_LEAD + (last ? last.at + last.seconds : 0)
+    for (const st of state.values()) close(st, seconds, row0)
+    if (errors.length > 0) return { score: null, errors: dedupe(errors) }
+    notes.sort((a, b) => a.time - b.time)
+    return { score: { instruments: inst, ...(s.reverb ? { reverb: s.reverb } : {}), notes, seconds, stop: s.stop ? SCORE_LEAD + s.stop.at : null, sections: spans }, errors: [] }
+}
+
+const dedupe = (es: TrailerError[]): TrailerError[] => [...new Map(es.map((e) => [`${e.line} ${e.message}`, e])).values()]

package/src/trailer/score/sound.ts

@@ -0,0 +1,112 @@
+// a score as a wav in the cache, keyed on its notes, instruments, room and the synth's own code, and what it sounds
+// like as numbers: each section's loudness and peak, since nobody hears a build. Silence under notes refuses
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { CompiledScore } from './score.ts'
+import { HOT, RATE, type Rendered, renderScore } from './synth.ts'
+
+/** the synth's sources: an edit to any renders every score again */
+const SYNTH = ['synth.ts', 'dsp.ts', 'pattern.ts'].map((f) => join(import.meta.dir, f))
+
+export interface Level {
+    name: string
+    /** seconds in the render */
+    at: number
+    seconds: number
+    notes: number
+    /** dBFS, the louder channel */
+    rms: number
+    peak: number
+    /** the share of its samples at the soft ceiling */
+    hot: number
+}
+
+/** below this RMS a section is silence */
+export const SILENT_DB = -60
+/** past this share of samples at the ceiling, a section distorts */
+const HOT_SHARE = 0.002
+
+const db = (x: number): number => (x > 0 ? 20 * Math.log10(x) : -120)
+
+/** each span's RMS, peak and share of samples at the ceiling */
+export function levels(r: Rendered, spans: readonly { name: string; at: number; seconds: number; notes: number }[]): Level[] {
+    return spans.map((s) => {
+        const a = Math.max(0, Math.floor(s.at * r.rate))
+        const b = Math.min(r.left.length, Math.ceil((s.at + s.seconds) * r.rate))
+        const m = spanStats(r.left, r.right, a, b)
+        return { ...s, rms: +db(m.rms).toFixed(1), peak: +db(m.peak).toFixed(1), hot: +m.hot.toFixed(4) }
+    })
+}
+
+function spanStats(l: Float32Array, r: Float32Array, a: number, b: number): { rms: number; peak: number; hot: number } {
+    let sl = 0
+    let sr = 0
+    let peak = 0
+    let hot = 0
+    for (let i = a; i < b; i++) {
+        const x = l[i]!
+        const y = r[i]!
+        sl += x * x
+        sr += y * y
+        const p = Math.max(Math.abs(x), Math.abs(y))
+        if (p > peak) peak = p
+        if (p >= HOT) hot++
+    }
+    const n = Math.max(1, b - a)
+    return { rms: Math.sqrt(Math.max(sl, sr) / n), peak, hot: hot / n }
+}
+
+/** a level as one line; `bad` names what is wrong with it */
+export function levelLine(x: Level): { line: string; bad: 'silent' | 'hot' | null } {
+    const bad = x.notes > 0 && x.rms < SILENT_DB ? 'silent' : x.hot > HOT_SHARE ? 'hot' : null
+    const why = bad === 'silent' ? `: SILENT, ${x.notes} notes nobody hears` : bad === 'hot' ? `: HOT, ${(x.hot * 100).toFixed(1)}% of it at the ceiling, lower the score's volume or its loudest tracks` : ''
+    return { line: `score ${x.name.padEnd(14)} ${x.at.toFixed(2).padStart(6)} s ${x.seconds.toFixed(2).padStart(6)} s  ${String(x.notes).padStart(4)} notes  rms ${x.rms.toFixed(1).padStart(6)} dBFS  peak ${x.peak.toFixed(1).padStart(6)} dBFS${why}`, bad }
+}
+
+/** 16 bit stereo PCM */
+export function wavOf(r: Rendered): Buffer {
+    const n = r.left.length
+    const out = new Int16Array(n * 2)
+    for (let i = 0; i < n; i++) {
+        out[i * 2] = Math.round(Math.max(-1, Math.min(1, r.left[i]!)) * 32767)
+        out[i * 2 + 1] = Math.round(Math.max(-1, Math.min(1, r.right[i]!)) * 32767)
+    }
+    const pcm = Buffer.from(out.buffer)
+    const h = Buffer.alloc(44)
+    h.write('RIFF', 0)
+    h.writeUInt32LE(36 + pcm.length, 4)
+    h.write('WAVEfmt ', 8)
+    h.writeUInt32LE(16, 16)
+    h.writeUInt16LE(1, 20)
+    h.writeUInt16LE(2, 22)
+    h.writeUInt32LE(r.rate, 24)
+    h.writeUInt32LE(r.rate * 4, 28)
+    h.writeUInt16LE(4, 32)
+    h.writeUInt16LE(16, 34)
+    h.write('data', 36)
+    h.writeUInt32LE(pcm.length, 40)
+    return Buffer.concat([h, pcm])
+}
+
+/** the file the score's wav of `seconds` (rounded up) is kept in: its notes, instruments, room and the synth's code */
+export function scoreWavFile(score: CompiledScore, seconds: number, dir: string): string {
+    const h = new Bun.CryptoHasher('sha1').update(JSON.stringify([score.instruments, score.reverb ?? null, score.notes, score.stop, score.sections, Math.ceil(seconds), RATE]))
+    for (const f of SYNTH) h.update(readFileSync(f))
+    return join(dir, `score-${h.digest('hex').slice(0, 16)}.wav`)
+}
+
+/** the score's wav of `seconds` (rounded up) in `dir`, rendered when missing; its levels kept beside it */
+export function scoreWav(score: CompiledScore, seconds: number, dir: string): { file: string; made: boolean; levels: Level[]; ms: number } {
+    const s = Math.ceil(seconds)
+    const file = scoreWavFile(score, seconds, dir)
+    const meta = `${file}.levels.json`
+    if (existsSync(file) && existsSync(meta)) return { file, made: false, levels: JSON.parse(readFileSync(meta, 'utf8')) as Level[], ms: 0 }
+    const t0 = performance.now()
+    const r = renderScore(score, s)
+    const lv = levels(r, score.sections)
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(`${file}.part`, wavOf(r))
+    writeFileSync(meta, JSON.stringify(lv))
+    renameSync(`${file}.part`, file)
+    return { file, made: true, levels: lv, ms: performance.now() - t0 }
+}