@hraness/dawg 0.6.1 → 0.8.0

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;
+}

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";
+  },
+};