@hraness/dawg 0.5.0 → 0.6.1

package/src/audio/resample.ts

@@ -0,0 +1,285 @@
+/**
+ * Resample (0.6.1): render one track, one orbit or the whole mix, over the
+ * song, a section or a bar range, to a 16-bit WAV a new sampler or granular
+ * track plays. The render is the same offline path `dawg render` writes
+ * (`renderArrangedPcm`), with the source soloed and, unless `master` is
+ * asked for, the song master left out (a pre-master stem), so the same score
+ * always gives the same bytes and the same sha256.
+ *
+ * Level: the sampler plays a resampled stereo file (a ref with `from`) as
+ * stereo, each channel scaled by SAMPLE_LEVEL and the centre pan's
+ * equal-power gain, so the file is written RESAMPLE_FILE_SCALE louder than
+ * the stem (about +0.09 dB) for the new track, at voice gain RESAMPLE_GAIN
+ * and pan 0, to match the source in both channels (panned sources and
+ * stereo effects keep their image). A granular track reads the mono
+ * mixdown. Peaks past full scale clamp.
+ *
+ * A section or bar range renders from PREROLL_BARS before it (or from the
+ * earliest source note still sounding at its start) and drops those
+ * frames, so held notes and effect tails cross into the range as in the
+ * song.
+ */
+import { createHash } from "node:crypto";
+import {
+  SCORE_LIMITS,
+  TrackScore,
+  ScoreValidationError,
+  type SampleProvenance,
+  type Track,
+} from "../../core/score.ts";
+import { barTicks, findSection, sectionScore } from "../../core/sections.ts";
+import { secondsAtTick } from "../../core/tempo.ts";
+import { renderArrangedPcm } from "./arrange.ts";
+import { orbitOf } from "./effects/duck.ts";
+import { exportSampleRate } from "./measure.ts";
+import { SAMPLE_LEVEL } from "./sampler.ts";
+import type { SampleBank } from "./samples.ts";
+import { RENDER_CHANNELS, encodeWav } from "./wav.ts";
+
+/** Bars rendered before a section or bar range for effect tails. */
+export const PREROLL_BARS = 2;
+
+/** Voice gain the new sampler track plays the file at. */
+export const RESAMPLE_GAIN = 2;
+/** File level over the rendered stem so the voice reproduces it. */
+export const RESAMPLE_FILE_SCALE =
+  Math.SQRT1_2 / (SAMPLE_LEVEL * RESAMPLE_GAIN * 0.5);
+
+export type ResampleSource =
+  | Readonly<{ kind: "track"; trackId: string }>
+  | Readonly<{ kind: "orbit"; orbit: number }>
+  | Readonly<{ kind: "master" }>;
+
+export type ResampleRange =
+  | Readonly<{ kind: "song" }>
+  | Readonly<{ kind: "section"; name: string }>
+  | Readonly<{ kind: "bars"; from: number; to: number }>;
+
+export type ResampleRequest = Readonly<{
+  source: ResampleSource;
+  range: ResampleRange;
+  /** Keep the song master on the render (always on for `master`). */
+  post?: boolean;
+}>;
+
+export type ResampleRender = Readonly<{
+  wav: Uint8Array;
+  sha256: string;
+  sampleRate: number;
+  seconds: number;
+  /** Score tick the rendered range starts at (where the new note goes). */
+  startTick: number;
+  /** Ticks the range covers (the new note's length). */
+  durationTicks: number;
+  from: SampleProvenance;
+}>;
+
+/** `track:<id>`, `orbit:<n>` or `master`: the provenance source name. */
+export function resampleSourceName(source: ResampleSource): string {
+  if (source.kind === "track") return `track:${source.trackId}`;
+  if (source.kind === "orbit") return `orbit:${source.orbit}`;
+  return "master";
+}
+
+/** sha256 of the score's canonical JSON (the provenance pin). */
+export function scoreSha256(score: TrackScore): string {
+  return createHash("sha256")
+    .update(JSON.stringify(score.toJSON()))
+    .digest("hex");
+}
+
+/** The tracks a source plays (throws for an unknown track or empty orbit). */
+export function resampleTracks(
+  score: TrackScore,
+  source: ResampleSource,
+): readonly Track[] {
+  if (source.kind === "master") return score.tracks;
+  const tracks =
+    source.kind === "track"
+      ? score.tracks.filter((track) => track.id === source.trackId)
+      : score.tracks.filter((track) => orbitOf(track) === source.orbit);
+  if (tracks.length === 0)
+    throw new ScoreValidationError(
+      source.kind === "track"
+        ? `no track ${source.trackId}`
+        : `no track plays on orbit ${source.orbit}`,
+      "invalid-track",
+    );
+  return tracks;
+}
+
+/**
+ * The score the render plays: the source soloed (every other track muted),
+ * the master removed unless `post`, cut to the range. Returns where the
+ * range sits in the song.
+ */
+export function resampleScore(
+  score: TrackScore,
+  request: ResampleRequest,
+): Readonly<{
+  score: TrackScore;
+  startTick: number;
+  durationTicks: number;
+  /** Ticks of lead-in the render plays before the range (sliced off). */
+  leadTicks: number;
+}> {
+  const sources = new Set(
+    resampleTracks(score, request.source).map((track) => track.id),
+  );
+  const post = request.post === true || request.source.kind === "master";
+  const json = { ...score.toJSON() } as Record<string, unknown>;
+  json.tracks = score.tracks.map((track) => {
+    const copy = { ...track } as Record<string, unknown>;
+    delete copy.solo;
+    // Solo, not mute, the others: a granular `quant chord` source still
+    // hears the song's harmony (muted tracks leave the chord).
+    if (request.source.kind !== "master" && sources.has(track.id)) {
+      delete copy.muted;
+      copy.solo = true;
+    }
+    return copy;
+  });
+  if (!post) delete json.master;
+  let played = new TrackScore(json as never);
+  const ticks = barTicks(played);
+  const range = request.range;
+  if (range.kind === "song")
+    return {
+      score: played,
+      startTick: 0,
+      durationTicks: played.bars * ticks,
+      leadTicks: 0,
+    };
+  let section;
+  if (range.kind === "section") {
+    section = findSection(played, range.name);
+    if (!section)
+      throw new ScoreValidationError(
+        `no section named ${range.name}${played.sections.length > 0 ? ` (sections: ${played.sections.map((s) => s.name).join(", ")})` : ""}`,
+        "invalid-track",
+      );
+  } else {
+    if (
+      !Number.isInteger(range.from) ||
+      !Number.isInteger(range.to) ||
+      range.from < 1 ||
+      range.to < range.from ||
+      range.to > played.bars
+    )
+      throw new ScoreValidationError(
+        `bars must be a-b inside 1-${played.bars}`,
+        "invalid-track",
+      );
+    section = {
+      name: "resample",
+      startBar: range.from - 1,
+      bars: range.to - range.from + 1,
+    };
+  }
+  // Lead-in: notes still sounding at the range start, and the effect tails
+  // of the bars before it, play from where they began (PREROLL_BARS back at
+  // least); the render then drops the lead-in frames.
+  const from = section.startBar * ticks;
+  let leadBar = Math.max(0, section.startBar - PREROLL_BARS);
+  for (const note of played.notes)
+    if (
+      sources.has(note.trackId) &&
+      note.startTick < from &&
+      note.startTick + note.durationTicks > from
+    )
+      leadBar = Math.min(leadBar, Math.floor(note.startTick / ticks));
+  const lead = section.startBar - leadBar;
+  played = sectionScore(played, {
+    ...section,
+    startBar: leadBar,
+    bars: section.bars + lead,
+  });
+  return {
+    score: played,
+    startTick: from,
+    durationTicks: section.bars * ticks,
+    leadTicks: lead * ticks,
+  };
+}
+
+/**
+ * Render a resample to WAV bytes. `samples` is the source score's loaded
+ * bank (needed when the source plays samples).
+ */
+export function renderResample(
+  score: TrackScore,
+  request: ResampleRequest,
+  samples?: SampleBank,
+): ResampleRender {
+  const {
+    score: played,
+    startTick,
+    durationTicks,
+    leadTicks,
+  } = resampleScore(score, request);
+  // The song's export rate (48 kHz once it has a master), so the new
+  // track nulls against the source when both play at that rate.
+  const sampleRate = exportSampleRate(score);
+  const rendered = renderArrangedPcm(played, {
+    sampleRate,
+    loop: false,
+    ...(samples ? { samples } : {}),
+  });
+  const skip = Math.min(
+    rendered.frames,
+    Math.round(secondsAtTick(played, leadTicks) * rendered.sampleRate),
+  );
+  const audio =
+    skip === 0
+      ? rendered
+      : {
+          ...rendered,
+          frames: rendered.frames - skip,
+          pcm: rendered.pcm.subarray(skip * RENDER_CHANNELS),
+        };
+  const full = new Int16Array(audio.pcm.length);
+  for (let index = 0; index < full.length; index += 1)
+    full[index] = Math.max(
+      -32_768,
+      Math.min(32_767, Math.round(audio.pcm[index]! * RESAMPLE_FILE_SCALE)),
+    );
+  // Trim the tail that rounds to digital silence (within 1 LSB): the new
+  // track's note length comes from the range, not from the file.
+  let end = full.length;
+  while (end > 0 && Math.abs(full[end - 1]!) <= 1) end -= 1;
+  if (end === 0)
+    throw new ScoreValidationError(
+      `${resampleSourceName(request.source)} is silent here · nothing to resample (add notes, unmute it or pick other bars)`,
+    );
+  // Keep 20 ms of silence so the sampler's end fade lands on nothing.
+  const frames = Math.min(
+    audio.frames,
+    Math.ceil(end / RENDER_CHANNELS) + Math.round(0.02 * audio.sampleRate),
+  );
+  const pcm = full.subarray(0, frames * RENDER_CHANNELS);
+  const seconds = frames / audio.sampleRate;
+  if (seconds > SCORE_LIMITS.maxResampleSeconds)
+    throw new ScoreValidationError(
+      `the resample is ${Math.round(seconds)} s; the limit is ${SCORE_LIMITS.maxResampleSeconds} s · pick a section or bars`,
+      "score-limit",
+    );
+  const wav = encodeWav(pcm, audio.sampleRate, RENDER_CHANNELS);
+  const range = request.range;
+  const from: SampleProvenance = {
+    source: resampleSourceName(request.source),
+    ...(range.kind === "section"
+      ? { section: findSection(score, range.name)?.name ?? range.name }
+      : {}),
+    ...(range.kind === "bars" ? { bars: [range.from, range.to] as const } : {}),
+    score: scoreSha256(score),
+  };
+  return {
+    wav,
+    sha256: createHash("sha256").update(wav).digest("hex"),
+    sampleRate: audio.sampleRate,
+    seconds,
+    startTick,
+    durationTicks,
+    from,
+  };
+}

package/src/audio/resonators.ts

@@ -0,0 +1,295 @@
+/**
+ * The modal percussion engine (0.6, lane f06-modal): renders a track whose
+ * instrument is `"modal"` and that carries a `modal` field. Registered in
+ * `src/audio/instruments.ts`; without the field the legacy tone voice plays.
+ *
+ * Per track: notes in onset order, at most `MAX_RESONATOR_VOICES` sounding
+ * (the oldest onset is stolen with a 5 ms fade), each a `ModalBank` struck
+ * once and rung for up to `MAX_RESONATOR_TAIL` seconds after note-off with
+ * early stop on silence. Stealing depends only on earlier onsets, so a
+ * render is prefix-stable: adding a later note never changes earlier audio
+ * before that note starts.
+ *
+ * 0.5 hooks: tuning and note cents (`noteHz`), bends and glides
+ * (`performance.cents`, faded per tick above 0.45 sr), articulation as
+ * timbre only (accent and marcato harden the mallet; staccato damps sooner
+ * through the shorter length), sustain pedal (longer lengths) and half
+ * pedal (`performance.damp`), velocity curve and humanize (already in the
+ * performed notes), and the tempo map (`context.warp`).
+ */
+import type { PerformedNote } from "../../core/expression.ts";
+import {
+  MAX_RESONATOR_TAIL,
+  MAX_RESONATOR_VOICES,
+  MODAL_LANE_PARAMS,
+  modalSettings,
+  modalTailSeconds,
+  RESONATOR_TABLE_VERSION,
+  type ModalSettings,
+} from "../../core/resonators.ts";
+import type { AutomationPoint, Track } from "../../core/score.ts";
+import { noteHz } from "../../core/tuning.ts";
+import { ModalBank, MODAL_BLOCK } from "./dsp/modal.ts";
+import { logCosh } from "./dsp/shape.ts";
+import { interpolateAutomation } from "./effects/common.ts";
+import type { EngineContext, InstrumentEngine } from "./instruments.ts";
+import { warpedSpan } from "./warp.ts";
+
+/**
+ * Raised-cosine fade applied to a stolen voice, seconds. At 80 ms the
+ * largest per-sample gain step is pi/(2*fade samples): -61 dB at 22.05 kHz,
+ * -68 dB at 48 kHz, so stealing a long gong or kempul does not click.
+ */
+const STEAL_FADE = 0.08;
+/** Extra mallet hardness for accent and marcato. */
+const ACCENT_HARDNESS = 0.2;
+/**
+ * Track-level safety knee: exactly linear up to KNEE, then a tanh shoulder
+ * that never passes CEILING. Single notes (about 0.8 at velocity 0.8) and
+ * dyads pass bit-exact; only dense velocity-1 chords reach the shoulder. A
+ * six-note chord at velocity 1 sums to about 4-5 and lands under the
+ * ceiling, which the centre pan and track gain keep below 0 dBFS (spec
+ * test 13).
+ */
+export const MODAL_KNEE = 1;
+const KNEE = MODAL_KNEE;
+const CEILING = 1.38;
+const SPAN = CEILING - KNEE;
+
+function knee(x: number): number {
+  const a = Math.abs(x);
+  if (a <= KNEE) return x;
+  return Math.sign(x) * (KNEE + SPAN * Math.tanh((a - KNEE) / SPAN));
+}
+
+/** Antiderivative of `knee` (even), for first-order ADAA. */
+function kneeF(x: number): number {
+  const a = Math.abs(x);
+  if (a <= KNEE) return 0.5 * x * x;
+  return (
+    0.5 * KNEE * KNEE +
+    KNEE * (a - KNEE) +
+    SPAN * SPAN * logCosh((a - KNEE) / SPAN)
+  );
+}
+
+/**
+ * The knee with first-order ADAA only inside the shoulder: while this and
+ * the previous sample are both under KNEE the output is the input itself, so
+ * the limiter adds no two-tap low-pass or half-sample delay to normal play.
+ */
+export function applyModalKnee(dry: Float64Array, samples: number): void {
+  let x1 = 0;
+  let F1 = 0;
+  for (let index = 0; index < samples; index += 1) {
+    const x = dry[index]!;
+    const Fx = kneeF(x);
+    if (Math.abs(x) > KNEE || Math.abs(x1) > KNEE) {
+      const dx = x - x1;
+      dry[index] = Math.abs(dx) < 1e-5 ? knee(0.5 * (x + x1)) : (Fx - F1) / dx;
+    }
+    x1 = x;
+    F1 = Fx;
+  }
+}
+
+type Planned = Readonly<{
+  note: PerformedNote;
+  start: number;
+  length: number;
+}>;
+
+function span(
+  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 laneOf(
+  track: Track,
+  param: string,
+): readonly AutomationPoint[] | undefined {
+  const lanes = track.fxAutomation as
+    Readonly<Record<string, readonly AutomationPoint[]>> | undefined;
+  const points = lanes?.[`modal-${param}`];
+  return points && points.length > 0 ? points : undefined;
+}
+
+/** Renders a modal track's performed notes into `dry` (mono). */
+export function renderResonatorTrack(
+  dry: Float64Array,
+  notes: readonly PerformedNote[],
+  track: Track,
+  context: EngineContext,
+): void {
+  const { sampleRate, samples } = context;
+  const samplesPerTick = context.samplesPerTick;
+  const tickAt = (index: number): number =>
+    context.warp ? context.warp.tick(index) : index / samplesPerTick;
+  const planned: Planned[] = notes
+    .map((note) => ({ note, ...span(note, context) }))
+    .filter((entry) => entry.start < samples)
+    .sort(
+      (a, b) =>
+        a.start - b.start ||
+        a.note.pitch - b.note.pitch ||
+        (a.note.id < b.note.id ? -1 : a.note.id > b.note.id ? 1 : 0),
+    );
+  const lanes = new Map<string, readonly AutomationPoint[]>();
+  for (const { param } of MODAL_LANE_PARAMS) {
+    const points = laneOf(track, param);
+    if (points) lanes.set(param, points);
+  }
+  const motorLane = lanes.get("motordepth");
+  const volumeLane = track.volumeAutomation ?? [];
+  const volume = Math.max(0, Math.min(1, track.volume ?? 1));
+  const gainAt = (index: number): number =>
+    volume *
+    (volumeLane.length > 0
+      ? interpolateAutomation(volumeLane, tickAt(index), 1)
+      : 1);
+  const seedTick = context.seedTick ?? 0;
+  const base = modalSettings(track.modal);
+  // An ombak pair (f061-gamelan-winds): the pengisep names its partner in
+  // `pair` and sounds `ombak` Hz above the same note, single voice; the
+  // partner (pengumbang) carries ombak 0. Each track renders from its own
+  // field, so stems key per track.
+  const paired = track.modal?.pair !== undefined;
+  const banks: ModalBank[] = [];
+  // Conservative end of each planned voice (its ring cap, or a steal).
+  const ends: number[] = [];
+  const steals: number[] = [];
+  const sounding: number[] = [];
+  for (let i = 0; i < planned.length; i += 1) {
+    const { note, start, length } = planned[i]!;
+    const onsetTick = note.startTick;
+    const settings =
+      lanes.size === 0
+        ? base
+        : clampLanes(
+            modalSettings(track.modal, (param) => {
+              const points = lanes.get(param);
+              return points
+                ? interpolateAutomation(
+                    points,
+                    onsetTick,
+                    base[param as keyof typeof base] as number,
+                  )
+                : undefined;
+            }),
+          );
+    const performance = note.performance;
+    const accent =
+      performance?.accent || note.articulation === "marcato"
+        ? ACCENT_HARDNESS
+        : 0;
+    const hz = noteHz(note.pitch, note.cents, context.tuning);
+    const bank = new ModalBank(
+      paired ? { ...settings, ombak: 0 } : settings,
+      {
+        hz: paired ? hz + settings.ombak : hz,
+        velocity: note.velocity,
+        start: start / sampleRate,
+        duration: length / sampleRate,
+        seed: `${note.id}:${note.startTick + seedTick}:modal`,
+        ...(accent ? { accent } : {}),
+        ...(performance?.cents ? { cents: performance.cents } : {}),
+        ...(motorLane
+          ? {
+              motordepth: (t: number) =>
+                interpolateAutomation(
+                  motorLane,
+                  tickAt(start + t * sampleRate),
+                  settings.motordepth,
+                ),
+            }
+          : {}),
+      },
+      sampleRate,
+      MAX_RESONATOR_TAIL,
+    );
+    banks.push(bank);
+    ends.push(start + bank.endAt);
+    steals.push(Infinity);
+    // Voice stealing in onset order: drop finished voices, then steal the
+    // oldest onset while the pool is full.
+    for (let k = sounding.length - 1; k >= 0; k -= 1)
+      if (ends[sounding[k]!]! <= start) sounding.splice(k, 1);
+    while (sounding.length >= MAX_RESONATOR_VOICES) {
+      const oldest = sounding.shift()!;
+      steals[oldest] = start;
+      ends[oldest] = Math.min(
+        ends[oldest]!,
+        start + Math.round(STEAL_FADE * sampleRate),
+      );
+    }
+    sounding.push(i);
+  }
+  const scratch = new Float64Array(MODAL_BLOCK);
+  const fade = Math.max(1, Math.round(STEAL_FADE * sampleRate));
+  for (let i = 0; i < planned.length; i += 1) {
+    const { note, start } = planned[i]!;
+    const bank = banks[i]!;
+    const stop = Math.min(samples, ends[i]!);
+    const steal = steals[i]!;
+    const damp = note.performance?.damp;
+    const dampFrom = damp ? start + Math.round(damp.from * sampleRate) : 0;
+    let at = start;
+    while (at < stop) {
+      const count = Math.min(MODAL_BLOCK, stop - at);
+      scratch.fill(0, 0, count);
+      const alive = bank.process(scratch, 0, count);
+      const gain = gainAt(at);
+      for (let j = 0; j < count; j += 1) {
+        const index = at + j;
+        let level = gain;
+        if (index >= steal)
+          level *=
+            index - steal >= fade
+              ? 0
+              : 0.5 + 0.5 * Math.cos((Math.PI * (index - steal)) / fade);
+        if (damp && index > dampFrom)
+          level *= Math.exp(-(index - dampFrom) / (damp.tau * sampleRate));
+        dry[index]! += scratch[j]! * level;
+      }
+      if (!alive) break;
+      at += count;
+    }
+  }
+  // Causal and stateless across renders, so the output stays prefix-stable.
+  applyModalKnee(dry, samples);
+}
+
+/** Lane values land inside each parameter's range. */
+function clampLanes(settings: ModalSettings): ModalSettings {
+  const out: Record<string, number | string> = { ...settings };
+  for (const { param, spec } of MODAL_LANE_PARAMS) {
+    const value = out[param];
+    if (typeof value === "number")
+      out[param] = Math.max(spec.min, Math.min(spec.max, value));
+  }
+  return Object.freeze(out) as ModalSettings;
+}
+
+/** The modal engine as registered in `src/audio/instruments.ts`. */
+export const MODAL_ENGINE: InstrumentEngine = Object.freeze({
+  id: "modal",
+  field: "modal",
+  render(dry, _dryR, notes, track, context) {
+    renderResonatorTrack(dry, notes, track, context);
+  },
+  tailSeconds: (track: Track, lowestPitch?: number) =>
+    modalTailSeconds(track.modal, lowestPitch),
+  // Undamped bars and gongs ring on after the key lifts, as struck metal does.
+  ringOut: (track: Track) => modalSettings(track.modal).damp === 0,
+  stereo: () => false,
+  assetDigests: () => [`resonators:${RESONATOR_TABLE_VERSION}`],
+});