@hraness/dawg 0.6.0 → 0.6.1

package/src/audio/dsp/shift.ts

@@ -0,0 +1,256 @@
+/**
+ * Pitch shift at constant duration (0.6 B2 `shift`, `formant`), ported from
+ * the granular prototype (`proto/granular/stretch.ts` `pitchShift`):
+ * phase-vocoder stretch by rho = 2^(st/12) onto an intermediate axis (bins
+ * above Nyquist/rho dropped so the read-back cannot alias), then read it
+ * rho times faster with a 4-point Hermite, so the length is kept exactly.
+ *
+ * Formants: absent follows the pitch (like a tape); a number moves them
+ * that many semitones from where they were, so `0` keeps them (cepstral
+ * envelope from `envelope.ts`: magnitudes are divided by the frame's
+ * envelope and multiplied by the envelope warped to where it must land
+ * after the read-back). Identity phase locking after Laroche and Dolson,
+ * "Improved phase vocoder time-scale modification of audio", IEEE TSAP 1999.
+ * Strudel's `stretch` (superdough's phase-vocoder worklet) is the same idea.
+ */
+import {
+  ENVELOPE_ITERATIONS,
+  ENVELOPE_LIFTER_SECONDS,
+  cepstralEnvelope,
+  envelopeScratch,
+  peakEnvelope,
+} from "./envelope.ts";
+import { hermite4 } from "./interp.ts";
+import {
+  HANN_SQUARED_OLA_QUARTER,
+  analyse,
+  frameSize,
+  hann,
+  inverse,
+  princarg,
+  sampleAt,
+} from "./stft.ts";
+
+/** Analysis frame, as the `tones` fit (85 ms). */
+export const SHIFT_FRAME_SECONDS = 0.085;
+/** Vocoder hops between yields of `pitchShiftJob`. */
+const SHIFT_YIELD_HOPS = 16;
+/** Largest per-frame level restore after formant correction (12 dB). */
+const FORMANT_LEVEL_CAP = 4;
+/** Largest formant correction gain (24 dB), so a deep envelope dip cannot explode. */
+const MAX_FORMANT_GAIN = 16;
+
+export type ShiftOptions = Readonly<{
+  /** Formant shift in semitones; 0 keeps them; absent follows the pitch. */
+  formant?: number;
+  /** Frame length in seconds (rounded up to a power of two). */
+  frame?: number;
+  /** Cepstral lifter in seconds. */
+  lifter?: number;
+  /** True-envelope passes (0 is the plain cepstral envelope; default 16). */
+  iterations?: number;
+  /** Shrink the lifter to a quarter pitch period per frame (default on). */
+  adaptive?: boolean;
+  /**
+   * Envelope used to keep formants: "peaks" (default) joins the harmonic
+   * peaks; "cepstral" is the true cepstral envelope alone.
+   */
+  envelope?: "peaks" | "cepstral";
+}>;
+
+/**
+ * Phase vocoder reading `x` at `t / rho` for `outLength` frames, with
+ * bins above Nyquist/rho removed and optional formant correction for a
+ * later read-back at `rho`.
+ */
+function* stretchForShift(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  rho: number,
+  outLength: number,
+  formantRatio: number | undefined,
+  options: ShiftOptions,
+): Generator<void, Float64Array> {
+  const n = frameSize(options.frame ?? SHIFT_FRAME_SECONDS, sampleRate);
+  const hs = n / 4;
+  const half = n / 2;
+  const w = hann(n);
+  const norm = 1 / HANN_SQUARED_OLA_QUARTER;
+  const keep = rho > 1 ? Math.floor(half / rho) : half;
+  const lifter = Math.max(
+    4,
+    Math.round((options.lifter ?? ENVELOPE_LIFTER_SECONDS) * sampleRate),
+  );
+  const periodRange = [sampleRate / 800, sampleRate / 50] as const;
+  const out = new Float64Array(outLength + n);
+  const reA = new Float64Array(n);
+  const imA = new Float64Array(n);
+  const reB = new Float64Array(n);
+  const imB = new Float64Array(n);
+  const mag = new Float64Array(half + 1);
+  const phA = new Float64Array(half + 1);
+  const syn = new Float64Array(half + 1);
+  const next = new Float64Array(half + 1);
+  const omega = new Float64Array(half + 1);
+  const env = new Float64Array(half + 1);
+  const scratch = envelopeScratch(n);
+  const smooth = new Float64Array(half + 1);
+  const envPeaks: number[] = [];
+  const peaks: number[] = [];
+  for (let m = 0; m * hs < outLength; m += 1) {
+    if (m % SHIFT_YIELD_HOPS === SHIFT_YIELD_HOPS - 1) yield;
+    const at = Math.round((m * hs + half) / rho - half);
+    analyse(x, at, w, reA, imA);
+    analyse(x, at - hs, w, reB, imB);
+    for (let k = 0; k <= half; k += 1) {
+      mag[k] = Math.hypot(reA[k]!, imA[k]!);
+      phA[k] = Math.atan2(imA[k]!, reA[k]!);
+      const phB = Math.atan2(imB[k]!, reB[k]!);
+      const bin = (2 * Math.PI * k * hs) / n;
+      omega[k] = bin + princarg(phA[k]! - phB - bin);
+    }
+    if (formantRatio !== undefined)
+      cepstralEnvelope(
+        mag,
+        n,
+        lifter,
+        env,
+        scratch,
+        options.iterations ?? ENVELOPE_ITERATIONS,
+        options.adaptive === false ? undefined : periodRange,
+      );
+    if (formantRatio !== undefined && options.envelope !== "cepstral") {
+      smooth.set(env);
+      peakEnvelope(mag, half, env, smooth, envPeaks);
+    }
+    if (m === 0) syn.set(phA);
+    else {
+      peaks.length = 0;
+      for (let k = 2; k <= half - 2; k += 1) {
+        const v = mag[k]!;
+        if (
+          v > mag[k - 1]! &&
+          v >= mag[k + 1]! &&
+          v > mag[k - 2]! &&
+          v >= mag[k + 2]!
+        )
+          peaks.push(k);
+      }
+      if (peaks.length === 0)
+        for (let k = 0; k <= half; k += 1) syn[k] = syn[k]! + omega[k]!;
+      else {
+        for (const p of peaks) next[p] = syn[p]! + omega[p]!;
+        let j = 0;
+        for (let k = 0; k <= half; k += 1) {
+          while (
+            j + 1 < peaks.length &&
+            Math.abs(peaks[j + 1]! - k) < Math.abs(peaks[j]! - k)
+          )
+            j += 1;
+          const p = peaks[j]!;
+          if (k !== p) next[k] = next[p]! + phA[k]! - phA[p]!;
+        }
+        syn.set(next);
+      }
+    }
+    let before = 0;
+    let after = 0;
+    for (let k = 0; k <= half; k += 1) {
+      let a = k > keep ? 0 : mag[k]!;
+      before += a * a;
+      if (formantRatio !== undefined && a > 0) {
+        // Bin k lands at k*rho after the read-back; give it the envelope
+        // found at k*rho/formantRatio in the source frame.
+        const src = (k * rho) / formantRatio;
+        const i0 = Math.floor(src);
+        const target =
+          i0 + 1 <= half
+            ? env[i0]! + (env[i0 + 1]! - env[i0]!) * (src - i0)
+            : env[half]! * 1e-3;
+        a *= Math.min(target / env[k]!, MAX_FORMANT_GAIN);
+      }
+      after += a * a;
+      reA[k] = a * Math.cos(syn[k]!);
+      imA[k] = a * Math.sin(syn[k]!);
+      if (k > 0 && k < half) {
+        reA[n - k] = reA[k]!;
+        imA[n - k] = -imA[k]!;
+      }
+    }
+    imA[0] = 0;
+    imA[half] = 0;
+    // Formant correction reshapes the spectrum, not the loudness: give the
+    // frame back its energy (a scale moves no peak), capped at 12 dB.
+    if (formantRatio !== undefined && after > 0) {
+      const gain = Math.min(Math.sqrt(before / after), FORMANT_LEVEL_CAP);
+      for (let k = 0; k < n; k += 1) {
+        reA[k] = reA[k]! * gain;
+        imA[k] = imA[k]! * gain;
+      }
+    }
+    inverse(reA, imA);
+    const o0 = m * hs;
+    for (let i = 0; i < n; i += 1)
+      out[o0 + i] = out[o0 + i]! + reA[i]! * w[i]! * norm;
+  }
+  return out;
+}
+
+/**
+ * `x` shifted by `semitones` at the same length. `formant` (semitones)
+ * moves the formants independently; 0 keeps them.
+ */
+export function pitchShift(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  semitones: number,
+  options: ShiftOptions = {},
+): Float32Array {
+  const job = pitchShiftJob(x, sampleRate, semitones, options);
+  for (;;) {
+    const step = job.next();
+    if (step.done) return step.value;
+  }
+}
+
+/**
+ * `pitchShift` as resumable work: yields every few vocoder hops so a live
+ * engine can spread a long shift over idle time (`src/audio/fit.ts`).
+ */
+export function* pitchShiftJob(
+  x: ArrayLike<number>,
+  sampleRate: number,
+  semitones: number,
+  options: ShiftOptions = {},
+): Generator<void, Float32Array> {
+  const length = x.length;
+  const out = new Float32Array(length);
+  if (semitones === 0 && options.formant === undefined) {
+    for (let i = 0; i < length; i += 1) out[i] = x[i]!;
+    return out;
+  }
+  const rho = 2 ** (semitones / 12);
+  const formantRatio =
+    options.formant === undefined ? undefined : 2 ** (options.formant / 12);
+  const midLength = Math.ceil(length * rho) + 4;
+  const y = yield* stretchForShift(
+    x,
+    sampleRate,
+    rho,
+    midLength,
+    formantRatio,
+    options,
+  );
+  for (let i = 0; i < length; i += 1) {
+    const pos = i * rho;
+    const j = Math.floor(pos);
+    out[i] = hermite4(
+      sampleAt(y, j - 1),
+      sampleAt(y, j),
+      sampleAt(y, j + 1),
+      sampleAt(y, j + 2),
+      pos - j,
+    );
+  }
+  return out;
+}

package/src/audio/effects/chain.ts

@@ -2,8 +2,9 @@
  * The fixed per-track effects chain (`FX_CHAIN` in core/fx.ts):
  *
  *   filter → djf → autofilter → vowel → crush → distort → stomp → head →
- *   cab → tremolo →
- *   compressor → pan → phaser → chorus → leslie → postgain → delay → reverb
+ *   cab → wobble → bloom → swell → tremolo →
+ *   compressor → pan → double → phaser → chorus → leslie → postgain →
+ *   delay → reverb
  *
  * Stages before pan run on the mono voice sum; pan spreads it to stereo;
  * the rest run on the stereo pair. Disabled stages cost nothing.
@@ -12,6 +13,7 @@ import { FX_CHAIN, type FxName, type FxValues } from "../../../core/fx.ts";
 import type { Track } from "../../../core/score.ts";
 import type { EffectContext } from "./common.ts";
 import { applyCrush, applyDistort } from "./drive.ts";
+import { applyBloom, applyDouble, applySwell, applyWobble } from "./gaze.ts";
 import { applyCompressor, applyPostgain, applyTremolo } from "./dynamics.ts";
 import {
   applyAutoFilter,
@@ -32,7 +34,16 @@ export {
   reverbWet,
   type ReverbWet,
 } from "./space.ts";
-export { interpolateAutomation, type EffectContext } from "./common.ts";
+export {
+  interpolateAutomation,
+  type EffectContext,
+  type EffectNote,
+} from "./common.ts";
+
+/** Whether `track` has a stage that reads `EffectContext.notes`. */
+export function needsEffectNotes(track: Track | undefined): boolean {
+  return Boolean(track?.fx?.bloom || track?.fx?.swell);
+}
 
 type MonoStage = (
   buffer: Float64Array,
@@ -57,11 +68,15 @@ const MONO: Readonly<Partial<Record<FxName, MonoStage>>> = Object.freeze({
   stomp: applyStomp,
   head: applyHead,
   cab: applyCab,
+  wobble: applyWobble,
+  bloom: applyBloom,
+  swell: applySwell,
   tremolo: applyTremolo,
   compressor: applyCompressor,
 });
 
 const STEREO: Readonly<Partial<Record<FxName, StereoStage>>> = Object.freeze({
+  double: applyDouble,
   phaser: applyPhaser,
   chorus: applyChorus,
   leslie: applyLeslie,

package/src/audio/effects/common.ts

@@ -25,6 +25,20 @@ export type EffectContext = Readonly<{
   irs?: ReadonlyMap<string, DecodedSample>;
   /** The song's tempo map in samples; absent: constant tempo. */
   warp?: SampleWarp;
+  /**
+   * The track's notes in buffer samples, for note-aware stages (bloom,
+   * swell; 0.6.1). Filled only when such a stage is on.
+   */
+  notes?: readonly EffectNote[];
+}>;
+
+/** One note as a note-aware effect sees it: where it sounds and its pitch. */
+export type EffectNote = Readonly<{
+  id: string;
+  start: number;
+  length: number;
+  hz: number;
+  velocity: number;
 }>;
 
 /** Score tick at sample `index`, through the tempo map when there is one. */

package/src/audio/effects/convolution.ts

@@ -10,7 +10,7 @@
  * 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
+ * Built-in impulses (`builtin:room`, `hall`, `plate`, `reverse`, `gate`, `spring`) 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
@@ -236,6 +236,31 @@ export const BUILTIN_IMPULSES = Object.freeze({
     attack: 0.06,
   },
   plate: { title: "plate", seconds: 1.8, damp: 9000, early: 0, attack: 0 },
+  // 0.6.1 shaped impulses (`shape`, see `shapedSide`).
+  reverse: {
+    title: "reverse",
+    seconds: 1.2,
+    damp: 7000,
+    early: 0,
+    attack: 0,
+    shape: "rise",
+  },
+  gate: {
+    title: "gated",
+    seconds: 0.45,
+    damp: 8000,
+    early: 6,
+    attack: 0.005,
+    shape: "gate",
+  },
+  spring: {
+    title: "spring tank",
+    seconds: 2.2,
+    damp: 4500,
+    early: 0,
+    attack: 0,
+    shape: "spring",
+  },
 } as const);
 export type BuiltinImpulse = keyof typeof BUILTIN_IMPULSES;
 
@@ -259,6 +284,15 @@ export function builtinImpulse(
   if (cached) return cached;
   const spec = BUILTIN_IMPULSES[name as BuiltinImpulse];
   const length = Math.max(1, Math.round(spec.seconds * sampleRate));
+  if ("shape" in spec) {
+    const impulse = normalizeImpulse(
+      `builtin:${name}`,
+      shapedSide(name, "L", spec, sampleRate),
+      shapedSide(name, "R", spec, sampleRate),
+    );
+    BUILTIN_CACHE.set(key, impulse);
+    return impulse;
+  }
   const sides = ["L", "R"].map((side) => {
     const random = seededRandom(`dawg-ir:${name}:${side}`);
     const out = new Float64Array(length);
@@ -289,6 +323,77 @@ export function builtinImpulse(
   return impulse;
 }
 
+/**
+ * One side of a shaped built-in (0.6.1), all seeded noise through a
+ * one-pole low-pass at `damp`:
+ * - rise: the Yamaha SPX90 "reverse gate": energy rises exponentially to a
+ *   hard cut at `seconds`, so the wash swells into the cut (a reverse
+ *   reverb that stays causal and works in play mode).
+ * - gate: dense flat tail cut hard at `seconds` (the 1980s gated snare).
+ * - spring: a decaying noise tail plus a train of dispersive chirps every
+ *   ~33 ms (high frequencies arrive first, the drip of a spring tank).
+ */
+function shapedSide(
+  name: string,
+  side: string,
+  spec: Readonly<{
+    seconds: number;
+    damp: number;
+    early: number;
+    attack: number;
+    shape: string;
+  }>,
+  sampleRate: number,
+): Float64Array {
+  const random = seededRandom(`dawg-ir:${name}:${side}`);
+  const length = Math.max(16, Math.round(spec.seconds * sampleRate));
+  const out = new Float64Array(length);
+  const coefficient =
+    1 -
+    Math.exp(
+      (-2 * Math.PI * Math.min(spec.damp, sampleRate * 0.45)) / sampleRate,
+    );
+  const fadeOut = Math.min(length >> 2, Math.round(0.003 * sampleRate));
+  let state = 0;
+  for (let index = 0; index < length; index += 1) {
+    const x = (index + 0.5) / length;
+    const t = index / sampleRate;
+    state += coefficient * (random() * 2 - 1 - state);
+    let env: number;
+    if (spec.shape === "rise") env = Math.exp(4 * (x - 1));
+    else if (spec.shape === "gate")
+      env = Math.min(1, t / Math.max(1e-4, spec.attack)) * (1 - 0.3 * x);
+    else env = 0.35 * Math.exp((-Math.log(1000) * t) / spec.seconds);
+    // A short fade into the cut, so it clicks no more than a real gate.
+    if (spec.shape !== "spring" && index >= length - fadeOut)
+      env *= (length - index) / fadeOut;
+    out[index] = state * env;
+  }
+  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.5 - tap * 0.05);
+  }
+  if (spec.shape === "spring") {
+    // Dispersive chirps: 4 kHz falling to 300 Hz over 25 ms, each echo
+    // -1.6 dB down on the last, the period jittered per side.
+    const period = (0.031 + 0.004 * random()) * sampleRate;
+    const chirp = 0.025;
+    const decay = Math.log(1000) / spec.seconds;
+    for (let echo = 0; echo * period < length; echo += 1) {
+      const start = Math.round(echo * period);
+      const level = Math.exp((-decay * start) / sampleRate);
+      let phase = random() * 2 * Math.PI;
+      for (let k = 0; k < chirp * sampleRate && start + k < length; k += 1) {
+        const u = k / (chirp * sampleRate);
+        const hz = 4000 * (300 / 4000) ** u;
+        phase += (2 * Math.PI * hz) / sampleRate;
+        out[start + k]! += level * Math.sin(phase) * Math.sin(Math.PI * u);
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * An impulse from a decoded sample (mono, any rate): resampled linearly to
  * the render rate, cut to `MAX_IMPULSE_SECONDS`, energy-normalized; both