@hraness/dawg 0.3.0 → 0.4.1

package/src/audio/effects/convolution.ts

@@ -0,0 +1,339 @@
+/**
+ * Convolution reverb for `reverb.ir` (Strudel `iresponse`/`ir`): the track's
+ * stereo pair, summed to mono, is convolved with a stereo impulse response
+ * by uniformly partitioned overlap-save FFT convolution.
+ *
+ * The impulse is cut into P blocks of B samples; each block's spectrum is
+ * kept once. Every input block is transformed once, multiplied with the
+ * last P input spectra (a frequency-domain delay line) and transformed back,
+ * so the cost per sample is O(P + log B) instead of O(IR length). Left and
+ * right impulses share one transform: G = FFT(hL + i·hR), and because the
+ * input is real, Re(IFFT(X·G)) is the left output and Im(…) the right.
+ *
+ * Built-in impulses (`builtin:room`, `builtin:hall`, `builtin:plate`) are
+ * generated from a seeded integer PRNG, so they need no files and are
+ * identical on every render path. Everything here is plain float64
+ * arithmetic over fixed loops: deterministic. Clean-room, from standard DSP
+ * literature (Gardner 1995; Wefers 2015), not from any Strudel source.
+ */
+import { seededRandom } from "../random.ts";
+
+/** Longest impulse a render uses, in seconds; longer files are cut. */
+export const MAX_IMPULSE_SECONDS = 10;
+
+/** A stereo impulse response at the render rate, energy-normalized. */
+export type Impulse = Readonly<{
+  /** Stable identity for stem cache keys. */
+  id: string;
+  left: Float64Array;
+  right: Float64Array;
+}>;
+
+type Twiddles = { cos: Float64Array; sin: Float64Array; rev: Uint32Array };
+const TWIDDLES = new Map<number, Twiddles>();
+
+function twiddles(n: number): Twiddles {
+  let table = TWIDDLES.get(n);
+  if (table) return table;
+  const cos = new Float64Array(n >> 1);
+  const sin = new Float64Array(n >> 1);
+  for (let k = 0; k < n >> 1; k += 1) {
+    cos[k] = Math.cos((2 * Math.PI * k) / n);
+    sin[k] = Math.sin((2 * Math.PI * k) / n);
+  }
+  const rev = new Uint32Array(n);
+  for (let i = 1, j = 0; i < n; i += 1) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    rev[i] = j;
+  }
+  table = { cos, sin, rev };
+  TWIDDLES.set(n, table);
+  return table;
+}
+
+/**
+ * In-place radix-2 complex FFT with cached tables. `inverse` uses e^{+i}
+ * and no scaling (inverse(forward(x)) = n·x).
+ */
+export function fftInPlace(
+  re: Float64Array,
+  im: Float64Array,
+  inverse = false,
+): void {
+  const n = re.length;
+  const { cos, sin, rev } = twiddles(n);
+  for (let i = 1; i < n; i += 1) {
+    const j = rev[i]!;
+    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 length = 2; length <= n; length <<= 1) {
+    const half = length >> 1;
+    const stride = n / length;
+    for (let k = 0; k < half; k += 1) {
+      const wr = cos[k * stride]!;
+      const wi = sign * sin[k * stride]!;
+      for (let a = k; a < n; a += length) {
+        const b = a + half;
+        const xr = re[b]! * wr - im[b]! * wi;
+        const xi = re[b]! * wi + im[b]! * wr;
+        re[b] = re[a]! - xr;
+        im[b] = im[a]! - xi;
+        re[a]! += xr;
+        im[a]! += xi;
+      }
+    }
+  }
+}
+
+function nextPow2(value: number): number {
+  let n = 1;
+  while (n < value) n <<= 1;
+  return n;
+}
+
+/** Partition size for an impulse: large blocks offline, a few partitions. */
+export function partitionSize(impulseLength: number): number {
+  return Math.min(32_768, Math.max(512, nextPow2(impulseLength) >> 3));
+}
+
+/**
+ * Adds `gain`·(input ∗ impulse) to `outL`/`outR` (same length as `input`;
+ * the tail past the end is dropped, as with every other effect).
+ * `gainAt`, when given, is sampled per output sample instead of `gain`.
+ */
+export function convolveStereo(
+  input: Float64Array,
+  impulse: Impulse,
+  outL: Float64Array,
+  outR: Float64Array,
+  gain: number,
+  gainAt?: (index: number) => number,
+): void {
+  const rawL = new Float64Array(input.length);
+  const rawR = new Float64Array(input.length);
+  const scale = convolveRaw(input, impulse, rawL, rawR);
+  if (scale === 0) return;
+  addConvolved(rawL, rawR, scale, outL, outR, gain, gainAt);
+}
+
+/**
+ * Adds the unscaled convolution from `convolveRaw` at `gain` (or `gainAt`
+ * per sample): `out += raw · (gain · scale)`, the order `convolveStereo`
+ * always used, so a cached raw signal mixes to the same samples.
+ */
+export function addConvolved(
+  rawL: Float64Array,
+  rawR: Float64Array,
+  scale: number,
+  outL: Float64Array,
+  outR: Float64Array,
+  gain: number,
+  gainAt?: (index: number) => number,
+): void {
+  for (let index = 0; index < rawL.length; index += 1) {
+    const g = (gainAt ? gainAt(index) : gain) * scale;
+    outL[index]! += rawL[index]! * g;
+    outR[index]! += rawR[index]! * g;
+  }
+}
+
+/**
+ * The convolution input ∗ impulse into `rawL`/`rawR` before its inverse-FFT
+ * scale, which it returns. Samples past the input are left as they were
+ * (zero for fresh arrays), as is everything when the impulse is empty.
+ */
+export function convolveRaw(
+  input: Float64Array,
+  impulse: Impulse,
+  rawL: Float64Array,
+  rawR: Float64Array,
+): number {
+  const length = input.length;
+  const irLength = impulse.left.length;
+  if (length === 0 || irLength === 0) return 0;
+  const block = partitionSize(irLength);
+  const n = block * 2;
+  const partitions = Math.ceil(irLength / block);
+  // Impulse partition spectra G_p = FFT(hL_p + i·hR_p), zero-padded to n.
+  const gRe: Float64Array[] = [];
+  const gIm: Float64Array[] = [];
+  for (let p = 0; p < partitions; p += 1) {
+    const re = new Float64Array(n);
+    const im = new Float64Array(n);
+    const start = p * block;
+    const end = Math.min(irLength, start + block);
+    for (let i = start; i < end; i += 1) {
+      re[i - start] = impulse.left[i]!;
+      im[i - start] = impulse.right[i]!;
+    }
+    fftInPlace(re, im);
+    gRe.push(re);
+    gIm.push(im);
+  }
+  // Frequency-domain delay line of input spectra (ring of `partitions`).
+  const xRe = Array.from({ length: partitions }, () => new Float64Array(n));
+  const xIm = Array.from({ length: partitions }, () => new Float64Array(n));
+  const accRe = new Float64Array(n);
+  const accIm = new Float64Array(n);
+  const blocks = Math.ceil(length / block);
+  const scale = 1 / n;
+  for (let k = 0; k < blocks; k += 1) {
+    const slot = k % partitions;
+    const re = xRe[slot]!;
+    const im = xIm[slot]!;
+    // Window: previous block then this block.
+    const base = (k - 1) * block;
+    for (let i = 0; i < n; i += 1) {
+      const at = base + i;
+      re[i] = at >= 0 && at < length ? input[at]! : 0;
+      im[i] = 0;
+    }
+    fftInPlace(re, im);
+    accRe.fill(0);
+    accIm.fill(0);
+    for (let p = 0; p < partitions && p <= k; p += 1) {
+      const source = (slot - p + partitions) % partitions;
+      const ar = xRe[source]!;
+      const ai = xIm[source]!;
+      const br = gRe[p]!;
+      const bi = gIm[p]!;
+      for (let i = 0; i < n; i += 1) {
+        const r = ar[i]!;
+        const m = ai[i]!;
+        accRe[i]! += r * br[i]! - m * bi[i]!;
+        accIm[i]! += r * bi[i]! + m * br[i]!;
+      }
+    }
+    fftInPlace(accRe, accIm, true);
+    const outStart = k * block;
+    const count = Math.min(block, length - outStart);
+    for (let i = 0; i < count; i += 1) {
+      rawL[outStart + i] = accRe[block + i]!;
+      rawR[outStart + i] = accIm[block + i]!;
+    }
+  }
+  return scale;
+}
+
+/** Built-in impulse names (`builtin:<name>`). */
+export const BUILTIN_IMPULSES = Object.freeze({
+  room: { title: "small room", seconds: 0.7, damp: 6000, early: 7, attack: 0 },
+  hall: {
+    title: "concert hall",
+    seconds: 2.8,
+    damp: 4500,
+    early: 5,
+    attack: 0.06,
+  },
+  plate: { title: "plate", seconds: 1.8, damp: 9000, early: 0, attack: 0 },
+} as const);
+export type BuiltinImpulse = keyof typeof BUILTIN_IMPULSES;
+
+const BUILTIN_CACHE = new Map<string, Impulse>();
+
+/**
+ * A generated stereo impulse: early reflections (seeded taps in the first
+ * 40 ms) then decorrelated noise per side with an exact -60 dB decay at
+ * `seconds`, a fade-in over `attack` (diffuse build-up of a large hall) and
+ * a one-pole low-pass that closes from 16 kHz toward `damp` as the tail
+ * decays, so it darkens like air absorption.
+ */
+export function builtinImpulse(
+  name: string,
+  sampleRate: number,
+): Impulse | undefined {
+  if (!Object.prototype.hasOwnProperty.call(BUILTIN_IMPULSES, name))
+    return undefined;
+  const key = `${name}@${sampleRate}`;
+  const cached = BUILTIN_CACHE.get(key);
+  if (cached) return cached;
+  const spec = BUILTIN_IMPULSES[name as BuiltinImpulse];
+  const length = Math.max(1, Math.round(spec.seconds * sampleRate));
+  const sides = ["L", "R"].map((side) => {
+    const random = seededRandom(`dawg-ir:${name}:${side}`);
+    const out = new Float64Array(length);
+    const decay = Math.log(1000) / spec.seconds;
+    let state = 0;
+    for (let index = 0; index < length; index += 1) {
+      const t = index / sampleRate;
+      const progress = t / spec.seconds;
+      const cutoff = 16_000 * (spec.damp / 16_000) ** progress;
+      const coefficient =
+        1 -
+        Math.exp(
+          (-2 * Math.PI * Math.min(cutoff, sampleRate * 0.45)) / sampleRate,
+        );
+      state += coefficient * (random() * 2 - 1 - state);
+      const build = spec.attack > 0 ? Math.min(1, t / spec.attack) : 1;
+      out[index] = state * Math.exp(-decay * t) * build;
+    }
+    for (let tap = 0; tap < spec.early; tap += 1) {
+      const at = Math.floor((0.004 + random() * 0.036) * sampleRate);
+      if (at < length)
+        out[at]! += (random() < 0.5 ? -1 : 1) * (0.9 - tap * 0.08);
+    }
+    return out;
+  });
+  const impulse = normalizeImpulse(`builtin:${name}`, sides[0]!, sides[1]!);
+  BUILTIN_CACHE.set(key, impulse);
+  return impulse;
+}
+
+/**
+ * An impulse from a decoded sample (mono, any rate): resampled linearly to
+ * the render rate, cut to `MAX_IMPULSE_SECONDS`, energy-normalized; both
+ * sides play the same response.
+ */
+export function sampleImpulse(
+  id: string,
+  mono: Float32Array,
+  sourceRate: number,
+  sampleRate: number,
+): Impulse {
+  const length = Math.max(
+    1,
+    Math.min(
+      Math.round((mono.length * sampleRate) / sourceRate),
+      Math.round(MAX_IMPULSE_SECONDS * sampleRate),
+    ),
+  );
+  const out = new Float64Array(length);
+  const step = sourceRate / sampleRate;
+  for (let index = 0; index < length; index += 1) {
+    const position = index * step;
+    const base = Math.floor(position);
+    const a = mono[Math.min(mono.length - 1, base)] ?? 0;
+    const b = mono[Math.min(mono.length - 1, base + 1)] ?? 0;
+    out[index] = a + (b - a) * (position - base);
+  }
+  return normalizeImpulse(id, out, out);
+}
+
+/** Scales both sides so the mean energy per side is 1 (silence stays 0). */
+function normalizeImpulse(
+  id: string,
+  left: Float64Array,
+  right: Float64Array,
+): Impulse {
+  let energy = 0;
+  for (let index = 0; index < left.length; index += 1)
+    energy += left[index]! * left[index]! + right[index]! * right[index]!;
+  const scale = energy > 0 ? 1 / Math.sqrt(energy / 2) : 0;
+  const l = new Float64Array(left.length);
+  const r = new Float64Array(right.length);
+  for (let index = 0; index < left.length; index += 1) {
+    l[index] = left[index]! * scale;
+    r[index] = right[index]! * scale;
+  }
+  return Object.freeze({ id, left: l, right: r });
+}

package/src/audio/effects/drive.ts

@@ -0,0 +1,142 @@
+/**
+ * Saturation stages on the mono track signal: bitcrush/coarse (sample-rate
+ * and bit-depth reduction) and the distortion waveshaper.
+ */
+import type { Track } from "../../../core/score.ts";
+import type { FxValues } from "../../../core/fx.ts";
+import {
+  CONTROL_SAMPLES,
+  OnePole,
+  clamp,
+  fxReader,
+  type EffectContext,
+} from "./common.ts";
+
+/**
+ * Bitcrush: `coarse` holds every Nth sample (sample-rate reduction) and
+ * `bits` quantizes to 2^(bits-1) levels per polarity. Fractional bits are
+ * allowed so the amount can sweep smoothly.
+ */
+export function applyCrush(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "crush", values, context);
+  const bits = read.param("bits");
+  const mix = read.param("mix");
+  const coarse = Math.max(1, Math.round(read.number("coarse")));
+  let levels = 2 ** (bits.at(0) - 1);
+  let wet = mix.at(0);
+  let held = 0;
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      if (bits.automated) levels = 2 ** (bits.at(index) - 1);
+      if (mix.automated) wet = mix.at(index);
+    }
+    const input = buffer[index]!;
+    if (index % coarse === 0) held = input;
+    const crushed = Math.round(held * levels) / levels;
+    buffer[index] = input + (crushed - input) * wet;
+  }
+}
+
+/** Waveshaper curves; each maps 0 → 0 and is odd unless noted. */
+export function shapeCurve(type: string, x: number, amount: number): number {
+  switch (type) {
+    case "hard":
+      return clamp(x, -1, 1);
+    case "cubic": {
+      const y = clamp(x, -1.5, 1.5);
+      return y - (y * y * y) / 6.75;
+    }
+    case "diode":
+      // Asymmetric: positive half saturates harder, like a forward-biased diode.
+      return x >= 0 ? Math.tanh(1.5 * x) / 1.2 : Math.tanh(0.7 * x) / 0.85;
+    case "asym":
+      return Math.tanh(x + 0.3) - Math.tanh(0.3);
+    case "fold": {
+      // Triangle wavefolder: reflect at ±1.
+      const folded = (((x + 1) % 4) + 4) % 4;
+      return folded < 2 ? folded - 1 : 3 - folded;
+    }
+    case "sinefold":
+      return Math.sin((Math.PI / 2) * x);
+    case "chebyshev": {
+      // T3 Chebyshev blended in: adds a strong third harmonic.
+      const y = Math.tanh(x);
+      return 0.6 * y + 0.4 * (4 * y * y * y - 3 * y);
+    }
+    case "scurve":
+      return (2 / Math.PI) * Math.atan(x * 1.4);
+    case "shape": {
+      // Strudel `shape` amount 0..1 → k; the classic (1+k)x/(1+k|x|) shaper.
+      const a = Math.min(0.99, amount);
+      const k = (2 * a) / (1 - a);
+      return ((1 + k) * x) / (1 + k * Math.abs(x));
+    }
+    default:
+      return Math.tanh(x);
+  }
+}
+
+/** Reference level for automatic gain compensation (about -12 dBFS). */
+const COMPENSATION_LEVEL = 0.25;
+const COMPENSATION_RMS = COMPENSATION_LEVEL / Math.SQRT2;
+const COMPENSATION_POINTS = 64;
+
+/**
+ * Distortion: pre-gain from `drive` (0..10 → 0..36 dB), the chosen curve,
+ * gain compensation so louder drive does not mean a louder track, a
+ * post-shaper `tone` low-pass, then `postgain` and the wet/dry `mix`.
+ */
+export function applyDistort(
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+): void {
+  const read = fxReader(track, "distort", values, context);
+  const drive = read.param("drive");
+  const tone = read.param("tone");
+  const mix = read.param("mix");
+  const type = read.text("type");
+  const postgain = read.number("postgain");
+  // `shape` takes the drive as its 0..1 amount; other curves use pre-gain.
+  const setDrive = (value: number) => {
+    const amount = value / 10;
+    const pregain = type === "shape" ? 1 : 2 ** (value * 0.6);
+    // RMS of the curve over one sine cycle at the reference level, so
+    // folders (whose output is not monotonic in level) compensate too.
+    let sum = 0;
+    for (let k = 0; k < COMPENSATION_POINTS; k += 1) {
+      const x =
+        COMPENSATION_LEVEL * Math.sin((2 * Math.PI * k) / COMPENSATION_POINTS);
+      sum += shapeCurve(type, pregain * x, amount) ** 2;
+    }
+    const reference = Math.sqrt(sum / COMPENSATION_POINTS);
+    const compensation = clamp(
+      COMPENSATION_RMS / Math.max(1e-3, reference),
+      0.05,
+      1.5,
+    );
+    return { amount, pregain, compensation };
+  };
+  let state = setDrive(drive.at(0));
+  const lowpass = new OnePole(tone.at(0), context.sampleRate);
+  let wet = mix.at(0);
+  for (let index = 0; index < buffer.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      if (drive.automated) state = setDrive(drive.at(index));
+      if (tone.automated) lowpass.set(tone.at(index), context.sampleRate);
+      if (mix.automated) wet = mix.at(index);
+    }
+    const input = buffer[index]!;
+    const shaped =
+      shapeCurve(type, input * state.pregain, state.amount) *
+      state.compensation;
+    const output = lowpass.process(shaped) * postgain;
+    buffer[index] = input + (output - input) * wet;
+  }
+}

package/src/audio/effects/duck.ts

@@ -0,0 +1,122 @@
+/**
+ * Orbits and ducking, applied where track stems are summed.
+ *
+ * Every track plays on an orbit (`fx.orbit`, 1 when absent). A track with
+ * `fx.duck` dips its target orbit at each of its note onsets: the gain
+ * falls to `1 - depth` over `onset` seconds and climbs back over `attack`
+ * seconds (a new onset during the recovery dips again from where the gain
+ * is). Several duckers on one orbit multiply. A ducker never ducks itself.
+ *
+ * Ducking is a gain on finished stems, so it never invalidates a ducked
+ * track's cached stem and costs nothing when no track ducks. The curve is
+ * plain float64 arithmetic over integer sample positions: deterministic on
+ * every render path. Clean-room, from Strudel's documented behaviour.
+ */
+import type { Track } from "../../../core/score.ts";
+
+export type Ducker = Readonly<{
+  trackId: string;
+  target: number;
+  depth: number;
+  attack: number;
+  onset: number;
+  /** Note onsets in samples, any order. */
+  onsets: readonly number[];
+}>;
+
+/** The orbit a track plays on. */
+export function orbitOf(track: Track | undefined): number {
+  const orbit = track?.fx?.orbit?.orbit;
+  return typeof orbit === "number" ? orbit : 1;
+}
+
+/** The track's duck settings without onsets, or undefined when it does not duck. */
+export function duckSettings(
+  track: Track | undefined,
+): Omit<Ducker, "trackId" | "onsets"> | undefined {
+  const duck = track?.fx?.duck;
+  if (!duck) return undefined;
+  const number = (key: string, fallback: number) =>
+    typeof duck[key] === "number" ? duck[key] : fallback;
+  return {
+    target: number("orbit", 1),
+    depth: number("depth", 1),
+    attack: number("attack", 0.1),
+    onset: number("onset", 0.003),
+  };
+}
+
+/**
+ * The duck envelope (0 = no dip, 1 = full dip) of one ducker over
+ * `samples` samples. With `loopFrames`, onsets repeat every loop so the
+ * folded tail sees the next pass's notes.
+ */
+export function duckEnvelope(
+  ducker: Ducker,
+  samples: number,
+  sampleRate: number,
+  loopFrames?: number,
+): Float64Array {
+  const marks = new Uint8Array(samples);
+  const repeats =
+    loopFrames && loopFrames > 0 ? Math.ceil(samples / loopFrames) : 1;
+  for (const onset of ducker.onsets)
+    for (let pass = 0; pass < repeats; pass += 1) {
+      const at = onset + pass * (loopFrames ?? 0);
+      if (at >= 0 && at < samples) marks[at] = 1;
+    }
+  const envelope = new Float64Array(samples);
+  const riseSamples = Math.max(1, ducker.onset * sampleRate);
+  const fallStep = 1 / Math.max(1, ducker.attack * sampleRate);
+  let level = 0;
+  let rising = false;
+  let riseFrom = 0;
+  let riseAt = 0;
+  for (let index = 0; index < samples; index += 1) {
+    if (marks[index] === 1) {
+      rising = true;
+      riseFrom = level;
+      riseAt = 0;
+    }
+    if (rising) {
+      riseAt += 1;
+      const progress = Math.min(1, riseAt / riseSamples);
+      level = riseFrom + (1 - riseFrom) * progress;
+      if (progress >= 1) rising = false;
+    } else if (level > 0) level = Math.max(0, level - fallStep);
+    envelope[index] = level;
+  }
+  return envelope;
+}
+
+/**
+ * Per-track gain curves: for each track id that some other track ducks,
+ * the product of `1 - depth · envelope` over its duckers. Tracks absent
+ * from the map play at unity.
+ */
+export function duckGains(
+  tracks: readonly Readonly<{ id: string; orbit: number }>[],
+  duckers: readonly Ducker[],
+  samples: number,
+  sampleRate: number,
+  loopFrames?: number,
+): Map<string, Float64Array> {
+  const gains = new Map<string, Float64Array>();
+  if (duckers.length === 0) return gains;
+  const envelopes = duckers.map((ducker) =>
+    duckEnvelope(ducker, samples, sampleRate, loopFrames),
+  );
+  for (const track of tracks) {
+    let gain: Float64Array | undefined;
+    duckers.forEach((ducker, which) => {
+      if (ducker.target !== track.orbit || ducker.trackId === track.id) return;
+      if (ducker.depth <= 0) return;
+      if (!gain) gain = new Float64Array(samples).fill(1);
+      const envelope = envelopes[which]!;
+      for (let index = 0; index < samples; index += 1)
+        gain[index]! *= 1 - ducker.depth * envelope[index]!;
+    });
+    if (gain) gains.set(track.id, gain);
+  }
+  return gains;
+}