@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/vocoder/bank.ts

@@ -0,0 +1,314 @@
+/**
+ * The channel vocoder (0.7): a bank of cascaded RBJ band-passes analyses
+ * the modulator, each band's follower shapes the same band of the carrier.
+ * Ported from the reviewed prototype (proto/vocoder, DSP v2):
+ * - layout from bands/lo/hi/width only (sample-rate independent);
+ * - band k reads the modulator advanced by its group delay plus the attack;
+ * - formant: synthesis band k takes the envelope at fractional analysis
+ *   index k - formant / 12 / log2(ratio);
+ * - enhance whitens the carrier per band (each band normalised by its own
+ *   follower), so a dull carrier still speaks in every band;
+ * - fixed makeup gain from the layout only, never from the rendered span.
+ * A stereo carrier runs one analysis and one synthesis bank per channel.
+ */
+import {
+  bandpass,
+  bankDesign,
+  runBiquad,
+  type Biquad,
+} from "../dsp/bandbank.ts";
+import { follow, followCoef, gateCurve, holdCurve } from "../dsp/follow.ts";
+import { unit } from "../dsp/rng.ts";
+import { at, VOCODER_BLOCK, type VocoderControl } from "./control.ts";
+import { hissPath, unvoicedCurve } from "./detect.ts";
+
+/** Fixed channel makeup from the layout only (fitted once on the voice fixture). */
+export function channelMakeup(bands: number, width: number): number {
+  return (
+    (1.4 * (bands / 16) ** 0.29) / (width <= 1 ? width ** 0.35 : width ** 1.1)
+  );
+}
+
+/** Reference band level for depth < 1: envelope^depth * REF^(1 - depth). */
+const REF = 0.02;
+
+/** A noise sample in -1..1 at an absolute song sample. */
+export function noiseSample(seed: number, songSample: number): number {
+  return unit(seed, songSample, 11) * 2 - 1;
+}
+
+/** Follower with an optional per-sample release curve and hold. */
+function followVarying(
+  x: Float64Array,
+  attack: number,
+  release: number,
+  releaseCurve: Float64Array | undefined,
+  sampleRate: number,
+  hold?: Uint8Array,
+): Float64Array {
+  if (!releaseCurve) return follow(x, attack, release, sampleRate, hold);
+  const a = followCoef(attack, sampleRate);
+  const out = new Float64Array(x.length);
+  let e = 0;
+  let lastRelease = Number.NaN;
+  let r = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    if (releaseCurve[i] !== lastRelease) {
+      lastRelease = releaseCurve[i]!;
+      r = followCoef(lastRelease, sampleRate);
+    }
+    if (!hold || hold[i] === 0) {
+      const v = Math.abs(x[i]!);
+      const c = v > e ? a : r;
+      e = c * e + (1 - c) * v;
+    }
+    out[i] = e;
+  }
+  return out;
+}
+
+/** Runs a biquad whose coefficients may change at 32-sample blocks. */
+function runBand(
+  x: Float64Array,
+  filter: Biquad,
+  filterAt: ((i: number) => Biquad) | undefined,
+): void {
+  if (!filterAt) {
+    runBiquad(filter, x);
+    return;
+  }
+  let z1 = 0;
+  let z2 = 0;
+  let f = filterAt(0);
+  for (let i = 0; i < x.length; i += 1) {
+    if (i % VOCODER_BLOCK === 0) f = filterAt(i);
+    const v = x[i]!;
+    const y = f.b0 * v + z1;
+    z1 = f.b1 * v - f.a1 * y + z2;
+    z2 = f.b2 * v - f.a2 * y;
+    x[i] = y;
+  }
+}
+
+/**
+ * The band filter run twice in cascade, in one pass when the coefficients
+ * are fixed (the same arithmetic per sample as two passes).
+ */
+function runBandTwice(
+  x: Float64Array,
+  filter: Biquad,
+  filterAt: ((i: number) => Biquad) | undefined,
+): void {
+  if (filterAt) {
+    runBand(x, filter, filterAt);
+    runBand(x, filter, filterAt);
+    return;
+  }
+  const { b0, b1, b2, a1, a2 } = filter;
+  let p1 = 0;
+  let p2 = 0;
+  let q1 = 0;
+  let q2 = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    const v = x[i]!;
+    const y = b0 * v + p1;
+    p1 = b1 * v - a1 * y + p2;
+    p2 = b2 * v - a2 * y;
+    const w = b0 * y + q1;
+    q1 = b1 * y - a1 * w + q2;
+    q2 = b2 * y - a2 * w;
+    x[i] = w;
+  }
+}
+
+/** `e[i] *= g[i]` (its own function so the loop is optimised). */
+function multiplyInto(e: Float64Array, g: Float64Array): void {
+  for (let i = 0; i < e.length; i += 1) e[i] = e[i]! * g[i]!;
+}
+
+/** Cross-fades the carrier toward level-matched noise where `u` is unvoiced. */
+function blendUnvoiced(
+  carrier: Float64Array,
+  u: Float64Array,
+  control: VocoderControl,
+  seed: number,
+  origin: number,
+  sr: number,
+): void {
+  const level = follow(carrier, 0.01, 0.1, sr);
+  const curve = control.curves.unvoiced;
+  const fixed = control.settings.unvoiced;
+  for (let i = 0; i < carrier.length; i += 1) {
+    const w = u[i]! * (curve ? curve[i]! : fixed);
+    if (w <= 0) continue;
+    const noise = noiseSample(seed, origin + i);
+    carrier[i] =
+      carrier[i]! * (1 - w) + noise * 1.7 * Math.max(level[i]!, 0.05) * w;
+  }
+}
+
+/**
+ * One synthesis band into `out` with a fixed formant shift and depth: the
+ * envelope interpolated between analysis bands `ea` and `eb` by `fr`, shaped
+ * by `depth`, over the carrier band `syn` (whitened by `ec` when enhancing).
+ * A small function of its own so the JIT optimises the loop: inlined in
+ * `channelVocode`, which runs once per render, it stayed in the baseline tier.
+ */
+function mixBandFixed(
+  out: Float64Array,
+  syn: Float64Array,
+  ea: Float64Array,
+  eb: Float64Array,
+  fr: number,
+  ec: Float64Array | undefined,
+  depth: number,
+  scale: number,
+): void {
+  const n = out.length;
+  const refPow = REF ** (1 - depth);
+  if (ec)
+    for (let i = 0; i < n; i += 1) {
+      const e = ea[i]! * (1 - fr) + eb[i]! * fr;
+      const level = depth === 1 ? e : e ** depth * refPow;
+      const g = level / (ec[i]! + 1e-5);
+      out[i]! += syn[i]! * Math.min(g, 1e3) * scale;
+    }
+  else
+    for (let i = 0; i < n; i += 1) {
+      const e = ea[i]! * (1 - fr) + eb[i]! * fr;
+      const level = depth === 1 ? e : e ** depth * refPow;
+      out[i]! += syn[i]! * level * 8 * scale;
+    }
+}
+
+/**
+ * Vocodes each carrier channel with `mod`. The modulator is read up to the
+ * largest band advance past each output sample (zero past its end).
+ * Returns the wet signal per channel, after `gain` and before the peak guard
+ * and `mix` (`applyVocoderStage` adds those).
+ */
+export function channelVocode(
+  mod: Float64Array,
+  cars: readonly Float64Array[],
+  control: VocoderControl,
+): Float64Array[] {
+  const { settings: p, sampleRate: sr, origin, seed } = control;
+  const n = Math.min(mod.length, ...cars.map((c) => c.length));
+  const { bands, ratio } = bankDesign(p, sr);
+  const nb = bands.length;
+  const widthCurve = control.curves.width;
+  // Width automation re-designs the band filters per block.
+  const designs = new Map<number, Biquad[]>();
+  const filtersFor = (width: number): Biquad[] => {
+    let known = designs.get(width);
+    if (!known) {
+      const octaves = Math.log2(ratio) * width * 1.55;
+      known = bands.map((b) =>
+        bandpass(Math.min(b.hz, 0.45 * sr), octaves, sr),
+      );
+      designs.set(width, known);
+    }
+    return known;
+  };
+  const filterAt = (k: number, offset: number) =>
+    widthCurve
+      ? (i: number): Biquad =>
+          filtersFor(widthCurve[Math.min(n - 1, i + offset)]!)[k]!
+      : undefined;
+  const gate = gateCurve(mod.subarray(0, n), sr, control.gateDb);
+  if (gate && control.hold) holdCurve(gate, control.hold);
+  const unvoicedOn = p.unvoiced > 0 || control.curves.unvoiced !== undefined;
+  const u = unvoicedOn
+    ? unvoicedCurve(mod.subarray(0, n), sr, p.sens, origin, gate)
+    : undefined;
+  // Analysis: one envelope per band.
+  const env: Float64Array[] = [];
+  const band = new Float64Array(n);
+  for (let k = 0; k < nb; k += 1) {
+    const b = bands[k]!;
+    if (!b.live) {
+      env.push(new Float64Array(n));
+      continue;
+    }
+    // The modulator advanced by the band's delay, zero past its end.
+    const from = Math.min(b.advance, mod.length);
+    const take = Math.min(n, mod.length - from);
+    band.set(mod.subarray(from, from + take));
+    band.fill(0, take);
+    runBandTwice(band, b.filter, filterAt(k, b.advance));
+    const e = followVarying(
+      band,
+      p.attack,
+      p.release,
+      control.curves.release,
+      sr,
+      control.hold,
+    );
+    if (gate) multiplyInto(e, gate);
+    env.push(e);
+  }
+  const shiftOf = (i: number): number =>
+    at(control, "formant", i) / 12 / Math.log2(ratio);
+  const staticShift = control.curves.formant ? undefined : shiftOf(0);
+  const synthEnv = (k: number, i: number): number => {
+    const pos = k - (staticShift ?? shiftOf(i));
+    const i0 = Math.floor(pos);
+    const fr = pos - i0;
+    const a = i0 >= 0 && i0 < nb ? env[i0]![i]! : 0;
+    const b = i0 + 1 >= 0 && i0 + 1 < nb ? env[i0 + 1]![i]! : 0;
+    return a * (1 - fr) + b * fr;
+  };
+  const scale = channelMakeup(p.bands, p.width);
+  const depthCurve = control.curves.depth;
+  const shape = (e: number, i: number): number => {
+    const depth = depthCurve ? depthCurve[i]! : p.depth;
+    return depth === 1 ? e : e ** depth * REF ** (1 - depth);
+  };
+  const hiss =
+    p.hiss > 0 || control.curves.hiss ? hissPath(mod, n, sr) : undefined;
+  const zeros = new Float64Array(n);
+  const outs: Float64Array[] = [];
+  for (const car of cars) {
+    const carrier = car.slice(0, n);
+    if (u) blendUnvoiced(carrier, u, control, seed, origin, sr);
+    const out = new Float64Array(n);
+    const syn = new Float64Array(n);
+    for (let k = 0; k < nb; k += 1) {
+      const b = bands[k]!;
+      if (!b.live) continue;
+      syn.set(carrier);
+      runBandTwice(syn, b.filter, filterAt(k, 0));
+      // The envelope this band reads: a fixed pair of analysis bands and
+      // weight unless the formant is automated (same arithmetic as
+      // `synthEnv`, without a call per sample).
+      let ea: Float64Array = zeros;
+      let eb: Float64Array = zeros;
+      let fr = 0;
+      if (staticShift !== undefined) {
+        const pos = k - staticShift;
+        const i0 = Math.floor(pos);
+        fr = pos - i0;
+        if (i0 >= 0 && i0 < nb) ea = env[i0]!;
+        if (i0 + 1 >= 0 && i0 + 1 < nb) eb = env[i0 + 1]!;
+      }
+      const ec = p.enhance
+        ? followVarying(syn, p.attack, p.release, control.curves.release, sr)
+        : undefined;
+      if (staticShift !== undefined && depthCurve === undefined)
+        mixBandFixed(out, syn, ea, eb, fr, ec, p.depth, scale);
+      else
+        for (let i = 0; i < n; i += 1) {
+          const level = shape(synthEnv(k, i), i);
+          if (ec) {
+            const g = level / (ec[i]! + 1e-5);
+            out[i]! += syn[i]! * Math.min(g, 1e3) * scale;
+          } else out[i]! += syn[i]! * level * 8 * scale;
+        }
+    }
+    if (hiss)
+      for (let i = 0; i < n; i += 1)
+        out[i]! += at(control, "hiss", i) * hiss[i]! * (gate ? gate[i]! : 1);
+    outs.push(out);
+  }
+  return outs;
+}

package/src/audio/vocoder/carrier.ts

@@ -0,0 +1,165 @@
+/**
+ * Built-in carriers for instrument `vocoder` (0.7): saw, supersaw, pulse or
+ * noise, pitched by the track's performed notes, the song's chord timeline
+ * or a drone at `root`, through the track tuning. PolyBLEP edges (the synth
+ * oscillators' residual); supersaw unison copies alternate left and right
+ * on a stereo carrier. Phases are seeded from the note (never Math.random);
+ * noise is keyed to the absolute song sample.
+ */
+import type { PerformedNote } from "../../../core/expression.ts";
+import { noteHz, type TuningTable } from "../../../core/tuning.ts";
+import type { ResolvedVocoder } from "../../../core/vocoder.ts";
+import { unit } from "../dsp/rng.ts";
+import { polyBlep } from "../synth/oscillators.ts";
+
+/** Unison copies of a supersaw, in units of `spread` semitones. */
+const UNISON = Object.freeze([0, -0.73, 0.73, -1.67, 1.67, -2.67, 2.67]);
+/** Short fades so carrier notes never click (the vocoder adds no envelope). */
+const FADE_SECONDS = 0.004;
+
+export type CarrierSpan = Readonly<{
+  start: number;
+  length: number;
+  pitches: readonly number[];
+  /** Pitch offset in cents at `t` seconds from the span start (glide, bend, vibrato). */
+  cents?: (t: number) => number;
+  velocity: number;
+  seed: number;
+  /**
+   * Phase runs on the absolute song sample (chord and drone spans), so a
+   * window that cuts into the span hears the same wave as one pass.
+   */
+  absolute?: boolean;
+}>;
+
+export type CarrierOptions = Readonly<{
+  sampleRate: number;
+  /** Absolute song sample of index 0 (noise only). */
+  origin: number;
+  seed: number;
+  tuning?: TuningTable;
+}>;
+
+/**
+ * Adds one span (one note, chord or drone segment) of carrier into `left`
+ * (and `right`). Supersaw copies after the centre alternate channels.
+ */
+export function renderCarrierSpan(
+  left: Float64Array,
+  right: Float64Array | undefined,
+  span: CarrierSpan,
+  settings: Pick<ResolvedVocoder, "carrier" | "spread">,
+  options: CarrierOptions,
+): void {
+  const { sampleRate } = options;
+  const end = Math.min(left.length, span.start + span.length);
+  const begin = Math.max(0, span.start);
+  if (end <= begin) return;
+  const fade = Math.max(1, Math.round(FADE_SECONDS * sampleRate));
+  const level = 0.3 * (0.4 + 0.6 * Math.max(0, Math.min(1, span.velocity)));
+  const envelope = (i: number): number => {
+    const a = i - span.start;
+    const b = span.start + span.length - i;
+    return Math.min(1, a / fade, b / fade);
+  };
+  if (settings.carrier === "noise") {
+    for (let i = begin; i < end; i += 1) {
+      const v = (unit(options.seed, options.origin + i, 7) * 2 - 1) * 0.5;
+      const e = envelope(i) * level;
+      left[i]! += v * e;
+      if (right) right[i]! += v * e;
+    }
+    return;
+  }
+  const copies = settings.carrier === "supersaw" ? UNISON : [0];
+  const voices = span.pitches.length * copies.length;
+  const norm = 1 / Math.sqrt(Math.max(1, voices));
+  span.pitches.forEach((pitch, p) => {
+    const base = noteHz(pitch, undefined, options.tuning);
+    const bend = span.cents;
+    copies.forEach((offset, c) => {
+      const hz = base * 2 ** ((offset * settings.spread) / 12);
+      let dt = hz / sampleRate;
+      if (!(dt > 0 && dt < 0.5)) return;
+      let phase =
+        settings.carrier === "supersaw" ? unit(span.seed, p * 8 + c, 3) : 0;
+      // Phase at `begin` (a span that starts before the buffer), or on the
+      // absolute song sample for a span a render window may cut into.
+      phase = span.absolute
+        ? (phase + (((options.origin + begin) * dt) % 1)) % 1
+        : (phase + (begin - span.start) * dt) % 1;
+      const weight = (c === 0 ? 1 : 0.6) * norm * level;
+      const side = c === 0 ? 0 : c % 2 === 1 ? -1 : 1;
+      for (let i = begin; i < end; i += 1) {
+        // Bends are read every 32 samples (control rate).
+        if (bend && (i - begin) % 32 === 0)
+          dt = Math.min(
+            0.49,
+            (hz * 2 ** (bend((i - span.start) / sampleRate) / 1200)) /
+              sampleRate,
+          );
+        const v =
+          settings.carrier === "pulse"
+            ? (phase < 0.5 ? 1 : -1) +
+              polyBlep(phase, dt) -
+              polyBlep((phase + 0.5) % 1, dt)
+            : 2 * phase - 1 - polyBlep(phase, dt);
+        const s = v * weight * envelope(i);
+        if (!right || side === 0) {
+          left[i]! += s;
+          if (right) right[i]! += s;
+        } else if (side < 0) left[i]! += s * 1.4;
+        else right[i]! += s * 1.4;
+        phase += dt;
+        if (phase >= 1) phase -= 1;
+      }
+    });
+  });
+}
+
+/** Spans for `follow: notes`: one per performed note. */
+export function noteSpans(
+  notes: readonly PerformedNote[],
+  span: (note: PerformedNote) => { start: number; length: number },
+  seedOf: (note: PerformedNote) => number,
+): CarrierSpan[] {
+  return notes.map((note) => {
+    const { start, length } = span(note);
+    const cents = note.performance?.cents;
+    return {
+      start,
+      length,
+      pitches: [note.pitch],
+      ...(cents ? { cents } : {}),
+      velocity: note.velocity,
+      seed: seedOf(note),
+    };
+  });
+}
+
+/**
+ * Spans for `follow: chords`: the chord timeline's pitch classes voiced in
+ * the octave from `root` upward, one span per chord change; no chord, no
+ * carrier.
+ */
+export function chordSpans(
+  changes: readonly Readonly<{
+    start: number;
+    end: number;
+    pcs: readonly number[];
+  }>[],
+  root: number,
+  seed: number,
+): CarrierSpan[] {
+  return changes
+    .filter((change) => change.pcs.length > 0 && change.end > change.start)
+    .map((change) => ({
+      start: change.start,
+      length: change.end - change.start,
+      pitches: change.pcs.map((pc) => root + ((((pc - root) % 12) + 12) % 12)),
+      velocity: 0.8,
+      // One seed for the track: a render window's chord index differs.
+      seed,
+      absolute: true,
+    }));
+}

package/src/audio/vocoder/control.ts

@@ -0,0 +1,68 @@
+/**
+ * Control values for one vocoder render: the resolved settings plus, for
+ * each automated parameter, a per-sample curve read once per 32-sample block
+ * on the absolute song grid (so a window and the full render agree).
+ */
+import type { ResolvedVocoder } from "../../../core/vocoder.ts";
+
+export const VOCODER_BLOCK = 32;
+
+export type VocoderCurves = Partial<
+  Record<
+    | "spread"
+    | "width"
+    | "release"
+    | "formant"
+    | "unvoiced"
+    | "hiss"
+    | "depth"
+    | "mix"
+    | "gain",
+    Float64Array
+  >
+>;
+
+export type VocoderControl = Readonly<{
+  settings: ResolvedVocoder;
+  sampleRate: number;
+  /** Absolute song sample of index 0. */
+  origin: number;
+  seed: number;
+  /** Gate threshold in dBFS (auto already resolved); -120 is off. */
+  gateDb: number;
+  curves: VocoderCurves;
+  /** Non-zero where the envelopes hold (freeze on, or its lane at 1). */
+  hold?: Uint8Array;
+}>;
+
+/** A value at sample `i`: its curve when automated, else the static value. */
+export function at(
+  control: VocoderControl,
+  name: keyof VocoderCurves,
+  i: number,
+): number {
+  const curve = control.curves[name];
+  return curve ? curve[i]! : (control.settings[name] as number);
+}
+
+/**
+ * Per-sample curve from `valueAt(index)`, sampled at each block's first
+ * song-grid sample (clamped to 0) and held for the block.
+ */
+export function blockCurve(
+  n: number,
+  origin: number,
+  valueAt: (index: number) => number,
+): Float64Array {
+  const out = new Float64Array(n);
+  const phase = ((origin % VOCODER_BLOCK) + VOCODER_BLOCK) % VOCODER_BLOCK;
+  let i = 0;
+  let start = -phase;
+  while (i < n) {
+    const end = Math.min(n, start + VOCODER_BLOCK);
+    const value = valueAt(start);
+    for (; i < end; i += 1) out[i] = value;
+    start += VOCODER_BLOCK;
+  }
+  return out;
+}

package/src/audio/vocoder/detect.ts

@@ -0,0 +1,50 @@
+/**
+ * The vocoder's detectors (0.7): the unvoiced curve (fricatives and
+ * breaths get a noise carrier). A sample counts as unvoiced when its share
+ * of energy above 4 kHz passes a `sens`-scaled threshold AND the modulator
+ * is aperiodic (low normalised autocorrelation), and only while the gate is
+ * open: either cue alone misfires on bright vowels or on reverb tails.
+ */
+import { highpass, runBiquad } from "../dsp/bandbank.ts";
+import { follow, followCoef } from "../dsp/follow.ts";
+import { periodicityCurve } from "../dsp/periodicity.ts";
+
+export function unvoicedCurve(
+  mod: Float64Array,
+  sampleRate: number,
+  sens: number,
+  origin = 0,
+  gate?: Float64Array,
+): Float64Array {
+  const hp = Float64Array.from(mod);
+  const filter = highpass(4000, sampleRate);
+  runBiquad(filter, hp);
+  runBiquad(filter, hp);
+  const high = follow(hp, 0.002, 0.02, sampleRate);
+  const full = follow(mod, 0.002, 0.02, sampleRate);
+  const periodic = periodicityCurve(mod, sampleRate, origin);
+  const threshold = 0.5 - 0.35 * sens;
+  const out = new Float64Array(mod.length);
+  const c = followCoef(0.004, sampleRate);
+  let s = 0;
+  for (let i = 0; i < mod.length; i += 1) {
+    const ratio = full[i]! > 1e-4 ? high[i]! / full[i]! : 0;
+    const share = Math.min(1, Math.max(0, (ratio - threshold) / 0.15));
+    const aperiodic = Math.min(1, Math.max(0, (0.75 - periodic[i]!) / 0.2));
+    const t = share * aperiodic * (gate ? gate[i]! : 1);
+    s = c * s + (1 - c) * t;
+    out[i] = s;
+  }
+  return out;
+}
+
+/** The modulator above 5 kHz, gated: the `hiss` path that keeps "s" crisp. */
+export function hissPath(
+  mod: Float64Array,
+  n: number,
+  sampleRate: number,
+): Float64Array {
+  const hp = mod.slice(0, n);
+  runBiquad(highpass(5000, sampleRate), hp);
+  return hp;
+}