@hraness/dawg 0.6.0 → 0.6.1

package/src/audio/effects/gaze.ts

@@ -0,0 +1,354 @@
+/**
+ * Shoegaze stages (0.6.1): wobble, bloom, swell (mono, after the cab) and
+ * double (stereo, right after pan). Ported from the guitar design lane's
+ * prototype (proto/guitar/rig.ts wobbleCurve, addFeedback, applySwell,
+ * applyDouble).
+ *
+ * - wobble: a held tremolo arm (the "glide guitar" of Kevin Shields). One
+ *   seeded curve per track in render time bends the whole voice sum
+ *   together. The voice is read through a moving, non-causal delay whose
+ *   slope is the pitch ratio, so a sine of peak `depth` cents is exact.
+ * - bloom: feedback. The highest note held past `delay` grows a partial at
+ *   `harm` × f0 with a slow seeded drift of a few cents (one seed per
+ *   note id), the way a loud amp makes the top note sing.
+ * - swell: a Slow Gear style volume swell; the gain resets at each onset
+ *   cluster and rises over `time`.
+ * - double: automatic double tracking. A second take is the input delayed
+ *   `time` ms with a seeded wander of ± `drift` ms and a darker tilt,
+ *   spread against the dry take by `width`.
+ *
+ * Every random number comes from the track id (and note id), so a render
+ * is byte-identical on every run.
+ */
+import type { FxValues } from "../../../core/fx.ts";
+import type { Track } from "../../../core/score.ts";
+import { seededRandom } from "../dsp/rng.ts";
+import { OnePole } from "../dsp/filters.ts";
+import {
+  CONTROL_SAMPLES,
+  clamp,
+  fxReader,
+  type EffectContext,
+  type EffectNote,
+} from "./common.ts";
+
+const CENTS_TO_LOG = Math.LN2 / 1200;
+
+/** Catmull-Rom (4-point Hermite) read of `x` at a fractional position. */
+function readAt(x: Float64Array, position: number): number {
+  const last = x.length - 1;
+  if (last < 0) return 0;
+  const p = clamp(position, 0, last);
+  const i = Math.floor(p);
+  const t = p - i;
+  const a = x[Math.max(0, i - 1)]!;
+  const b = x[i]!;
+  const c = x[Math.min(last, i + 1)]!;
+  const d = x[Math.min(last, i + 2)]!;
+  const c1 = 0.5 * (c - a);
+  const c2 = a - 2.5 * b + 2 * c - 0.5 * d;
+  const c3 = 0.5 * (d - a) + 1.5 * (b - c);
+  return ((c3 * t + c2) * t + c1) * t + b;
+}
+
+export type WobbleShape = Readonly<{
+  /** Read offset in seconds at time t (positive: earlier audio). */
+  offset: (t: number) => number;
+  /** Pitch deviation in cents at time t. */
+  cents: (t: number) => number;
+  /** Largest possible |offset| in seconds (the components' summed amplitude). */
+  span: number;
+}>;
+
+/**
+ * Most a wobble moves a note in time, in seconds. Slow, deep settings
+ * (100 c at 0.05 Hz) would otherwise drag strums 170 ms off the grid; past
+ * this bound the depth gives way instead.
+ */
+export const WOBBLE_MAX_OFFSET = 0.015;
+
+/**
+ * The track's wobble curve: three seeded sines (the first at `rate`, the
+ * others off-ratio) weighted by `drift`. Each component's delay amplitude
+ * is chosen so its pitch contribution peaks at its share of `depth`.
+ */
+export function wobbleShape(
+  depth: number,
+  rate: number,
+  drift: number,
+  seed: string,
+): WobbleShape {
+  const r = seededRandom(`wobble:${seed}`);
+  const phase = [r(), r(), r()].map((x) => x * 2 * Math.PI);
+  const ratio = [1, 0.61 + 0.1 * r(), 1.53 + 0.2 * r()];
+  const d = clamp(drift, 0, 1);
+  const weight = [1 - d, 0.6 * d, 0.4 * d];
+  const norm = weight[0]! + weight[1]! + weight[2]!;
+  const hz = ratio.map((k) => Math.max(0.01, rate) * k);
+  // Delay amplitude (s) whose derivative peaks at the component's cents.
+  const amp = hz.map(
+    (f, k) => ((weight[k]! / norm) * depth * CENTS_TO_LOG) / (2 * Math.PI * f),
+  );
+  return {
+    span: amp[0]! + amp[1]! + amp[2]!,
+    // Reading at t + offset(t): ratio = 1 + offset'(t) ≈ 2^(cents/1200).
+    offset: (t) => {
+      let s = 0;
+      for (let k = 0; k < 3; k += 1)
+        s += amp[k]! * Math.sin(2 * Math.PI * hz[k]! * t + phase[k]!);
+      return s;
+    },
+    cents: (t) => {
+      let s = 0;
+      for (let k = 0; k < 3; k += 1)
+        s +=
+          amp[k]! *
+          2 *
+          Math.PI *
+          hz[k]! *
+          Math.cos(2 * Math.PI * hz[k]! * t + phase[k]!);
+      return s / CENTS_TO_LOG;
+    },
+  };
+}
+
+export function applyWobble(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "wobble", values, context);
+  const depth = read.param("depth");
+  const rate = read.number("rate");
+  const drift = read.number("drift");
+  const sr = context.sampleRate;
+  const peak = depth.automated ? 100 : depth.at(0);
+  if (peak <= 0 || buffer.length === 0) return;
+  // Unit-depth shape, scaled by the (possibly automated) depth.
+  const shape = wobbleShape(1, rate, drift, track.id);
+  // Depth that keeps every read within WOBBLE_MAX_OFFSET of the grid.
+  const most = shape.span > 0 ? WOBBLE_MAX_OFFSET / shape.span : Infinity;
+  const source = buffer.slice();
+  let scale = Math.min(most, depth.at(0));
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (depth.automated && index % CONTROL_SAMPLES === 0)
+      scale = Math.min(most, depth.at(index));
+    const t = index / sr;
+    buffer[index] = readAt(source, index + scale * shape.offset(t) * sr);
+  }
+}
+
+/**
+ * Feedback bloom. Only the highest note sounding at once feeds back (one
+ * dominant loop), and only once it has been held past `delay`. One sweep:
+ * the dominant note is found per 32-sample block from the sorted note
+ * starts and a small active set, and a hand-over crossfades 20 ms, so the
+ * cost is O(samples + notes log notes) even on a dense strum.
+ *
+ * The partial feeds back from the signal itself: its level follows an
+ * envelope of the incoming buffer (50 ms attack, `time` release), so a
+ * quiet, faded or muted track blooms quietly or not at all, and the
+ * partial never sits more than about -6 dB under the input's peak.
+ */
+export function applyBloom(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const notes = context.notes;
+  if (!notes || notes.length === 0) return;
+  const read = fxReader(track, "bloom", values, context);
+  const amount = read.number("amount");
+  if (amount <= 0) return;
+  const harm = read.number("harm");
+  const sr = context.sampleRate;
+  const delay = Math.round(read.number("delay") * sr);
+  const grow = Math.max(0.05, read.number("time"));
+  const release = Math.round(0.08 * sr);
+  const fade = Math.max(1, Math.round(0.02 * sr));
+  // Envelope (peak-equivalent of a smoothed RMS) of the input.
+  const follow = new Float64Array(buffer.length);
+  const up = 1 - Math.exp(-1 / (0.05 * sr));
+  const down = 1 - Math.exp(-1 / (Math.max(0.1, grow) * sr));
+  let power = 0;
+  for (let index = 0; index < buffer.length; index += 1) {
+    const x2 = buffer[index]! * buffer[index]!;
+    power += (x2 > power ? up : down) * (x2 - power);
+    follow[index] = Math.sqrt(2 * power);
+  }
+  const sorted = notes
+    .filter((note) => note.length > delay)
+    .sort((x, y) => x.start - y.start || y.hz - x.hz);
+  type Loop = {
+    note: EffectNote;
+    phase: number;
+    driftHz: number;
+    level: number;
+    /** Hand-over gain 0..1 and its direction. */
+    gain: number;
+    rising: boolean;
+  };
+  const loops: Loop[] = [];
+  const active: EffectNote[] = [];
+  let next = 0;
+  let current: EffectNote | undefined;
+  for (let block = 0; block < buffer.length; block += BLOCK) {
+    while (next < sorted.length && sorted[next]!.start <= block)
+      active.push(sorted[next++]!);
+    for (let k = active.length - 1; k >= 0; k -= 1)
+      if (active[k]!.start + active[k]!.length <= block) active.splice(k, 1);
+    let top: EffectNote | undefined;
+    for (const note of active)
+      if (note.start + delay <= block && (!top || note.hz > top.hz)) top = note;
+    if (top !== current) {
+      for (const loop of loops) if (loop.note !== top) loop.rising = false;
+      if (top && !loops.some((loop) => loop.note === top)) {
+        const r = seededRandom(`bloom:${track.id}:${top.id}`);
+        loops.push({
+          note: top,
+          phase: r() * 2 * Math.PI,
+          driftHz: 0.2 + 0.3 * r(),
+          // Relative to the input envelope; at most -6 dB under it.
+          level: Math.min(0.5, 0.6 * amount * (0.5 + 0.5 * top.velocity)),
+          gain: current ? 0 : 1,
+          rising: true,
+        });
+      }
+      current = top;
+    }
+    const end = Math.min(buffer.length, block + BLOCK);
+    for (let k = loops.length - 1; k >= 0; k -= 1) {
+      const loop = loops[k]!;
+      const from = loop.note.start + delay;
+      const off = loop.note.start + loop.note.length;
+      for (let index = block; index < end; index += 1) {
+        const t = (index - from) / sr;
+        const cents = 3 * Math.sin(2 * Math.PI * loop.driftHz * t);
+        loop.phase +=
+          (2 * Math.PI * harm * loop.note.hz * 2 ** (cents / 1200)) / sr;
+        loop.gain = loop.rising
+          ? Math.min(1, loop.gain + 1 / fade)
+          : Math.max(0, loop.gain - 1 / fade);
+        let env =
+          follow[index]! * loop.level * loop.gain * (1 - Math.exp(-t / grow));
+        if (index > off) env *= Math.max(0, 1 - (index - off) / release);
+        buffer[index]! += env * Math.sin(loop.phase);
+      }
+      if (loop.gain <= 0 || end > off + release) {
+        loops.splice(k, 1);
+        if (current === loop.note) current = undefined;
+      }
+    }
+  }
+}
+
+/** Control block of the bloom sweep, in samples. */
+const BLOCK = 32;
+
+/** Onset clusters (notes within 40 ms of the cluster's first), sorted. */
+function onsets(notes: readonly EffectNote[], sr: number): number[] {
+  const gap = 0.04 * sr;
+  const out: number[] = [];
+  for (const start of notes.map((note) => note.start).sort((a, b) => a - b))
+    if (out.length === 0 || start - out[out.length - 1]! > gap) out.push(start);
+  return out;
+}
+
+export function applySwell(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const notes = context.notes;
+  if (!notes || notes.length === 0) return;
+  const read = fxReader(track, "swell", values, context);
+  const mix = read.param("mix");
+  const sr = context.sampleRate;
+  // Reaches about -0.4 dB at `time`.
+  const tau = (Math.max(0.01, read.number("time")) / 3) * sr;
+  // A new onset over a ringing chord first ducks the gain to 0 over at
+  // most `duck` (scaled by how high it was), then rises again: no click.
+  const duck = 0.006 * sr;
+  const starts = onsets(notes, sr);
+  let next = 0;
+  let last = Number.NEGATIVE_INFINITY;
+  let g = 1;
+  let from = 0;
+  let fall = 0;
+  let wet = mix.at(0);
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (mix.automated && index % CONTROL_SAMPLES === 0) wet = mix.at(index);
+    while (next < starts.length && starts[next]! <= index) {
+      // Before the first onset nothing sounds: rise from silence.
+      from = last === Number.NEGATIVE_INFINITY ? 0 : g;
+      fall = Math.round(duck * from);
+      last = starts[next++]!;
+    }
+    if (last !== Number.NEGATIVE_INFINITY) {
+      const elapsed = index - last;
+      g =
+        elapsed < fall
+          ? from * (1 - elapsed / fall)
+          : 1 - Math.exp(-(elapsed - fall) / tau);
+    }
+    buffer[index] = buffer[index]! * (1 - wet + wet * g * g);
+  }
+}
+
+/** Seeded wandering delay of one channel, read non-causally from `x`. */
+function secondTake(
+  x: Float64Array,
+  time: number,
+  drift: number,
+  seed: string,
+  sr: number,
+): Float64Array {
+  const r = seededRandom(`double:${seed}`);
+  const ph1 = r() * 2 * Math.PI;
+  const ph2 = r() * 2 * Math.PI;
+  const f1 = 0.35 + 0.3 * r();
+  const f2 = 0.11 + 0.1 * r();
+  const tilt = new OnePole(5500, sr);
+  const out = new Float64Array(x.length);
+  let d = (time / 1000) * sr;
+  for (let index = 0; index < x.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      const t = index / sr;
+      const wander =
+        0.65 * Math.sin(2 * Math.PI * f1 * t + ph1) +
+        0.35 * Math.sin(2 * Math.PI * f2 * t + ph2);
+      d = ((time + drift * wander) / 1000) * sr;
+    }
+    const position = index - d;
+    out[index] = tilt.process(position < 0 ? 0 : readAt(x, position));
+  }
+  return out;
+}
+
+export function applyDouble(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "double", values, context);
+  const time = read.number("time");
+  const drift = read.number("drift");
+  const width = clamp(read.number("width"), 0, 1);
+  const sr = context.sampleRate;
+  const copyL = secondTake(left, time, drift, track.id, sr);
+  const copyR = secondTake(right, time, drift, track.id, sr);
+  for (let index = 0; index < left.length; index += 1) {
+    const l = left[index]!;
+    const r = right[index]!;
+    const cl = copyL[index]!;
+    const cr = copyR[index]!;
+    // width 1: the dry take left, the second take right; 0: both centred.
+    left[index] = 0.5 * (l + cl) + 0.5 * width * (l - cl);
+    right[index] = 0.5 * (r + cr) - 0.5 * width * (r - cr);
+  }
+}

package/src/audio/engine.ts

@@ -9,6 +9,7 @@ import {
   type ClickLevel,
 } from "./click.ts";
 import type { LiveNotePcm } from "./live.ts";
+import { RING_OUT_FADE_SECONDS } from "./instruments.ts";
 import { measureLoudness, pcmChannels } from "./loudness.ts";
 import type { MasterReport } from "./master.ts";
 import { levelOf, type SoundLevel } from "./preview.ts";
@@ -308,8 +309,16 @@ type LiveVoice = {
   /** Fade-out frames left once released early; undefined while sounding. */
   fadeLeft: number | undefined;
   fadeFrames: number;
+  /** Rings to its end on note-off (0.6.1 modal ring-out). */
+  ringOut?: boolean;
 };
 
+/**
+ * At most this many ring-out voices sound at once; the oldest beyond it fades
+ * over `RING_OUT_FADE_SECONDS` (spec 7.3: 32 resonator voices).
+ */
+export const MAX_RING_OUT_VOICES = 32;
+
 type PlayRequest = {
   score: TrackScore;
   beat: number | undefined;
@@ -531,14 +540,18 @@ export class AudioEngine {
       existing.frames = note.frames;
       existing.fadeLeft = undefined;
       existing.fadeFrames = this.releaseFrames(note);
-    } else
+      existing.ringOut = note.ringOut === true;
+    } else {
       this.voices.set(id, {
         pcm: note.pcm,
         frames: note.frames,
         position: 0,
         fadeLeft: undefined,
         fadeFrames: this.releaseFrames(note),
+        ...(note.ringOut ? { ringOut: true } : {}),
       });
+      if (note.ringOut) this.capRingOut();
+    }
     // Write what is due now so the voice joins the very next chunk.
     const first = this.written;
     this.pump();
@@ -553,11 +566,39 @@ export class AudioEngine {
     );
   }
 
-  /** Fade a live voice out over ~10 ms (sustain lifted, mode left). */
-  public noteOff(id: number): void {
+  /**
+   * Past `MAX_RING_OUT_VOICES` ringing voices, fade the oldest still at full
+   * level over `RING_OUT_FADE_SECONDS` (Map order is start order).
+   */
+  private capRingOut(): void {
+    let ringing = 0;
+    for (const voice of this.voices.values())
+      if (voice.ringOut && voice.fadeLeft === undefined) ringing += 1;
+    for (const voice of this.voices.values()) {
+      if (ringing <= MAX_RING_OUT_VOICES) break;
+      if (!voice.ringOut || voice.fadeLeft !== undefined) continue;
+      this.fadeRingOut(voice);
+      ringing -= 1;
+    }
+  }
+
+  private fadeRingOut(voice: LiveVoice): void {
+    voice.fadeFrames = Math.max(
+      1,
+      Math.round(this.sampleRate * RING_OUT_FADE_SECONDS),
+    );
+    voice.fadeLeft = voice.fadeFrames;
+  }
+
+  /**
+   * Fade a live voice out over ~10 ms (sustain lifted, mode left). A
+   * ring-out voice keeps ringing; `noteOff(id, true)` silences it too.
+   */
+  public noteOff(id: number, force = false): void {
     const voice = this.voices.get(id);
-    if (voice && voice.fadeLeft === undefined)
-      voice.fadeLeft = voice.fadeFrames;
+    if (!voice || voice.fadeLeft !== undefined) return;
+    if (!voice.ringOut) voice.fadeLeft = voice.fadeFrames;
+    else if (force) this.fadeRingOut(voice);
   }
 
   /** Frames of live voice `id` already mixed, or undefined once finished. */

package/src/audio/fit.ts

@@ -31,6 +31,7 @@ import {
   sampleAt,
 } from "./dsp/stft.ts";
 import { hermite4 } from "./dsp/interp.ts";
+import { pitchShiftJob } from "./dsp/shift.ts";
 import type { FitMap } from "./warp.ts";
 
 export type FitAlgorithm = "repitch" | "beats" | "tones";
@@ -146,6 +147,50 @@ export function fittedBuffer(
   return out;
 }
 
+/**
+ * Live renders pitch-shift buffers up to this long synchronously; longer
+ * ones run between blocks while the voice plays a repitch. A phase-vocoder
+ * shift with formant keeping costs about 30 ms per second of 22.05 kHz
+ * audio, so only very short sounds fit the 10 ms note-on budget.
+ */
+export const LIVE_SYNC_SHIFT_SECONDS = 0.1;
+
+/**
+ * `buffer` pitch-shifted by `semitones` (formant semitones, 0 keeps),
+ * cached under `key` with the fits (0.6.1 `shift`, `formant`). Returns
+ * undefined only in a live render while a long shift is still running.
+ */
+export function shiftedBuffer(
+  key: string,
+  buffer: Float32Array,
+  sampleRate: number,
+  semitones: number,
+  formant: number | undefined,
+): Float32Array | undefined {
+  const hit = cache.get(key);
+  if (hit) {
+    cache.delete(key);
+    cache.set(key, hit);
+    return hit;
+  }
+  const work = () =>
+    pitchShiftJob(buffer, sampleRate, semitones, {
+      ...(formant === undefined ? {} : { formant }),
+    });
+  if (live && buffer.length > LIVE_SYNC_SHIFT_SECONDS * sampleRate) {
+    missed = true;
+    if (!pending.has(key)) {
+      pending.set(key, { job: work(), window: key });
+      schedule();
+    }
+    return undefined;
+  }
+  pending.delete(key);
+  const out = drain(work());
+  remember(key, out);
+  return out;
+}
+
 function drain(job: Generator<void, Float32Array>): Float32Array {
   for (;;) {
     const step = job.next();