polyphon 0.0.0-stage → 0.1.0

package/src/instruments/play.ts

@@ -0,0 +1,151 @@
+// Play one note on any instrument: a cached sample, a bowed sample with a looping sustain, or a live voice.
+
+import { DESKS } from './bowed.ts';
+import { midiToFrequency, type SampledInstrument } from './definition.ts';
+import { getInstrument } from './registry.ts';
+import { getSample, hasSample, loopOf, sampleMidi } from './samples.ts';
+
+export interface NoteCall {
+  ctx: BaseAudioContext;
+  out: AudioNode;
+  /** Start time (context seconds) */
+  t: number;
+  /** Held length (seconds) */
+  dur: number;
+  /** MIDI pitch (0 for unpitched drums) */
+  m: number;
+  /** 0-1 */
+  vel: number;
+  /** Glides: [seconds after the start, target MIDI pitch] */
+  bends?: [number, number][];
+  /** The track's instrument parameters */
+  params?: Readonly<Record<string, number>>;
+  /** Bowed strings: the desk (players) of the track, 0 for the first (see deskList in compile.ts) */
+  desk?: number;
+}
+
+/** Play one note */
+export function playNote(name: string, c: NoteCall): void {
+  const def = getInstrument(name);
+  const amp = Math.pow(c.vel, 1.4) * def.level;
+  if (def.kind === 'live') {
+    def.voice({ ctx: c.ctx, out: c.out, t: c.t, dur: c.dur, f: midiToFrequency(c.m), vel: amp, touch: c.vel, bends: c.bends?.map(([at, m]) => [at, midiToFrequency(m)]), o: c.params ?? {} });
+    return;
+  }
+  if (def.bow) {
+    playBow(def, name, c, amp);
+    return;
+  }
+  const variant = Math.floor(Math.random() * (def.variants ?? 1));
+  const b = getSample(c.ctx, def, name, c.m, variant);
+  const src = c.ctx.createBufferSource();
+  src.buffer = b;
+  // A fixed-pitch drum given a different note is tuned by changing the playback rate (taiko, tom and others are already rendered by pitch and never reach here)
+  if (def.fixed !== undefined && c.m && c.m !== def.fixed && (c.params?.tune ?? 0) > 0) src.playbackRate.value = Math.pow(2, (c.m - def.fixed) / 12);
+  const g = c.ctx.createGain();
+  if (def.loop) {
+    src.loop = true;
+    const a = c.params?.attack ?? 1.5;
+    const r = c.params?.release ?? 1.5;
+    g.gain.setValueAtTime(0, c.t);
+    g.gain.linearRampToValueAtTime(amp, c.t + a);
+    g.gain.setValueAtTime(amp, c.t + Math.max(a, c.dur));
+    g.gain.linearRampToValueAtTime(0, c.t + Math.max(a, c.dur) + r);
+    src.connect(g).connect(c.out);
+    src.start(c.t, (c.t * 7.3) % b.duration);
+    src.stop(c.t + Math.max(a, c.dur) + r + 0.05);
+    return;
+  }
+  g.gain.value = amp;
+  if (def.choke) choke(c, def.choke, g.gain);
+  let out: AudioNode = c.out;
+  if (def.spread) {
+    const pan = c.ctx.createStereoPanner();
+    pan.pan.value = Math.max(-1, Math.min(1, (c.m - 64) / 36)) * def.spread;
+    pan.connect(c.out);
+    out = pan;
+  }
+  if (def.tone) {
+    const lp = c.ctx.createBiquadFilter();
+    lp.type = 'lowpass';
+    lp.frequency.value = Math.min(c.ctx.sampleRate * 0.45, def.tone(c.m, c.vel));
+    // The Web Audio low-pass Q is the resonance in decibels: -3 dB is roughly Butterworth, with no nasal tone
+    lp.Q.value = -3;
+    src.connect(lp).connect(g).connect(out);
+  } else src.connect(g).connect(out);
+  src.start(c.t);
+  const r = c.params?.release ?? def.damper?.(c.m) ?? def.release ?? 0.2;
+  if (def.hold === 'damp' && !(c.params?.ring ?? 0) && r !== Infinity) {
+    const off = c.t + Math.max(def.minHold ?? 0.03, c.dur);
+    g.gain.setValueAtTime(amp, off);
+    if (def.afterRing) {
+      // The damper stops the string quickly, but a faint ring stays a moment longer
+      const [level, fade] = def.afterRing;
+      g.gain.setTargetAtTime(amp * level, off, r / 4);
+      g.gain.setTargetAtTime(1e-4, off + r, fade / 6.9);
+      src.stop(Math.min(off + r + fade, c.t + b.duration));
+    } else {
+      g.gain.setTargetAtTime(1e-4, off, r / 4);
+      src.stop(Math.min(off + r * 1.5, c.t + b.duration));
+    }
+  } else src.stop(c.t + b.duration);
+}
+
+/** The gain of the note last started in each choke group, per audio context */
+const chokeGroups = new WeakMap<BaseAudioContext, Map<string, AudioParam>>();
+
+/** Cut off the note still ringing in a choke group as this one starts (notes are scheduled in time order), and make this one the group's */
+function choke(c: NoteCall, group: string, gain: AudioParam): void {
+  let groups = chokeGroups.get(c.ctx);
+  if (!groups) chokeGroups.set(c.ctx, (groups = new Map()));
+  const ringing = groups.get(group);
+  if (ringing) {
+    // The target of setTargetAtTime cannot be 0 (some implementations diverge): fade toward silence, then close
+    ringing.cancelScheduledValues(c.t);
+    ringing.setTargetAtTime(1e-4, c.t, 0.004);
+    ringing.setValueAtTime(0, c.t + 0.04);
+  }
+  groups.set(group, gain);
+}
+
+/** Bowed strings: pick the soft or hard layer, make up pitch with a rate change, loop the sustain section, and lift the bow when the note ends */
+function playBow(def: SampledInstrument, name: string, c: NoteCall, amp: number): void {
+  const bw = def.bow!;
+  const o = c.params ?? {};
+  let loud = c.vel * (o.bright ?? 1) > bw.loudAt ? 1 : 0;
+  const root = sampleMidi(def, c.m);
+  // If this layer is not prepared but the other one is: use the other for now, rather than rendering during playback (that would stall);
+  // a desk with neither prepared borrows the first desk's players
+  const has = (layer: number, desk: number) => hasSample(c.ctx.sampleRate, def, name, c.m, layer, desk);
+  const seat = DESKS[(c.desk ?? 0) % DESKS.length];
+  let desk = DESKS.indexOf(seat);
+  if (desk && !has(0, desk) && !has(1, desk) && (has(0, 0) || has(1, 0))) desk = 0;
+  if (!has(loud, desk) && has(1 - loud, desk)) loud = 1 - loud;
+  const b = getSample(c.ctx, def, name, c.m, loud, desk);
+  const src = c.ctx.createBufferSource();
+  src.buffer = b;
+  const lp = loopOf(b);
+  if (lp) {
+    src.loop = true;
+    src.loopStart = lp[0];
+    src.loopEnd = lp[1];
+  }
+  const rate = src.playbackRate;
+  rate.setValueAtTime(Math.pow(2, (c.m - root) / 12), c.t);
+  const glide = o.glide ?? bw.glide;
+  if (c.bends) for (const [at, m] of c.bends) rate.setTargetAtTime(Math.pow(2, (m - root) / 12), c.t + at, glide / 3);
+  const a = Math.max(0.005, o.attack ?? bw.attack);
+  const r = o.release ?? bw.release;
+  const off = c.t + Math.max(c.dur, 0.06);
+  // A desk after the first lands its bow a little behind the first desk's, by a different amount every note; it lifts it with the others
+  const t = c.t + (seat.lag && seat.lag * (0.5 + Math.random()));
+  const g = c.ctx.createGain();
+  const p = g.gain;
+  p.setValueAtTime(0, t);
+  p.linearRampToValueAtTime(amp, t + Math.min(a, Math.max(0.005, off - t)));
+  p.setValueAtTime(amp, off);
+  p.setTargetAtTime(1e-4, off, r / 4);
+  src.connect(g).connect(c.out);
+  src.start(t);
+  src.stop(off + r * 1.6 + 0.02);
+}

package/src/instruments/registry.ts

@@ -0,0 +1,100 @@
+// The instrument registry: every name a track can use, built-in or registered by the application.
+
+import { BUILT_IN, type BuiltInInstrument } from './builtin.ts';
+import type { InstrumentDef } from './definition.ts';
+import { forgetSamples } from './samples.ts';
+
+/** An instrument name. Built-in names autocomplete; any registered name is accepted too. */
+export type InstrumentName = BuiltInInstrument | (string & {});
+
+/** One note handed to a custom synthesized instrument */
+export interface SynthNote {
+  context: BaseAudioContext;
+  /** Connect the note's output here */
+  destination: AudioNode;
+  /** Start time (context seconds) */
+  time: number;
+  /** How long the note is held (seconds); the release comes after this */
+  duration: number;
+  /** Frequency (Hz) */
+  frequency: number;
+  /** Loudness 0-1, already shaped by the instrument's level */
+  velocity: number;
+  /** Glides: [seconds after the start, target frequency in Hz] */
+  glides: [number, number][];
+  /** The track's `params`, for instrument-specific settings */
+  params: Readonly<Record<string, number>>;
+}
+
+/** A custom instrument rendered offline, once per pitch, then played back from a buffer */
+export interface CustomSampledInstrument {
+  /** Render one note: mono, or [left, right] */
+  render(sampleRate: number, midi: number): Float32Array | [Float32Array, Float32Array];
+  /** 'ring' (default) plays the whole sample; 'damp' fades it out `release` seconds after the note ends */
+  sustain?: 'ring' | 'damp';
+  /** Release time in seconds for 'damp' (default 0.2) */
+  release?: number;
+  /** Output level (default 1) */
+  level?: number;
+}
+
+/** A custom instrument synthesized live, note by note */
+export interface CustomSynthInstrument {
+  /** Build the Web Audio graph for one note */
+  play(note: SynthNote): void;
+  /** Output level (default 1) */
+  level?: number;
+  /** Supports glides between notes (the `>` marker in a melody) */
+  glide?: boolean;
+}
+
+export type CustomInstrument = CustomSampledInstrument | CustomSynthInstrument;
+
+const registry = new Map<string, InstrumentDef>(Object.entries(BUILT_IN));
+
+/**
+ * Add an instrument (or replace one) under a name tracks can use.
+ *
+ * @example
+ * registerInstrument('beep', {
+ *   play({ context, destination, time, duration, frequency, velocity }) {
+ *     const osc = new OscillatorNode(context, { type: 'square', frequency });
+ *     const amp = new GainNode(context, { gain: velocity * 0.2 });
+ *     osc.connect(amp).connect(destination);
+ *     osc.start(time);
+ *     osc.stop(time + duration);
+ *   },
+ * });
+ */
+export function registerInstrument(name: string, instrument: CustomInstrument): void {
+  forgetSamples(name);
+  if ('play' in instrument) {
+    registry.set(name, {
+      kind: 'live',
+      level: instrument.level ?? 1,
+      glide: instrument.glide ?? false,
+      voice: (c) =>
+        instrument.play({ context: c.ctx, destination: c.out, time: c.t, duration: c.dur, frequency: c.f, velocity: c.vel, glides: c.bends ?? [], params: c.o }),
+    });
+  } else {
+    registry.set(name, {
+      kind: 'sample',
+      render: (sampleRate, midi) => instrument.render(sampleRate, midi),
+      hold: instrument.sustain ?? 'ring',
+      release: instrument.release ?? 0.2,
+      level: instrument.level ?? 1,
+    });
+  }
+}
+
+/** Every instrument name currently available */
+export function instrumentNames(): string[] {
+  return [...registry.keys()];
+}
+
+/** Look up an instrument; throws a helpful error for unknown names */
+export function getInstrument(name: string): InstrumentDef {
+  const def = registry.get(name);
+  if (!def) throw new Error(`Unknown instrument "${name}". Available: ${instrumentNames().join(', ')}`);
+  return def;
+}

package/src/instruments/samples.ts

@@ -0,0 +1,119 @@
+// Sample cache: sampled instruments are rendered once per (sample rate, instrument, pitch, variant) and reused.
+// Rendering happens before a song starts (prepareSamples), in small slices so the main thread never stalls.
+
+import type { SampledInstrument } from './definition.ts';
+
+/** A sample a song needs rendered before it plays */
+export interface SampleRequest {
+  def: SampledInstrument;
+  name: string;
+  midi: number;
+  /** Only this layer (bowed strings pick soft or hard by velocity) */
+  layer?: number;
+  /** Bowed strings: the desk (players) of the track that plays it, 0 for the first */
+  desk?: number;
+}
+
+const cache = new Map<string, AudioBuffer>();
+/** Loop section of a bowed-string sample (seconds) */
+const loops = new WeakMap<AudioBuffer, [number, number]>();
+
+/** Bowed samples share a cache entry when one instrument borrows another's players (strPad uses strings) */
+const sampleName = (def: SampledInstrument, name: string) => def.bow?.name ?? name;
+const keyOf = (sampleRate: number, name: string, midi: number, variant: number, desk: number) => `${sampleRate}|${name}|${midi}|${variant}${desk ? `|${desk}` : ''}`;
+
+/** The pitch actually rendered: bowed strings sample every few semitones, fixed-pitch drums always use one note */
+export function sampleMidi(def: SampledInstrument, midi: number): number {
+  if (def.bow) return Math.round(midi / def.bow.zone) * def.bow.zone;
+  return def.fixed ?? Math.round(midi);
+}
+
+/** How much memory bowed-string samples may take at most (bytes): beyond that the least recently used are dropped (notes already playing still hold a reference, so they are unaffected) */
+const BOW_BUDGET = 48e6;
+const bowUse = new Map<string, number>();
+let bowBytes = 0;
+function keepBow(key: string, buffer: AudioBuffer): void {
+  if (!bowUse.has(key)) bowBytes += buffer.length * 4;
+  bowUse.delete(key);
+  bowUse.set(key, buffer.length * 4);
+  for (const [old, n] of bowUse) {
+    if (bowBytes <= BOW_BUDGET) break;
+    bowUse.delete(old);
+    cache.delete(old);
+    bowBytes -= n;
+  }
+}
+
+/** Which layer a bowed string uses at this velocity (times params.bright); near the threshold both layers are prepared (velocity has a little randomness at playback) */
+export function bowLayers(def: SampledInstrument, velocity: number, bright = 1): number[] {
+  const x = velocity * bright;
+  const at = def.bow!.loudAt;
+  if (Math.abs(x - at) < 0.06) return [0, 1];
+  return [x > at ? 1 : 0];
+}
+
+/** How many variants of a sampled instrument to precompute (random variants for drums; the soft and hard layers for bowed strings) */
+export const variantsOf = (def: SampledInstrument): number => (def.bow ? 2 : (def.variants ?? 1));
+
+/** Only bowed strings have desks (different players for tracks that share an instrument) */
+const deskOf = (def: SampledInstrument, desk: number) => (def.bow ? desk : 0);
+
+/** Whether a sample is already rendered */
+export function hasSample(sampleRate: number, def: SampledInstrument, name: string, midi: number, variant: number, desk = 0): boolean {
+  return cache.has(keyOf(sampleRate, sampleName(def, name), sampleMidi(def, midi), variant, deskOf(def, desk)));
+}
+
+/** The loop section (seconds) of a bowed sample, if it has one */
+export const loopOf = (buffer: AudioBuffer): [number, number] | undefined => loops.get(buffer);
+
+/** Render (or fetch from the cache) a sample */
+export function getSample(ctx: BaseAudioContext, def: SampledInstrument, name: string, midi: number, variant = 0, desk = 0): AudioBuffer {
+  const mm = sampleMidi(def, midi);
+  const v = variant % variantsOf(def);
+  const dk = deskOf(def, desk);
+  const k = keyOf(ctx.sampleRate, sampleName(def, name), mm, v, dk);
+  let b = cache.get(k);
+  if (!b) {
+    const sr = def.bow ? Math.round(ctx.sampleRate * def.bow.rate) : ctx.sampleRate;
+    const data = def.render(sr, mm, v, dk);
+    const chans = data instanceof Float32Array ? [data] : Array.isArray(data) ? data : [data.data];
+    // One NaN would circulate through the reverb and delay feedback and silence the whole mix for good
+    for (const d of chans) for (let i = 0; i < d.length; i++) if (!Number.isFinite(d[i])) d[i] = 0;
+    b = ctx.createBuffer(chans.length, chans[0].length, sr);
+    chans.forEach((d, i) => b!.getChannelData(i).set(d));
+    if (!(data instanceof Float32Array) && !Array.isArray(data)) loops.set(b, [data.loop[0] / sr, data.loop[1] / sr]);
+    cache.set(k, b);
+  }
+  if (def.bow) keepBow(k, b);
+  return b;
+}
+
+/** Drop every cached sample of an instrument (after it is redefined) */
+export function forgetSamples(name: string): void {
+  for (const k of [...cache.keys()]) if (k.split('|')[1] === name) cache.delete(k);
+}
+
+/** Every [variant] of a need that should be rendered */
+function* variantsToRender(def: SampledInstrument, layer: number | undefined): Generator<number> {
+  for (let v = 0; v < variantsOf(def); v++) if (layer === undefined || v === layer) yield v;
+}
+
+/** Render samples ahead of time; after more than 12 ms of continuous work, yield the main thread for a moment (so the screen does not stall) */
+export async function prepareSamples(ctx: BaseAudioContext, requests: Iterable<SampleRequest>): Promise<void> {
+  let last = performance.now();
+  for (const { def, name, midi, layer, desk } of requests) {
+    for (const v of variantsToRender(def, layer)) {
+      if (hasSample(ctx.sampleRate, def, name, midi, v, desk)) continue;
+      getSample(ctx, def, name, midi, v, desk);
+      if (performance.now() - last > 12) {
+        await new Promise((r) => setTimeout(r, 0));
+        last = performance.now();
+      }
+    }
+  }
+}
+
+/** Synchronous version (offline rendering, short play-once jingles) */
+export function prepareSamplesSync(ctx: BaseAudioContext, requests: Iterable<SampleRequest>): void {
+  for (const { def, name, midi, layer, desk } of requests) for (const v of variantsToRender(def, layer)) getSample(ctx, def, name, midi, v, desk);
+}