@hraness/dawg 0.2.0 → 0.4.0

package/src/audio/click.ts

@@ -0,0 +1,125 @@
+/**
+ * The click track (metronome): an accented downbeat, a beat click and a
+ * lighter subdivision click at the transport tempo and time signature.
+ *
+ * The click is a monitoring bus only. The engine mixes it into the live
+ * stream; it is never part of a loop render, `dawg render` or an export, and
+ * nothing here touches the score.
+ */
+
+export type ClickLevel = "accent" | "beat" | "sub";
+
+export type ClickSettings = Readonly<{
+  /** 0..1 output level. */
+  volume: number;
+  beatsPerBar: number;
+  /** Clicks per beat: 1 = quarters, 2 = eighths, 4 = sixteenths. */
+  subdivision: number;
+}>;
+
+export const DEFAULT_CLICK_VOLUME = 0.6;
+export const MAX_SUBDIVISION = 4;
+
+/** One click due inside a block of stream frames. */
+export type ClickEvent = Readonly<{
+  /** Frame offset inside the block. */
+  offset: number;
+  level: ClickLevel;
+  /** Absolute step (beat × subdivision); negative during a count-in. */
+  step: number;
+}>;
+
+/** Level of absolute step `step` (beat × subdivision). */
+export function clickLevel(
+  step: number,
+  beatsPerBar: number,
+  subdivision: number,
+): ClickLevel {
+  const perBar = Math.max(1, beatsPerBar) * Math.max(1, subdivision);
+  const inBar = ((step % perBar) + perBar) % perBar;
+  if (inBar === 0) return "accent";
+  return inBar % Math.max(1, subdivision) === 0 ? "beat" : "sub";
+}
+
+/**
+ * Clicks whose time falls in the half-open beat span [fromBeat, toBeat)
+ * covered by `frames` stream frames. Contiguous blocks never repeat or skip
+ * a click, and a jump (seek, loop wrap) never fires a stray mid-beat click.
+ */
+export function clicksIn(
+  fromBeat: number,
+  toBeat: number,
+  frames: number,
+  settings: Pick<ClickSettings, "beatsPerBar" | "subdivision">,
+): ClickEvent[] {
+  if (!(toBeat > fromBeat) || frames <= 0) return [];
+  const subdivision = Math.max(
+    1,
+    Math.min(MAX_SUBDIVISION, Math.round(settings.subdivision)),
+  );
+  const events: ClickEvent[] = [];
+  const span = toBeat - fromBeat;
+  // Half-open: a click exactly at `toBeat` belongs to the next block, whose
+  // `fromBeat` is computed identically, so it fires once.
+  const first = Math.ceil(fromBeat * subdivision) + 0;
+  for (let step = first; step / subdivision < toBeat; step += 1) {
+    const offset = Math.floor(
+      ((step / subdivision - fromBeat) / span) * frames,
+    );
+    if (offset < 0 || offset >= frames) continue;
+    events.push({
+      offset,
+      step,
+      level: clickLevel(step, settings.beatsPerBar, subdivision),
+    });
+    if (events.length > 64) break;
+  }
+  return events;
+}
+
+const CLICK_TONES: Readonly<
+  Record<ClickLevel, { hz: number; gain: number; ms: number }>
+> = Object.freeze({
+  accent: { hz: 1760, gain: 1, ms: 45 },
+  beat: { hz: 1320, gain: 0.7, ms: 35 },
+  sub: { hz: 990, gain: 0.35, ms: 25 },
+});
+
+/** Mono click waveforms (−1..1) for each level at `sampleRate`. */
+export function clickSounds(
+  sampleRate: number,
+): Readonly<Record<ClickLevel, Float32Array>> {
+  const make = (level: ClickLevel): Float32Array => {
+    const tone = CLICK_TONES[level];
+    const frames = Math.max(1, Math.round((tone.ms * sampleRate) / 1000));
+    const out = new Float32Array(frames);
+    const attack = Math.max(1, Math.round(0.001 * sampleRate));
+    for (let index = 0; index < frames; index += 1) {
+      const t = index / sampleRate;
+      const decay = Math.exp((-index / frames) * 6);
+      const env = Math.min(1, index / attack) * decay;
+      out[index] = Math.sin(2 * Math.PI * tone.hz * t) * env * tone.gain;
+    }
+    return out;
+  };
+  return { accent: make("accent"), beat: make("beat"), sub: make("sub") };
+}
+
+/** `/click on|off|<volume>` → settings change, or an error message. */
+export function parseClickArgument(
+  argument: string,
+  current: Readonly<{ on: boolean; volume: number }>,
+): { on: boolean; volume: number } | { error: string } {
+  const value = argument.trim().toLowerCase();
+  if (value === "" || value === "toggle")
+    return { on: !current.on, volume: current.volume };
+  if (value === "on") return { on: true, volume: current.volume };
+  if (value === "off") return { on: false, volume: current.volume };
+  const percent = value.endsWith("%");
+  const number = Number(percent ? value.slice(0, -1) : value);
+  if (!Number.isFinite(number) || number < 0)
+    return { error: "usage: /click on|off|<volume 0..1 or 0..100%>" };
+  const volume = percent || number > 1 ? number / 100 : number;
+  if (volume > 1) return { error: "click volume is 0..1 (or 0..100%)" };
+  return { on: volume > 0, volume };
+}

package/src/audio/effects/bus.ts

@@ -0,0 +1,147 @@
+/**
+ * Shared orbit buses (Strudel orbits): tracks whose `fx.orbit` sets
+ * `shared` send into one delay and one reverb per orbit instead of running
+ * their own.
+ *
+ * Each member's finished stem (its chain up to, not including, delay and
+ * reverb) is sent to the bus delay at its `delay.mix` and to the bus reverb
+ * at its `reverb.mix`, both following their mix lanes. The bus delay takes
+ * its time, feedback, ping-pong and highcut from the first member in score
+ * order that has a delay; the bus reverb takes its settings (size, fade,
+ * impulse...) from the first member with a reverb. The two run in parallel
+ * and their wet outputs join the mix after every stem, in orbit order. Both
+ * are linear, so a bus with one member sounds like that track's own delay
+ * and reverb run in parallel.
+ */
+import type { Track } from "../../../core/score.ts";
+import {
+  CONTROL_SAMPLES,
+  interpolateAutomation,
+  type EffectContext,
+} from "./common.ts";
+import { applyDelay, applyReverb } from "./space.ts";
+
+/** The orbit whose shared bus a track sends to, if any. */
+export function sharedOrbitOf(track: Track | undefined): number | undefined {
+  const orbit = track?.fx?.orbit;
+  return orbit?.shared === true ? Number(orbit.orbit) : undefined;
+}
+
+export type OrbitBus = {
+  readonly orbit: number;
+  delayLead?: Track;
+  reverbLead?: Track;
+  readonly delayL: Float64Array;
+  readonly delayR: Float64Array;
+  readonly reverbL: Float64Array;
+  readonly reverbR: Float64Array;
+  /** Member stem keys in send order: the bus output's cache key. */
+  readonly keys: string[];
+};
+
+export function createOrbitBus(orbit: number, samples: number): OrbitBus {
+  return {
+    orbit,
+    delayL: new Float64Array(samples),
+    delayR: new Float64Array(samples),
+    reverbL: new Float64Array(samples),
+    reverbR: new Float64Array(samples),
+    keys: [],
+  };
+}
+
+/** Adds `level(t)·stem` into a send pair; the level steps per control block. */
+function send(
+  outL: Float64Array,
+  outR: Float64Array,
+  stemL: Float64Array,
+  stemR: Float64Array,
+  base: number,
+  lane: readonly Readonly<{ tick: number; value: number }>[],
+  samplesPerTick: number,
+): void {
+  if (base <= 0 && lane.length === 0) return;
+  let level = base;
+  for (let index = 0; index < outL.length; index += 1) {
+    if (lane.length > 0 && index % CONTROL_SAMPLES === 0)
+      level = interpolateAutomation(lane, index / samplesPerTick, base);
+    outL[index]! += stemL[index]! * level;
+    outR[index]! += stemR[index]! * level;
+  }
+}
+
+/** Sends one member's stem to its bus. */
+export function sendToBus(
+  bus: OrbitBus,
+  track: Track,
+  stemL: Float64Array,
+  stemR: Float64Array,
+  context: EffectContext,
+  key: string,
+): void {
+  bus.keys.push(key);
+  if (track.delay) {
+    bus.delayLead ??= track;
+    send(
+      bus.delayL,
+      bus.delayR,
+      stemL,
+      stemR,
+      track.delay.mix,
+      track.delayMixAutomation ?? [],
+      context.samplesPerTick,
+    );
+  }
+  if (track.reverb) {
+    bus.reverbLead ??= track;
+    send(
+      bus.reverbL,
+      bus.reverbR,
+      stemL,
+      stemR,
+      track.reverb.mix,
+      track.fxAutomation?.["reverb-mix"] ?? [],
+      context.samplesPerTick,
+    );
+  }
+}
+
+/**
+ * Runs the bus delay and reverb on their sends, wet only, into a fresh
+ * stereo pair (the send buffers are consumed).
+ */
+export function renderOrbitBus(
+  bus: OrbitBus,
+  context: EffectContext,
+): { left: Float64Array; right: Float64Array } {
+  const left = new Float64Array(bus.delayL.length);
+  const right = new Float64Array(bus.delayL.length);
+  const lead = bus.delayLead;
+  if (lead?.delay) {
+    const unity: Track = {
+      ...lead,
+      delay: { ...lead.delay, mix: 1 },
+      delayMixAutomation: [],
+    };
+    applyDelay(bus.delayL, bus.delayR, unity, context, true);
+    for (let index = 0; index < left.length; index += 1) {
+      left[index]! += bus.delayL[index]!;
+      right[index]! += bus.delayR[index]!;
+    }
+  }
+  const room = bus.reverbLead;
+  if (room?.reverb) {
+    const { "reverb-mix": _lane, ...fxAutomation } = room.fxAutomation ?? {};
+    const unity: Track = {
+      ...room,
+      reverb: { ...room.reverb, mix: 1 },
+      fxAutomation,
+    };
+    applyReverb(bus.reverbL, bus.reverbR, unity, context, true);
+    for (let index = 0; index < left.length; index += 1) {
+      left[index]! += bus.reverbL[index]!;
+      right[index]! += bus.reverbR[index]!;
+    }
+  }
+  return { left, right };
+}

package/src/audio/effects/chain.ts

@@ -0,0 +1,99 @@
+/**
+ * The fixed per-track effects chain (`FX_CHAIN` in core/fx.ts):
+ *
+ *   filter → djf → autofilter → vowel → crush → distort → tremolo →
+ *   compressor → pan → 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.
+ */
+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 { applyCompressor, applyPostgain, applyTremolo } from "./dynamics.ts";
+import {
+  applyAutoFilter,
+  applyDjFilter,
+  applyTrackFilter,
+  applyVowel,
+} from "./filter.ts";
+import { applyChorus, applyLeslie, applyPhaser } from "./modulation.ts";
+import { applyDelay, applyReverb } from "./space.ts";
+
+export { delayTailFor, reverbImpulse, reverbTailFor } from "./space.ts";
+export { interpolateAutomation, type EffectContext } from "./common.ts";
+
+type MonoStage = (
+  buffer: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+) => void;
+type StereoStage = (
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  values: FxValues,
+  context: EffectContext,
+) => void;
+
+const MONO: Readonly<Partial<Record<FxName, MonoStage>>> = Object.freeze({
+  djf: applyDjFilter,
+  autofilter: applyAutoFilter,
+  vowel: applyVowel,
+  crush: applyCrush,
+  distort: applyDistort,
+  tremolo: applyTremolo,
+  compressor: applyCompressor,
+});
+
+const STEREO: Readonly<Partial<Record<FxName, StereoStage>>> = Object.freeze({
+  phaser: applyPhaser,
+  chorus: applyChorus,
+  leslie: applyLeslie,
+  postgain: applyPostgain,
+});
+
+const PAN_INDEX = FX_CHAIN.indexOf("pan");
+
+/** Mono stages, in chain order, on the track's dry voice sum. */
+export function applyMonoChain(
+  buffer: Float64Array,
+  track: Track,
+  context: EffectContext,
+): void {
+  for (const stage of FX_CHAIN.slice(0, PAN_INDEX)) {
+    if (stage === "filter") {
+      applyTrackFilter(buffer, track, context);
+      continue;
+    }
+    const values = track.fx?.[stage as FxName];
+    const apply = MONO[stage as FxName];
+    if (values && apply) apply(buffer, track, values, context);
+  }
+}
+
+/**
+ * Stereo stages, in chain order, after pan. A track on a shared orbit bus
+ * (`sends: false`) skips delay and reverb: the bus applies them to the sum.
+ */
+export function applyStereoChain(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  context: EffectContext,
+  sends = true,
+): void {
+  for (const stage of FX_CHAIN.slice(PAN_INDEX + 1)) {
+    if (stage === "delay") {
+      if (sends) applyDelay(left, right, track, context);
+    } else if (stage === "reverb") {
+      if (sends) applyReverb(left, right, track, context);
+    } else {
+      const values = track.fx?.[stage as FxName];
+      const apply = STEREO[stage as FxName];
+      if (values && apply) apply(left, right, track, values, context);
+    }
+  }
+}

package/src/audio/effects/common.ts

@@ -0,0 +1,251 @@
+/**
+ * Shared DSP building blocks for the track effects chain. Everything is
+ * plain float64 arithmetic in a fixed order with no clocks or ambient
+ * randomness, so a render is byte-identical on every run, cold or cached.
+ *
+ * The DSP in `src/audio/effects/` is dawg's own, written from standard
+ * literature (RBJ Audio EQ Cookbook biquads, Schroeder/Freeverb reverb,
+ * Giannoulis–Massberg–Reiss compressor design, Zölzer DAFX modulation
+ * effects). Parameter names follow Strudel's documentation; no Strudel
+ * source is used.
+ */
+import type { AutomationPoint, Track } from "../../../core/score.ts";
+import type { FxLane, FxValues } from "../../../core/fx.ts";
+import type { DecodedSample } from "../samples.ts";
+
+/** Effect parameters are refreshed at this sample interval. */
+export const CONTROL_SAMPLES = 32;
+
+export type EffectContext = Readonly<{
+  sampleRate: number;
+  samplesPerTick: number;
+  tempoBpm: number;
+  /** Decoded `reverb.ir` samples by track id (built-in impulses need none). */
+  irs?: ReadonlyMap<string, DecodedSample>;
+}>;
+
+/** Resolve a piecewise-linear automation lane, holding the static value before its first point. */
+export function interpolateAutomation(
+  points: readonly AutomationPoint[],
+  tick: number,
+  fallback: number,
+): number {
+  if (points.length === 0 || !Number.isFinite(tick)) return fallback;
+  const first = points[0]!;
+  if (tick < first.tick) return fallback;
+  const last = points[points.length - 1]!;
+  if (tick >= last.tick) return last.value;
+  for (let index = 1; index < points.length; index += 1) {
+    const right = points[index]!;
+    if (tick > right.tick) continue;
+    const left = points[index - 1]!;
+    const span = right.tick - left.tick;
+    const ratio = span <= 0 ? 1 : (tick - left.tick) / span;
+    return left.value + (right.value - left.value) * ratio;
+  }
+  return last.value;
+}
+
+/**
+ * One numeric effect parameter: its static value plus its automation lane
+ * (`<effect>-<param>` in `track.fxAutomation`), read at control rate.
+ */
+export class Param {
+  readonly automated: boolean;
+  private readonly points: readonly AutomationPoint[];
+
+  constructor(
+    readonly fallback: number,
+    points: readonly AutomationPoint[] | undefined,
+    private readonly samplesPerTick: number,
+  ) {
+    this.points = points ?? [];
+    this.automated = this.points.length > 0;
+  }
+
+  at(index: number): number {
+    return this.automated
+      ? interpolateAutomation(
+          this.points,
+          index / this.samplesPerTick,
+          this.fallback,
+        )
+      : this.fallback;
+  }
+}
+
+/** Reader for one `track.fx` effect's numbers, enums and lanes. */
+export function fxReader(
+  track: Track,
+  effect: string,
+  values: FxValues,
+  context: EffectContext,
+) {
+  return {
+    number(name: string): number {
+      return values[name] as number;
+    },
+    text(name: string): string {
+      return values[name] as string;
+    },
+    param(name: string): Param {
+      return new Param(
+        values[name] as number,
+        track.fxAutomation?.[`${effect}-${name}` as FxLane],
+        context.samplesPerTick,
+      );
+    },
+  };
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Resonance 0..1 → biquad Q 0.707..8 (the original filter's mapping). */
+export function resonanceQ(resonance: number): number {
+  return 0.707 + clamp(resonance, 0, 1) * 7.293;
+}
+
+export type FilterType = "lpf" | "hpf" | "bpf";
+
+/** Transposed direct form II biquad with RBJ cookbook coefficients. */
+export class Biquad {
+  b0 = 1;
+  b1 = 0;
+  b2 = 0;
+  a1 = 0;
+  a2 = 0;
+  z1 = 0;
+  z2 = 0;
+
+  set(type: FilterType, cutoff: number, q: number, sampleRate: number): void {
+    const frequency = clamp(cutoff, 20, sampleRate * 0.45);
+    const omega = (2 * Math.PI * frequency) / sampleRate;
+    const alpha = Math.sin(omega) / (2 * q);
+    const cos = Math.cos(omega);
+    const a0 = 1 + alpha;
+    if (type === "lpf") {
+      this.b0 = (1 - cos) / 2 / a0;
+      this.b1 = (1 - cos) / a0;
+      this.b2 = this.b0;
+    } else if (type === "hpf") {
+      this.b0 = (1 + cos) / 2 / a0;
+      this.b1 = -(1 + cos) / a0;
+      this.b2 = this.b0;
+    } else {
+      // Constant 0 dB peak gain band-pass.
+      this.b0 = alpha / a0;
+      this.b1 = 0;
+      this.b2 = -alpha / a0;
+    }
+    this.a1 = (-2 * cos) / a0;
+    this.a2 = (1 - alpha) / a0;
+  }
+
+  process(input: number): number {
+    const output = this.b0 * input + this.z1;
+    this.z1 = this.b1 * input - this.a1 * output + this.z2;
+    this.z2 = this.b2 * input - this.a2 * output;
+    return output;
+  }
+}
+
+/** One-pole low-pass; `set` takes a cutoff in Hz. */
+export class OnePole {
+  private coefficient = 0;
+  state = 0;
+
+  constructor(cutoff: number, sampleRate: number) {
+    this.set(cutoff, sampleRate);
+  }
+
+  set(cutoff: number, sampleRate: number): void {
+    this.coefficient =
+      1 -
+      Math.exp(
+        (-2 * Math.PI * clamp(cutoff, 1, sampleRate * 0.49)) / sampleRate,
+      );
+  }
+
+  process(input: number): number {
+    this.state += this.coefficient * (input - this.state);
+    return this.state;
+  }
+}
+
+export type LfoShape = "sine" | "tri" | "square" | "saw" | "ramp" | "random";
+
+/** Integer hash → 0..1, for sample-and-hold steps keyed by cycle number. */
+export function hashUnit(value: number, seed = 0): number {
+  let state = (Math.floor(value) ^ Math.imul(seed, 0x9e3779b1)) >>> 0;
+  state = Math.imul(state ^ (state >>> 16), 0x85ebca6b) >>> 0;
+  state = Math.imul(state ^ (state >>> 13), 0xc2b2ae35) >>> 0;
+  return ((state ^ (state >>> 16)) >>> 0) / 4_294_967_296;
+}
+
+/**
+ * Bipolar LFO, -1..1, at `phase` cycles (any real). `saw` falls, `ramp`
+ * rises; `random` holds one seeded value per cycle.
+ */
+export function lfo(shape: string, phase: number, seed = 0): number {
+  const cycle = phase - Math.floor(phase);
+  switch (shape) {
+    case "tri":
+      return 1 - 4 * Math.abs(cycle - 0.5);
+    case "square":
+      return cycle < 0.5 ? 1 : -1;
+    case "saw":
+      return 1 - 2 * cycle;
+    case "ramp":
+      return 2 * cycle - 1;
+    case "random":
+      return hashUnit(phase, seed) * 2 - 1;
+    default:
+      return Math.sin(2 * Math.PI * phase);
+  }
+}
+
+/** LFO frequency in Hz: tempo-synced when `sync` (beats per cycle) > 0. */
+export function lfoHz(sync: number, rate: number, tempoBpm: number): number {
+  return sync > 0 ? tempoBpm / 60 / sync : rate;
+}
+
+/** Sample-accurate LFO phase (cycles) with control-rate frequency changes. */
+export class Phasor {
+  phase: number;
+  private increment = 0;
+
+  constructor(start: number) {
+    this.phase = start;
+  }
+
+  setHz(hz: number, sampleRate: number): void {
+    this.increment = hz / sampleRate;
+  }
+
+  next(): number {
+    const value = this.phase;
+    this.phase += this.increment;
+    return value;
+  }
+}
+
+/** Read with linear interpolation `delay` samples behind `write` in a ring. */
+export function readFractional(
+  buffer: Float64Array,
+  write: number,
+  delay: number,
+): number {
+  const length = buffer.length;
+  const position = write - delay;
+  const base = Math.floor(position);
+  const fraction = position - base;
+  const a = buffer[((base % length) + length) % length]!;
+  const b = buffer[(((base + 1) % length) + length) % length]!;
+  return a + (b - a) * fraction;
+}
+
+export function dbToGain(db: number): number {
+  return 10 ** (db / 20);
+}