@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/vocoder/index.ts

@@ -0,0 +1,304 @@
+/**
+ * The vocoder stage and its built-in carrier (0.7). `applyVocoder` runs
+ * right after a carrier track's voice renders into `dry` (and `dryR`), before
+ * its FX_CHAIN: the modulator (another track's tap) shapes the carrier
+ * through a channel bank or an LPC talkbox. Output gain is fixed by the
+ * layout times `gain`, then a stateless soft peak guard, then `mix`; nothing
+ * is measured over the render span, so a window equals the full render.
+ * `VOCODER_ENGINE` plays instrument `vocoder`: a saw, supersaw, pulse or
+ * noise carrier following the track's notes, the song's chords or a drone.
+ */
+import type { PerformedNote } from "../../../core/expression.ts";
+import type { AutomationPoint, Track } from "../../../core/score.ts";
+import {
+  resolveVocoder,
+  vocoderTailSeconds,
+  VOCODER_INSTRUMENT,
+  VOCODER_LANE_PARAMS,
+  type ResolvedVocoder,
+} from "../../../core/vocoder.ts";
+import { seedHash } from "../dsp/rng.ts";
+import { interpolateAutomation } from "../effects/common.ts";
+import { chordAt, chordTimeline } from "../granular.ts";
+import type { EngineContext, InstrumentEngine } from "../instruments.ts";
+import type { RenderContext } from "../wav.ts";
+import { warpedSpan } from "../warp.ts";
+import { channelVocode } from "./bank.ts";
+import {
+  chordSpans,
+  noteSpans,
+  renderCarrierSpan,
+  type CarrierSpan,
+} from "./carrier.ts";
+import {
+  blockCurve,
+  type VocoderControl,
+  type VocoderCurves,
+} from "./control.ts";
+import { talkboxVocode } from "./talkbox.ts";
+import { quietHold } from "../dsp/follow.ts";
+
+export { autoGateDb } from "../dsp/follow.ts";
+
+/** Stateless soft knee: identity below 0.9, ceiling 1.0 (window-safe). */
+export function peakGuard(x: Float64Array): void {
+  for (let i = 0; i < x.length; i += 1) {
+    const v = x[i]!;
+    const a = Math.abs(v);
+    if (a > 0.9) x[i] = Math.sign(v) * (0.9 + 0.1 * Math.tanh((a - 0.9) / 0.1));
+  }
+}
+
+type LaneContext = Pick<
+  RenderContext,
+  "sampleRate" | "samplesPerTick" | "warp" | "seedSeconds"
+>;
+
+/** Absolute song sample of a render's index 0. */
+export function originOf(
+  context: Pick<RenderContext, "sampleRate" | "seedSeconds">,
+): number {
+  return Math.round((context.seedSeconds ?? 0) * context.sampleRate);
+}
+
+/** The noise seed: the stored one, else a hash of the track id. */
+export function vocoderSeed(track: Track, settings: ResolvedVocoder): number {
+  return settings.seed ?? seedHash(`vocoder:${track.id}`);
+}
+
+function laneOf(
+  track: Track,
+  param: string,
+): readonly AutomationPoint[] | undefined {
+  const lanes = track.fxAutomation as
+    Readonly<Record<string, readonly AutomationPoint[]>> | undefined;
+  const points = lanes?.[`vocoder-${param}`];
+  return points && points.length > 0 ? points : undefined;
+}
+
+function tickAt(context: LaneContext, index: number): number {
+  return context.warp
+    ? context.warp.tick(Math.max(0, index))
+    : index / context.samplesPerTick;
+}
+
+/** The control values for one render: settings, lane curves, hold. */
+export function vocoderControl(
+  track: Track,
+  n: number,
+  context: LaneContext,
+  gateDb: number,
+  mod?: Float64Array,
+): VocoderControl {
+  const settings = resolveVocoder(track.vocoder);
+  const origin = originOf(context);
+  const curves: Record<string, Float64Array> = {};
+  let hold: Uint8Array | undefined;
+  for (const { param } of VOCODER_LANE_PARAMS) {
+    const points = laneOf(track, param);
+    if (!points) continue;
+    const fallback =
+      param === "freeze"
+        ? settings.freeze
+          ? 1
+          : 0
+        : (settings as Record<string, unknown>)[param];
+    const curve = blockCurve(n, origin, (index) =>
+      interpolateAutomation(points, tickAt(context, index), fallback as number),
+    );
+    if (param === "freeze") {
+      hold = new Uint8Array(n);
+      for (let i = 0; i < n; i += 1) hold[i] = curve[i]! >= 0.5 ? 1 : 0;
+    } else curves[param] = curve;
+  }
+  // A static freeze holds the last sung vowel through every rest (a hold
+  // from sample 0 would freeze the silence before the voice comes in).
+  if (!hold && settings.freeze)
+    hold = mod
+      ? quietHold(mod, n, context.sampleRate, gateDb)
+      : new Uint8Array(n).fill(1);
+  return {
+    settings,
+    sampleRate: context.sampleRate,
+    origin,
+    seed: vocoderSeed(track, settings),
+    gateDb,
+    curves: curves as VocoderCurves,
+    ...(hold ? { hold } : {}),
+  };
+}
+
+/**
+ * Vocodes `dry` (and `dryR`) in place with modulator `mod` (the source's
+ * mono tap over the same span, plus any lookahead past it).
+ */
+export function applyVocoder(
+  dry: Float64Array,
+  dryR: Float64Array | undefined,
+  mod: Float64Array,
+  track: Track,
+  context: LaneContext,
+  gateDb: number,
+): void {
+  const n = dry.length;
+  const cars = dryR ? [dry, dryR] : [dry];
+  const padded =
+    mod.length >= n
+      ? mod
+      : (() => {
+          const out = new Float64Array(n);
+          out.set(mod);
+          return out;
+        })();
+  const control = vocoderControl(track, n, context, gateDb, padded);
+  const outs =
+    control.settings.mode === "talkbox"
+      ? talkboxVocode(padded, cars, control)
+      : channelVocode(padded, cars, control);
+  const { curves, settings } = control;
+  outs.forEach((out, c) => {
+    const car = cars[c]!;
+    const gain = curves.gain;
+    if (gain || settings.gain !== 0) {
+      const fixed = 10 ** (settings.gain / 20);
+      for (let i = 0; i < n; i += 1)
+        out[i] = out[i]! * (gain ? 10 ** (gain[i]! / 20) : fixed);
+    }
+    peakGuard(out);
+    const mix = curves.mix;
+    if (mix || settings.mix < 1)
+      for (let i = 0; i < n; i += 1) {
+        const m = mix ? mix[i]! : settings.mix;
+        out[i] = out[i]! * m + car[i]! * (1 - m);
+      }
+    car.set(out.subarray(0, n));
+  });
+}
+
+function noteSpanOf(
+  note: PerformedNote,
+  context: EngineContext,
+): { start: number; length: number } {
+  if (context.warp)
+    return warpedSpan(context.warp, note.startTick, note.durationTicks);
+  const perTick =
+    (60 * context.sampleRate) / (context.tempoBpm * context.ticksPerBeat);
+  return {
+    start: Math.max(0, Math.floor(note.startTick * perTick)),
+    length: Math.max(1, Math.floor(note.durationTicks * perTick)),
+  };
+}
+
+function sampleAtTick(context: EngineContext, tick: number): number {
+  if (context.warp) return warpedSpan(context.warp, tick, 0).start;
+  return Math.max(0, Math.floor(tick * context.samplesPerTick));
+}
+
+type ChordChange = { start: number; end: number; pcs: readonly number[] };
+
+const samePcs = (a: readonly number[], b: readonly number[]) =>
+  a.length === b.length && a.every((pc, index) => pc === b[index]);
+
+/**
+ * Chord changes as the carrier holds them: neighbours with the same pitch
+ * classes join (a staccato bass under a held chord never re-strikes the
+ * pad), and a silence shorter than `hold` samples holds the chord before it.
+ */
+export function mergeChordChanges(
+  changes: readonly ChordChange[],
+  hold: number,
+): ChordChange[] {
+  const merged: ChordChange[] = [];
+  for (const change of changes) {
+    if (change.end <= change.start) continue;
+    const last = merged[merged.length - 1];
+    if (
+      last &&
+      (samePcs(last.pcs, change.pcs) ||
+        (change.pcs.length === 0 &&
+          last.pcs.length > 0 &&
+          change.end - change.start < hold))
+    ) {
+      last.end = change.end;
+      continue;
+    }
+    merged.push({ ...change });
+  }
+  return merged;
+}
+
+/** The built-in carrier's spans for a track. */
+export function carrierSpans(
+  notes: readonly PerformedNote[],
+  track: Track,
+  settings: ResolvedVocoder,
+  context: EngineContext,
+): CarrierSpan[] {
+  const seed = vocoderSeed(track, settings);
+  if (settings.follow === "drone")
+    return [
+      {
+        start: 0,
+        length: context.samples,
+        pitches: [settings.root],
+        velocity: 0.8,
+        seed,
+        absolute: true,
+      },
+    ];
+  if (settings.follow === "chords") {
+    const timeline = chordTimeline(context.score);
+    const changes: { start: number; end: number; pcs: readonly number[] }[] =
+      [];
+    const ticks = [0, ...timeline.ticks.filter((tick) => tick > 0)];
+    ticks.forEach((tick, index) => {
+      const next = ticks[index + 1];
+      changes.push({
+        start: sampleAtTick(context, tick),
+        end: next === undefined ? context.samples : sampleAtTick(context, next),
+        pcs: chordAt(timeline, tick),
+      });
+    });
+    return chordSpans(
+      mergeChordChanges(changes, Math.round(0.05 * context.sampleRate)),
+      settings.root,
+      seed,
+    );
+  }
+  return noteSpans(
+    notes,
+    (note) => noteSpanOf(note, context),
+    (note) => seedHash(`${seed}:${note.id}`),
+  ).map((span, index) => {
+    const cents = notes[index]!.cents;
+    if (!cents) return span;
+    const curve = span.cents;
+    return {
+      ...span,
+      cents: curve ? (t: number) => cents + curve(t) : () => cents,
+    };
+  });
+}
+
+/** Instrument `vocoder`: the built-in carrier (its field is `vocoder`). */
+export const VOCODER_ENGINE: InstrumentEngine = {
+  id: VOCODER_INSTRUMENT,
+  field: "vocoder",
+  render(dry, dryR, notes, track, context) {
+    const settings = resolveVocoder(track.vocoder);
+    const origin = originOf(context);
+    for (const span of carrierSpans(notes, track, settings, context))
+      renderCarrierSpan(dry, dryR, span, settings, {
+        sampleRate: context.sampleRate,
+        origin,
+        seed: span.seed,
+        ...(context.tuning ? { tuning: context.tuning } : {}),
+      });
+  },
+  tailSeconds(track) {
+    return vocoderTailSeconds(track.vocoder);
+  },
+  stereo(track) {
+    return resolveVocoder(track.vocoder).carrier === "supersaw";
+  },
+};

package/src/audio/vocoder/talkbox.ts

@@ -0,0 +1,143 @@
+/**
+ * The LPC talkbox (0.7, after mda Talkbox): per 20 ms sqrt-Hann frame at
+ * 50 % overlap, the modulator's spectral envelope (Levinson-Durbin, order
+ * round(sr / 2000), pre-emphasised) filters the pre-whitened carrier. Frames
+ * sit on the absolute song grid. Formant shift resamples the analysis frame
+ * (±12 st) and a per-frame energy normaliser, measured after de-emphasis,
+ * keeps the frame at the unshifted modulator frame's energy.
+ */
+import { gateCurve, holdCurve } from "../dsp/follow.ts";
+import { autocorrelate, levinson } from "../dsp/lpc.ts";
+import { TALKBOX_FORMANT_MAX } from "../../../core/vocoder.ts";
+import { noiseSample } from "./bank.ts";
+import type { VocoderControl } from "./control.ts";
+import { at } from "./control.ts";
+import { hissPath, unvoicedCurve } from "./detect.ts";
+
+/** Fixed talkbox makeup (measured once on the voice fixture). */
+export const TALKBOX_MAKEUP = 0.97;
+
+const posMod = (a: number, m: number): number => ((a % m) + m) % m;
+
+export function talkboxVocode(
+  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 N = 2 * Math.round(0.01 * sr);
+  const hop = N / 2;
+  const order = Math.max(8, Math.round(sr / 2000));
+  const corder = 12;
+  const win = new Float64Array(N);
+  const sq = new Float64Array(N);
+  for (let i = 0; i < N; i += 1) {
+    win[i] = 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / N);
+    sq[i] = Math.sqrt(win[i]!);
+  }
+  const acc = cars.map(() => new Float64Array(n + N));
+  const pre = new Float64Array(n);
+  for (let i = 0; i < n; i += 1)
+    pre[i] = mod[i]! - 0.97 * (i > 0 ? mod[i - 1]! : 0);
+  const mf = new Float64Array(N);
+  const cf = new Float64Array(N);
+  const y = new Float64Array(N);
+  const r = new Float64Array(order + 1);
+  const a = new Float64Array(order + 1);
+  const rc = new Float64Array(corder + 1);
+  const ac = new Float64Array(corder + 1);
+  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;
+  let heldMe0 = 0;
+  for (let start = -posMod(origin, hop) - hop; start < n; start += hop) {
+    const centre = Math.min(n - 1, Math.max(0, start + hop));
+    const st = Math.max(
+      -TALKBOX_FORMANT_MAX,
+      Math.min(TALKBOX_FORMANT_MAX, at(control, "formant", centre)),
+    );
+    const shift = 2 ** (st / 12);
+    // freeze: a held frame reuses the last analysed filter and level
+    const held = heldMe0 > 0 && control.hold?.[centre] === 1;
+    let me = held ? 1 : 0;
+    let me0 = held ? heldMe0 : 0;
+    for (let i = 0; !held && i < N; i += 1) {
+      const j = start + i;
+      const jj = start + hop + (i - hop) * shift;
+      const k0 = Math.floor(jj);
+      const fr = jj - k0;
+      const m =
+        k0 >= 0 && k0 + 1 < n ? pre[k0]! * (1 - fr) + pre[k0 + 1]! * fr : 0;
+      const g = gate && j >= 0 && j < n ? gate[j]! : 1;
+      mf[i] = m * win[i]! * g;
+      me += mf[i]! * mf[i]!;
+      const raw = (j >= 0 && j < n ? mod[j]! : 0) * win[i]! * g;
+      me0 += raw * raw;
+    }
+    if (me < 1e-10 || me0 < 1e-10) continue;
+    if (!held) {
+      levinson(autocorrelate(mf, order, r, sr), order, a);
+      heldMe0 = me0;
+    }
+    for (let c = 0; c < cars.length; c += 1) {
+      const car = cars[c]!;
+      for (let i = 0; i < N; i += 1) {
+        const j = start + i;
+        let v = j >= 0 && j < n ? car[j]! : 0;
+        if (u && j >= 0 && j < n) {
+          const w = u[j]! * at(control, "unvoiced", j);
+          v = v * (1 - w) + noiseSample(seed, origin + j) * 0.5 * w;
+        }
+        cf[i] = v * sq[i]!;
+      }
+      if (p.enhance) {
+        levinson(autocorrelate(cf, corder, rc, sr), corder, ac);
+        for (let i = N - 1; i >= 0; i -= 1) {
+          let s = cf[i]!;
+          for (let j = 1; j <= corder && j <= i; j += 1)
+            s += ac[j]! * cf[i - j]!;
+          cf[i] = s;
+        }
+      }
+      let ce = 0;
+      for (let i = 0; i < N; i += 1) ce += cf[i]! * cf[i]!;
+      if (ce <= 1e-12) continue;
+      for (let i = 0; i < N; i += 1) {
+        let s = cf[i]!;
+        for (let j = 1; j <= order && j <= i; j += 1) s -= a[j]! * y[i - j]!;
+        y[i] = s;
+      }
+      let ye = 0;
+      let de = 0;
+      for (let i = 0; i < N; i += 1) {
+        de = y[i]! * sq[i]! + 0.97 * de;
+        const v = de * sq[i]!;
+        ye += v * v;
+      }
+      const g = ye > 1e-20 ? Math.sqrt(me0 / ye) * TALKBOX_MAKEUP : 0;
+      const o = acc[c]!;
+      for (let i = 0; i < N; i += 1) {
+        const j = start + i;
+        if (j >= 0) o[j]! += y[i]! * sq[i]! * g;
+      }
+    }
+  }
+  const hiss =
+    p.hiss > 0 || control.curves.hiss ? hissPath(mod, n, sr) : undefined;
+  return acc.map((o) => {
+    const res = new Float64Array(n);
+    let dd = 0;
+    for (let i = 0; i < n; i += 1) {
+      dd = o[i]! + 0.97 * dd;
+      res[i] = dd;
+    }
+    if (hiss)
+      for (let i = 0; i < n; i += 1)
+        res[i]! += at(control, "hiss", i) * hiss[i]! * (gate ? gate[i]! : 1);
+    return res;
+  });
+}