@hraness/dawg 0.6.1 → 0.7.0

package/src/audio/clips.ts

@@ -0,0 +1,240 @@
+/**
+ * Audio clips (0.7): files placed on a track's timeline, summed into the
+ * track's dry buffer before its effect chain (sources.md section 7). The
+ * pure placement and section cuts live in core/clips.ts; this module reads
+ * the decoded audio, places it through the tempo map, resamples it to the
+ * render rate (4-point Hermite), applies the take's clock-drift stretch,
+ * reverse, gain and equal-power fades, and multiplies by the track's
+ * volume the way every voice does. A clip whose audio did not load renders
+ * silence (the loader reported it as a warning).
+ */
+import {
+  CLIP_VOICE_PREFIX,
+  DEFAULT_CLIP_FADE,
+  clipSongTick,
+  resolveClipLengths,
+} from "../../core/clips.ts";
+import type { AudioClip, Take, Track, TrackScore } from "../../core/score.ts";
+import { autotuneClip } from "./autotune.ts";
+import { sampleKey, type DecodedSample, type SampleBank } from "./samples.ts";
+import type { SampleWarp } from "./warp.ts";
+
+/** What clip rendering reads of the render context. */
+export type ClipContext = Readonly<{
+  sampleRate: number;
+  samples: number;
+  samplesPerTick: number;
+  warp?: SampleWarp;
+}>;
+
+/** True when a track has clips that sound. */
+export function hasClips(track: Track | undefined): boolean {
+  return track?.clips?.some((clip) => !clip.mute) ?? false;
+}
+
+/** The decoded audio of a clip, if it loaded. */
+export function clipAudio(
+  bank: SampleBank | undefined,
+  trackId: string,
+  clip: AudioClip,
+): DecodedSample | undefined {
+  if (!bank) return undefined;
+  const exact = bank.voices.get(
+    sampleKey(trackId, `${CLIP_VOICE_PREFIX}${clip.id}`),
+  );
+  if (exact) return exact;
+  // A section or form pass of a clip is `<id>~<n>`: it plays the audio
+  // the bank loaded for `<id>` from the unsliced score.
+  const pass = clip.id.lastIndexOf("~");
+  return pass > 0
+    ? bank.voices.get(
+        sampleKey(trackId, `${CLIP_VOICE_PREFIX}${clip.id.slice(0, pass)}`),
+      )
+    : undefined;
+}
+
+/**
+ * `score` with each loaded clip's missing `dur` resolved from its file
+ * (`resolveClipLengths`), so section, form and window cuts see its real
+ * end. A score without clips, or without a bank, comes back as it is.
+ */
+export function withClipLengths(
+  score: TrackScore,
+  bank: SampleBank | undefined,
+): TrackScore {
+  if (!bank || !score.tracks.some((track) => track.clips)) return score;
+  return resolveClipLengths(score, (trackId, clip) => {
+    const audio = clipAudio(bank, trackId, clip);
+    return audio && audio.frames > 0
+      ? audio.frames / audio.sampleRate
+      : undefined;
+  });
+}
+
+/** Fractional render sample where a score tick sounds. */
+function sampleAt(context: ClipContext, tick: number): number {
+  return context.warp
+    ? context.warp.sample(tick)
+    : tick * context.samplesPerTick;
+}
+
+/** The take a clip plays from, if any. */
+function takeOf(track: Track, clip: AudioClip): Take | undefined {
+  if (clip.take === undefined) return undefined;
+  return track.takes?.find((take) => take.name === clip.take);
+}
+
+/** Catmull-Rom (4-point Hermite) read at a fractional frame, 0 outside. */
+function readHermite(data: Float32Array, position: number): number {
+  const base = Math.floor(position);
+  const t = position - base;
+  const at = (index: number) =>
+    index >= 0 && index < data.length ? data[index]! : 0;
+  const y0 = at(base - 1);
+  const y1 = at(base);
+  const y2 = at(base + 1);
+  const y3 = at(base + 2);
+  const c1 = 0.5 * (y2 - y0);
+  const c2 = y0 - 2.5 * y1 + 2 * y2 - 0.5 * y3;
+  const c3 = 0.5 * (y3 - y0) + 1.5 * (y1 - y2);
+  return ((c3 * t + c2) * t + c1) * t + y1;
+}
+
+/** Equal-power fade gain for `x` in 0..1 (sin of a quarter turn). */
+export function equalPowerFade(x: number): number {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  return Math.sin((x * Math.PI) / 2);
+}
+
+/**
+ * Sum `track`'s clips into `target` (the mono dry buffer). `gainAt(tick)`
+ * is the track volume with automation; `tickAt(sample)` maps a render
+ * sample back to a score tick for it. Returns the clips that did not
+ * load (they stay silent). With `score` and a `Track.autotune` (0.7), each
+ * clip plays retuned (`autotuneClip`, keyed by its offset and nudge);
+ * reversed clips play untuned.
+ */
+export function renderClips(
+  target: Float64Array,
+  track: Track,
+  context: ClipContext,
+  bank: SampleBank | undefined,
+  gainAt: (tick: number) => number,
+  score?: TrackScore,
+): string[] {
+  const missing: string[] = [];
+  if (!track.clips) return missing;
+  const { sampleRate, samples } = context;
+  const tickAt = (index: number) =>
+    context.warp ? context.warp.tick(index) : index / context.samplesPerTick;
+  for (const clip of track.clips) {
+    if (clip.mute) continue;
+    const audio = clipAudio(bank, track.id, clip);
+    if (!audio || audio.frames === 0) {
+      missing.push(clip.id);
+      continue;
+    }
+    const take = takeOf(track, clip);
+    // A take recorded on a drifting clock (`ppm`) plays slightly faster or
+    // slower so it stays on the grid; `nudge` moves it in milliseconds.
+    const drift = 1 + (take?.ppm ?? 0) / 1e6;
+    const nudge = (take?.nudge ?? 0) / 1000;
+    const fileSeconds = audio.frames / audio.sampleRate;
+    const offset = Math.min(fileSeconds, clip.offset ?? 0);
+    const length = Math.max(
+      0,
+      Math.min(
+        clip.dur ?? Number.POSITIVE_INFINITY,
+        (fileSeconds - offset) / drift,
+      ),
+    );
+    if (length <= 0) continue;
+    const start =
+      sampleAt(context, clipSongTick(clip, track.time)) + nudge * sampleRate;
+    const total = length * sampleRate;
+    const first = Math.max(0, Math.ceil(start));
+    const last = Math.min(samples, Math.ceil(start + total));
+    if (first >= last) continue;
+    const step = (audio.sampleRate / sampleRate) * drift;
+    const begin = offset * audio.sampleRate;
+    const span = length * audio.sampleRate * drift;
+    const fadeIn = Math.min(clip.fadeInTime ?? DEFAULT_CLIP_FADE, length / 2);
+    const fadeOut = Math.min(clip.fadeTime ?? DEFAULT_CLIP_FADE, length / 2);
+    const fadeInFrames = fadeIn * sampleRate;
+    const fadeOutFrames = fadeOut * sampleRate;
+    const gain = clip.gain ?? 1;
+    // 0.7 autotune: the clip's audio retuned at the song second its
+    // offset sounds (`start` already holds the nudge).
+    const tuned =
+      track.autotune && score && !clip.rev
+        ? autotuneClip(
+            score,
+            track,
+            {
+              sha256: audio.sha256,
+              sampleRate: audio.sampleRate,
+              mono: audio.mono,
+            },
+            start / sampleRate,
+            offset,
+            clip.id,
+            0,
+            nudge,
+          )
+        : undefined;
+    const data = tuned ? tuned.mono : audio.mono;
+    const shiftFrom = tuned ? tuned.from : 0;
+    // Track volume (with automation) is read once per 32-sample block.
+    let blockGain = 0;
+    for (let index = first; index < last; index += 1) {
+      if ((index - first) % 32 === 0) blockGain = gainAt(tickAt(index));
+      const elapsed = index - start;
+      let position = elapsed * step;
+      if (position >= span) break;
+      position = clip.rev ? begin + span - 1 - position : begin + position;
+      let shape = gain * blockGain;
+      if (fadeInFrames > 0 && elapsed < fadeInFrames)
+        shape *= equalPowerFade(elapsed / fadeInFrames);
+      const remaining = total - elapsed;
+      if (fadeOutFrames > 0 && remaining < fadeOutFrames)
+        shape *= equalPowerFade(remaining / fadeOutFrames);
+      target[index]! += readHermite(data, position - shiftFrom) * shape;
+    }
+  }
+  return missing;
+}
+
+/**
+ * Stem-cache key part for a track's clips: each clip's sha256 (the one
+ * loaded, so an edited file re-renders), placement, cut, gain, fades and
+ * reverse, and the drift of the take it plays from.
+ */
+export function clipsDigest(
+  track: Track,
+  bank: SampleBank | undefined,
+  guide = false,
+): string | undefined {
+  if (!track.clips || track.clips.length === 0) return undefined;
+  return (
+    (guide ? "guide|" : "") +
+    track.clips
+      .map((clip) => {
+        const take = takeOf(track, clip);
+        return [
+          clip.id,
+          clipAudio(bank, track.id, clip)?.sha256 ?? `missing:${clip.sha256}`,
+          clip.startTick,
+          clip.offset ?? "",
+          clip.dur ?? "",
+          clip.gain ?? "",
+          clip.fadeInTime ?? "",
+          clip.fadeTime ?? "",
+          clip.rev ? "r" : "",
+          clip.mute ? "m" : "",
+          take ? `${take.ppm ?? 0}/${take.nudge ?? 0}` : "",
+        ].join(",");
+      })
+      .join(";")
+  );
+}

package/src/audio/doctor.ts

@@ -0,0 +1,86 @@
+/**
+ * `dawg doctor`: how dawg makes sound on this machine. The backend and why
+ * it was chosen, the native sink's verification (or why it fell back), the
+ * audio devices, and the play-mode lead.
+ */
+import {
+  AudioEngine,
+  detectAudioBackend,
+  type AudioBackendInfo,
+} from "./engine.ts";
+import { PREBUILT_DIR, nativeTarget } from "./native.ts";
+import { DEFAULT_SAMPLE_RATE } from "./wav.ts";
+
+export type DoctorReport = Readonly<{
+  backend: AudioBackendInfo["backend"];
+  detail: string;
+  native: Readonly<{
+    target: string | null;
+    dir: string;
+    loaded: boolean;
+    reason?: string;
+  }>;
+  playLeadMs: number;
+  outputs: readonly string[];
+  inputs: readonly string[];
+}>;
+
+export function audioDoctor(info = detectAudioBackend()): DoctorReport {
+  const engine = new AudioEngine({ info, worker: false, timer: false });
+  const playLeadMs = engine.playLeadMs;
+  void engine.dispose();
+  const list = (input: boolean) =>
+    info.native
+      ?.devices(input)
+      .map(
+        (d) =>
+          `${d.name}${d.default ? " (default)" : ""} · ${d.channels} ch · ${d.rate} Hz`,
+      ) ?? [];
+  return {
+    backend: info.backend,
+    detail: info.detail,
+    native: {
+      target: nativeTarget() ?? null,
+      dir: PREBUILT_DIR,
+      loaded: info.backend === "native",
+      ...(info.nativeUnavailable ? { reason: info.nativeUnavailable } : {}),
+    },
+    playLeadMs,
+    outputs: list(false),
+    inputs: list(true),
+  };
+}
+
+export function formatAudioDoctor(report: DoctorReport): string[] {
+  const lines = [
+    `audio: ${report.backend} · ${report.detail}`,
+    report.native.loaded
+      ? `native sink: loaded (${report.native.target})`
+      : `native sink: not in use · ${report.native.reason ?? "another backend was forced"} · falls back to ffplay, sox or afplay`,
+    `play lead: ${report.playLeadMs} ms · render rate ${DEFAULT_SAMPLE_RATE} Hz`,
+  ];
+  if (report.outputs.length > 0)
+    lines.push("outputs:", ...report.outputs.map((d) => `  ${d}`));
+  if (report.inputs.length > 0)
+    lines.push("inputs:", ...report.inputs.map((d) => `  ${d}`));
+  return lines;
+}
+
+export async function runDoctorCommand(
+  args: readonly string[],
+  stdout: { write(text: string): unknown },
+): Promise<number> {
+  if (args.some((arg) => arg === "--help" || arg === "-h")) {
+    stdout.write(
+      "usage: dawg doctor [--json]  audio backend, native sink, devices\n",
+    );
+    return 0;
+  }
+  const report = audioDoctor();
+  stdout.write(
+    args.includes("--json")
+      ? `${JSON.stringify(report, null, 2)}\n`
+      : `${formatAudioDoctor(report).join("\n")}\n`,
+  );
+  return 0;
+}

package/src/audio/dsp/bandbank.ts

@@ -0,0 +1,138 @@
+/**
+ * Band-pass banks (0.7 vocoder): RBJ biquads, their group delay and a
+ * sample-rate-independent band layout. Band centres and widths depend only
+ * on the band count, range and width, never on the sample rate: a band whose
+ * centre lies above 0.45 sr is muted instead, so a 22 050 Hz audition and a
+ * 48 kHz export have the same layout.
+ */
+
+export type Biquad = Readonly<{
+  b0: number;
+  b1: number;
+  b2: number;
+  a1: number;
+  a2: number;
+}>;
+
+/** RBJ constant-0-dB-peak band-pass, bandwidth in octaves, pre-warped. */
+export function bandpass(
+  hz: number,
+  octaves: number,
+  sampleRate: number,
+): Biquad {
+  const w = (2 * Math.PI * hz) / sampleRate;
+  const s = Math.sin(w);
+  const alpha = s * Math.sinh(((Math.LN2 / 2) * octaves * w) / s);
+  const a0 = 1 + alpha;
+  return {
+    b0: alpha / a0,
+    b1: 0,
+    b2: -alpha / a0,
+    a1: (-2 * Math.cos(w)) / a0,
+    a2: (1 - alpha) / a0,
+  };
+}
+
+/** RBJ Butterworth high-pass (Q = 1/sqrt 2). */
+export function highpass(hz: number, sampleRate: number): Biquad {
+  const w = (2 * Math.PI * hz) / sampleRate;
+  const alpha = Math.sin(w) / (2 * Math.SQRT1_2);
+  const c = Math.cos(w);
+  const a0 = 1 + alpha;
+  return {
+    b0: (1 + c) / 2 / a0,
+    b1: -(1 + c) / a0,
+    b2: (1 + c) / 2 / a0,
+    a1: (-2 * c) / a0,
+    a2: (1 - alpha) / a0,
+  };
+}
+
+/** Group delay in samples of one biquad at angle `w` (numeric phase slope). */
+export function groupDelay(f: Biquad, w: number): number {
+  const phase = (x: number): number => {
+    const nr = f.b0 + f.b1 * Math.cos(x) + f.b2 * Math.cos(2 * x);
+    const ni = -(f.b1 * Math.sin(x) + f.b2 * Math.sin(2 * x));
+    const dr = 1 + f.a1 * Math.cos(x) + f.a2 * Math.cos(2 * x);
+    const di = -(f.a1 * Math.sin(x) + f.a2 * Math.sin(2 * x));
+    return Math.atan2(ni, nr) - Math.atan2(di, dr);
+  };
+  const d = 1e-5;
+  let dp = phase(w + d) - phase(w - d);
+  while (dp > Math.PI) dp -= 2 * Math.PI;
+  while (dp < -Math.PI) dp += 2 * Math.PI;
+  return -dp / (2 * d);
+}
+
+/** Runs a biquad over `x` in place (transposed direct form II). */
+export function runBiquad(f: Biquad, x: Float64Array): void {
+  let z1 = 0;
+  let z2 = 0;
+  const { b0, b1, b2, a1, a2 } = f;
+  for (let i = 0; i < x.length; i += 1) {
+    const v = x[i]!;
+    const y = b0 * v + z1;
+    z1 = b1 * v - a1 * y + z2;
+    z2 = b2 * v - a2 * y;
+    x[i] = y;
+  }
+}
+
+export type BandLayout = Readonly<{
+  bands: number;
+  lo: number;
+  hi: number;
+  width: number;
+}>;
+
+/**
+ * Log-spaced centres from `lo` to `hi`. Each of the two cascaded sections is
+ * about 1.55x wider than the target so the pair's -3 dB width matches
+ * spacing x width.
+ */
+export function bandLayout(p: BandLayout): {
+  centres: number[];
+  ratio: number;
+  octaves: number;
+} {
+  const n = Math.max(2, Math.round(p.bands));
+  const ratio = (p.hi / p.lo) ** (1 / (n - 1));
+  const centres = Array.from({ length: n }, (_, k) => p.lo * ratio ** k);
+  return { centres, ratio, octaves: Math.log2(ratio) * p.width * 1.55 };
+}
+
+export type BankBand = Readonly<{
+  hz: number;
+  live: boolean;
+  filter: Biquad;
+  /** Modulator advance: the pair's group delay at hz plus the attack. */
+  advance: number;
+}>;
+
+/**
+ * The bank at one sample rate. Each band's modulator advance cancels the
+ * analysis filters' group delay and the follower attack, so consonants land
+ * on the beat.
+ */
+export function bankDesign(
+  p: BandLayout & { attack?: number },
+  sampleRate: number,
+): { bands: BankBand[]; ratio: number } {
+  const { centres, ratio, octaves } = bandLayout(p);
+  const bands = centres.map((hz) => {
+    const live = hz <= 0.45 * sampleRate;
+    const filter = bandpass(
+      Math.min(hz, 0.45 * sampleRate),
+      octaves,
+      sampleRate,
+    );
+    const advance = live
+      ? Math.round(
+          2 * groupDelay(filter, (2 * Math.PI * hz) / sampleRate) +
+            (p.attack ?? 0) * sampleRate,
+        )
+      : 0;
+    return { hz, live, filter, advance };
+  });
+  return { bands, ratio };
+}

package/src/audio/dsp/envelope.ts

@@ -93,6 +93,15 @@ export function cepstralEnvelope(
   return out;
 }
 
+/**
+ * A peak joins the envelope only within this factor (-9 dB) of the smooth
+ * cepstral envelope: harmonics sit on it, while window sidelobes and breath
+ * noise in the valleys between harmonics sit far below. Without this the
+ * envelope followed the source's harmonic comb, and `formant 0` imposed the
+ * old pitch on the shifted one (pitch.md 3.5).
+ */
+const HARMONIC_PEAK_FLOOR = 10 ** (-9 / 20);
+
 /**
  * Harmonic-peak envelope (0.6.1): log magnitude interpolated linearly
  * between the spectral peaks (each refined by a parabola to its true bin
@@ -122,6 +131,7 @@ export function peakEnvelope(
     const v = mag[k]!;
     if (
       v > floor &&
+      v >= smooth[k]! * HARMONIC_PEAK_FLOOR &&
       v > mag[k - 1]! &&
       v >= mag[k + 1]! &&
       v > mag[k - 2]! &&

package/src/audio/dsp/follow.ts

@@ -0,0 +1,120 @@
+/**
+ * Envelope followers (0.7 vocoder): one-pole attack/release on |x|, and the
+ * gate curve built on one. Pure functions of the input buffer, so a render
+ * window with enough pre-roll settles to the full render's values.
+ */
+
+/** One-pole coefficient for a time constant in seconds (0 = instant). */
+export function followCoef(seconds: number, sampleRate: number): number {
+  return seconds <= 0 ? 0 : Math.exp(-1 / (seconds * sampleRate));
+}
+
+/**
+ * Follows |x| with separate attack and release times. Where `hold[i]` is
+ * non-zero the envelope keeps its last value (the vocoder's freeze).
+ */
+export function follow(
+  x: Float64Array,
+  attack: number,
+  release: number,
+  sampleRate: number,
+  hold?: Uint8Array,
+): Float64Array {
+  const a = followCoef(attack, sampleRate);
+  const r = followCoef(release, sampleRate);
+  const out = new Float64Array(x.length);
+  let e = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    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;
+}
+
+/**
+ * Gate gain 0..1 per sample: a broadband follower against `thresholdDb`
+ * with a 6 dB soft knee, smoothed over 5 ms. Undefined when the gate is off
+ * (threshold at or below -119 dBFS).
+ */
+export function gateCurve(
+  x: Float64Array,
+  sampleRate: number,
+  thresholdDb: number,
+): Float64Array | undefined {
+  if (thresholdDb <= -119) return undefined;
+  const level = follow(x, 0.001, 0.05, sampleRate);
+  const out = new Float64Array(x.length);
+  const c = followCoef(0.005, sampleRate);
+  let s = 0;
+  for (let i = 0; i < x.length; i += 1) {
+    const db = 20 * Math.log10(level[i]! + 1e-12);
+    const t = Math.min(1, Math.max(0, (db - thresholdDb) / 6));
+    s = c * s + (1 - c) * t;
+    out[i] = s;
+  }
+  return out;
+}
+
+/**
+ * Where `hold[i]` is non-zero, `curve` keeps its value from the sample
+ * before (in place): a frozen vocoder keeps its gate where it was, so the
+ * held vowel does not fade out once the modulator goes quiet.
+ */
+export function holdCurve(curve: Float64Array, hold: Uint8Array): void {
+  for (let i = 1; i < curve.length && i < hold.length; i += 1)
+    if (hold[i] !== 0) curve[i] = curve[i - 1]!;
+}
+
+/**
+ * The static `freeze` hold: 1 wherever the modulator is quiet (under the
+ * gate, or under -50 dBFS when the gate is lower or off), engaged
+ * `lead` seconds before the voice falls quiet so the envelopes are caught
+ * before their release. The carrier keeps the last sung vowel through every
+ * rest and follows the voice while it sings. Before the first note it holds
+ * silence. Local (the mod span plus its lookahead), so windows agree.
+ */
+export function quietHold(
+  x: Float64Array,
+  n: number,
+  sampleRate: number,
+  thresholdDb: number,
+  lead = 0.03,
+): Uint8Array {
+  const level = follow(x, 0.001, 0.01, sampleRate);
+  const floor = 10 ** (Math.max(thresholdDb, -50) / 20);
+  const ahead = Math.max(0, Math.round(lead * sampleRate));
+  const hold = new Uint8Array(n);
+  let nextQuiet = Infinity;
+  for (let i = Math.min(level.length, n + ahead) - 1; i >= 0; i -= 1) {
+    if (level[i]! < floor) {
+      // the start of a quiet run reaches back `ahead` samples
+      if (i === 0 || level[i - 1]! >= floor) nextQuiet = i;
+      if (i < n) hold[i] = 1;
+    } else if (i < n && nextQuiet - i <= ahead) hold[i] = 1;
+  }
+  for (let i = level.length; i < n; i += 1) hold[i] = 1;
+  return hold;
+}
+
+/**
+ * Auto gate threshold for a whole asset: the 10th-percentile 10 ms frame
+ * level plus 6 dB (the mean-abs follower reads about 1 dB under RMS). A
+ * property of the asset, so every render window agrees. -120 when silent.
+ */
+export function autoGateDb(asset: Float64Array, sampleRate: number): number {
+  const hop = Math.max(1, Math.round(0.01 * sampleRate));
+  const levels: number[] = [];
+  for (let s = 0; s + hop <= asset.length; s += hop) {
+    let e = 0;
+    for (let i = s; i < s + hop; i += 1) e += asset[i]! * asset[i]!;
+    const db = 10 * Math.log10(e / hop + 1e-24);
+    if (db > -100) levels.push(db);
+  }
+  if (levels.length === 0) return -120;
+  levels.sort((a, b) => a - b);
+  return levels[Math.floor(levels.length * 0.1)]! + 6;
+}