@hraness/dawg 0.4.1 → 0.5.0

package/src/audio/wav.ts

@@ -10,6 +10,12 @@ import {
   type TrackScore,
 } from "../../core/score.ts";
 import { drumVoiceForPitch, isDrumInstrument } from "../../core/drums.ts";
+import {
+  performanceTimingFor,
+  tunedTiming,
+  performNotes,
+  type PerformedNote,
+} from "../../core/expression.ts";
 import {
   planSamplerVoices,
   renderSamplerVoices,
@@ -53,12 +59,21 @@ import {
   type OrbitBus,
 } from "./effects/bus.ts";
 import { tableFor, wavetableOscillator } from "./wavetable.ts";
+import { noteHz, resolveTuning, type TuningTable } from "../../core/tuning.ts";
 import {
   duckGains,
   duckSettings,
   orbitOf,
   type Ducker,
 } from "./effects/duck.ts";
+import {
+  loopSecondsOf,
+  performedNotes,
+  slowestBpmOf,
+} from "../../core/tempo.ts";
+import { sampleWarpFor, warpedSpan, type SampleWarp } from "./warp.ts";
+import { applyMaster, type MasterReport } from "./master.ts";
+import type { SongMaster } from "../../core/master.ts";
 
 export type WavOptions = Readonly<{ sampleRate?: number; maxSeconds?: number }>;
 
@@ -75,6 +90,12 @@ export type RenderOptions = WavOptions &
      * tracks render silent; scores without samplers are unaffected.
      */
     samples?: SampleBank;
+    /**
+     * Ticks added to each note's start when seeding its noise. An arranged
+     * render window passes its origin so seeded voices sound as they do in
+     * a single pass of the whole song. Zero (the default) changes nothing.
+     */
+    seedTick?: number;
   }>;
 
 /** Interleaved stereo 16-bit PCM plus its frame count. */
@@ -83,6 +104,8 @@ export type RenderedAudio = Readonly<{
   channels: 2;
   frames: number;
   pcm: Int16Array;
+  /** Loudness the song master reached; absent without a master. */
+  master?: MasterReport;
 }>;
 
 /** Output channel count for every render and export. */
@@ -145,6 +168,16 @@ const MAX_DRUM_SECONDS = 0.6;
 const CONTROL_SAMPLES = 32;
 /** One-shot renders keep this much ring-out after the last bar. */
 const ONE_SHOT_TAIL_SECONDS = 0.35;
+
+function oneShotSeconds(
+  loopSeconds: number,
+  samplerTail: number,
+  reverbTail: number,
+): number {
+  return (
+    loopSeconds + Math.max(ONE_SHOT_TAIL_SECONDS, samplerTail) + reverbTail
+  );
+}
 /** Loop renders fold at most this much tail back onto the loop start. */
 const MAX_LOOP_TAIL_SECONDS = 8;
 
@@ -155,10 +188,14 @@ type RenderContext = Readonly<{
   samplesPerTick: number;
   tempoBpm: number;
   irs?: ReadonlyMap<string, DecodedSample>;
+  /** Tempo map in samples (core/tempo.ts); absent: constant tempo. */
+  warp?: SampleWarp;
+  seedTick?: number;
 }>;
 
 /** Exact (fractional) loop length in frames at a sample rate. */
 export function loopFrames(score: TrackScore, sampleRate: number): number {
+  if (score.time) return loopSecondsOf(score) * sampleRate;
   return (score.bars * score.beatsPerBar * 60 * sampleRate) / score.tempoBpm;
 }
 
@@ -256,11 +293,38 @@ export class StemRenderer {
     return { stems: this.stems.size, bytes: this.cacheBytes };
   }
 
+  /**
+   * Seconds a one-shot render of `score` needs (song plus tail) before the
+   * renderer's cap, so callers can tell when a single pass would cut it.
+   */
+  public oneShotSeconds(
+    score: TrackScore,
+    options: RenderOptions = {},
+  ): number {
+    const sampleRate = clampSampleRate(options.sampleRate);
+    const bank = options.samples ?? EMPTY_SAMPLE_BANK;
+    const reverbTail = Math.max(
+      0,
+      ...score.tracks.map((track) =>
+        reverbTailFor(track, sampleRate, bank.irs),
+      ),
+    );
+    const samplerTail = Math.min(
+      MAX_LOOP_TAIL_SECONDS,
+      Math.max(
+        samplerTailSeconds(score, bank, sampleRate),
+        ...score.tracks.map(synthTailSeconds),
+      ),
+    );
+    return oneShotSeconds(loopSecondsOf(score), samplerTail, reverbTail);
+  }
+
   public render(score: TrackScore, options: RenderOptions = {}): RenderedAudio {
     const sampleRate = clampSampleRate(options.sampleRate);
     const maxSeconds = Math.max(1, Math.min(60, options.maxSeconds ?? 30));
-    const loopSeconds = (score.bars * score.beatsPerBar * 60) / score.tempoBpm;
+    const loopSeconds = loopSecondsOf(score);
     const bank = options.samples ?? EMPTY_SAMPLE_BANK;
+    const warp = sampleWarpFor(score, sampleRate);
     const reverbTail = Math.max(
       0,
       ...score.tracks.map((track) =>
@@ -293,14 +357,17 @@ export class StemRenderer {
           reverbTail +
           Math.max(
             0,
-            ...score.tracks.map((track) => delayTailFor(track, score.tempoBpm)),
+            // The slowest tempo in the map gives the longest echoes.
+            ...score.tracks.map((track) =>
+              delayTailFor(track, slowestBpmOf(score)),
+            ),
           ),
       );
       samples = frames + Math.ceil(tailSeconds * sampleRate);
     } else {
       const seconds = Math.min(
         maxSeconds,
-        loopSeconds + Math.max(ONE_SHOT_TAIL_SECONDS, samplerTail) + reverbTail,
+        oneShotSeconds(loopSeconds, samplerTail, reverbTail),
       );
       frames = Math.max(1, Math.ceil(seconds * sampleRate));
       samples = frames;
@@ -312,6 +379,8 @@ export class StemRenderer {
       samplesPerTick: (sampleRate * 60) / (score.tempoBpm * score.ticksPerBeat),
       tempoBpm: score.tempoBpm,
       ...(bank.irs ? { irs: bank.irs } : {}),
+      ...(warp ? { warp } : {}),
+      ...(options.seedTick ? { seedTick: options.seedTick } : {}),
     };
     this.renders += 1;
     const { dry, dryR, left, right, mixL, mixR } = this.scratchFor(samples);
@@ -319,20 +388,34 @@ export class StemRenderer {
     mixR.fill(0);
     const tracks = new Map(score.tracks.map((track) => [track.id, track]));
     const groups = new Map<string, Note[]>();
-    for (const note of score.notes) {
+    // Track time (rate, phase, cycle) places notes on the song timeline.
+    for (const note of performedNotes(score)) {
       const group = groups.get(note.trackId);
       if (group) group.push(note);
       else groups.set(note.trackId, [note]);
     }
+    // Note expression and track performance (core/expression.ts): the
+    // notes as played. A track with neither gets its notes back unchanged.
+    const timing = performanceTimingFor(score);
+    const performed = new Map<string, readonly PerformedNote[]>();
+    for (const [trackId, notes] of groups) {
+      const track = tracks.get(trackId);
+      performed.set(
+        trackId,
+        performNotes(track, notes, tunedTiming(timing, score, track)),
+      );
+    }
     // Orbit ducking is a gain on finished stems (src/audio/effects/duck.ts).
     const duckers: Ducker[] = [];
-    for (const [trackId, notes] of groups) {
+    for (const [trackId] of groups) {
       const settings = duckSettings(tracks.get(trackId));
       if (settings && isTrackAudible(score, trackId))
         duckers.push({
           trackId,
           ...settings,
-          onsets: notes.map((note) => noteSpan(note, context).start),
+          onsets: performed
+            .get(trackId)!
+            .map((note) => noteSpan(note, context).start),
         });
     }
     const ducked = duckGains(
@@ -349,11 +432,16 @@ export class StemRenderer {
     for (const [trackId, notes] of groups) {
       if (!isTrackAudible(score, trackId)) continue;
       const track = tracks.get(trackId);
+      // Stems key on the written notes (with the track's performance
+      // settings); the voices render the performed ones.
+      const played = performed.get(trackId)!;
       const busOrbit = sharedOrbitOf(track);
       const sampler = isSamplerInstrument(track?.instrument);
       // Wavetable hook: the oscillator factory for a wavetable track (its
       // table id joins the stem key), undefined for every other instrument.
       const wavetable = track ? wavetableHook(track, bank, context) : undefined;
+      // The merged song and track tuning; undefined keeps 12-TET untouched.
+      const tuning = resolveTuning(score.tuning, track?.tuning, score.key);
       const key = stemKey(
         track,
         notes,
@@ -406,16 +494,28 @@ export class StemRenderer {
         const stereo = synthVoice && isStereoVoice(track);
         if (stereo) dryR.fill(0);
         if (sampler) {
-          if (track) renderSamplerNotes(dry, notes, track, context, bank);
+          if (track) renderSamplerNotes(dry, played, track, context, bank);
         } else if (synthVoice && track) {
           const gainAt = (tick: number) => trackGainAt(track, tick);
           const voice = {
             ...context,
             ticksPerBeat: score.ticksPerBeat,
             ...(wavetable ? { oscillatorFor: wavetable.oscillatorFor } : {}),
+            ...(tuning ? { tuning } : {}),
           };
-          for (const note of notes) {
+          const warp = context.warp;
+          for (const note of played) {
             const { start, length } = noteSpan(note, context);
+            // The voice asks for `startTick + elapsed / samplesPerTick`;
+            // through a tempo map that sample's tick comes from the map.
+            const noteGainAt = warp
+              ? (tick: number) =>
+                  gainAt(
+                    warp.tick(
+                      start + (tick - note.startTick) * context.samplesPerTick,
+                    ),
+                  )
+              : gainAt;
             renderSynthNote(
               dry,
               stereo ? dryR : undefined,
@@ -424,14 +524,14 @@ export class StemRenderer {
               start,
               length,
               voice,
-              gainAt,
+              noteGainAt,
             );
           }
         } else {
           const drums = isDrumInstrument(track?.instrument);
-          for (const note of notes) {
+          for (const note of played) {
             if (drums) renderDrumNote(dry, note, track, context);
-            else renderToneNote(dry, note, track, context);
+            else renderToneNote(dry, note, track, context, tuning);
           }
         }
         if (track) applyMonoChain(dry, track, context);
@@ -526,12 +626,26 @@ export class StemRenderer {
     // Linear effects superpose, so folding the tail onto the start yields
     // the steady state of the loop playing forever.
     if (samples > frames) foldTail(mixL, mixR, frames, samples);
-    const pcm = toPcm(mixL, mixR, frames);
+    // The song master (src/audio/master.ts); none leaves the mix untouched.
+    const mastered = applyMaster(
+      mixL,
+      mixR,
+      frames,
+      sampleRate,
+      score.master,
+      options.loop === true,
+    );
+    // A master's output is a finished level, so its reduction to 16 bits is
+    // TPDF-dithered (seeded: renders stay byte-identical run to run).
+    const pcm = mastered
+      ? toPcm(mastered.left, mastered.right, frames, true)
+      : toPcm(mixL, mixR, frames);
     return Object.freeze({
       sampleRate,
       channels: RENDER_CHANNELS,
       frames,
       pcm,
+      ...(mastered ? { master: mastered.report } : {}),
     });
   }
 
@@ -630,12 +744,59 @@ function foldTail(
 }
 
 /** Interleaved 16-bit PCM of the first `frames` mix samples. */
+/**
+ * The song master over an already summed 16-bit mix (an arrangement
+ * rendered in windows), so the whole song is limited and normalized as one
+ * pass is. Undefined when the master is absent or bypassed.
+ */
+export function masterSummedPcm(
+  pcm: Int16Array,
+  frames: number,
+  sampleRate: number,
+  master: SongMaster | undefined,
+  loop: boolean,
+): { pcm: Int16Array; report: MasterReport } | undefined {
+  const left = new Float64Array(frames);
+  const right = new Float64Array(frames);
+  for (let index = 0; index < frames; index += 1) {
+    left[index] = pcm[index * 2]! / 32767;
+    right[index] = pcm[index * 2 + 1]! / 32767;
+  }
+  const mastered = applyMaster(left, right, frames, sampleRate, master, loop);
+  if (!mastered) return undefined;
+  return {
+    pcm: toPcm(mastered.left, mastered.right, frames, true),
+    report: mastered.report,
+  };
+}
+
 function toPcm(
   mixL: Float64Array,
   mixR: Float64Array,
   frames: number,
+  dither = false,
 ): Int16Array {
   const pcm = new Int16Array(frames * RENDER_CHANNELS);
+  if (dither) {
+    // Triangular dither of +-1 LSB: the sum of two uniform values, from a
+    // fixed-seed xorshift so every render of a score dithers the same way.
+    let state = 0x9e3779b9;
+    const uniform = () => {
+      state ^= state << 13;
+      state ^= state >>> 17;
+      state ^= state << 5;
+      return (state >>> 0) / 4_294_967_296;
+    };
+    for (let index = 0; index < frames; index += 1) {
+      pcm[index * 2] = clamp16(
+        Math.round(mixL[index]! * 32767 + uniform() - uniform()),
+      );
+      pcm[index * 2 + 1] = clamp16(
+        Math.round(mixR[index]! * 32767 + uniform() - uniform()),
+      );
+    }
+    return pcm;
+  }
   for (let index = 0; index < frames; index += 1) {
     pcm[index * 2] = clamp16(mixL[index]! * 32767);
     pcm[index * 2 + 1] = clamp16(mixR[index]! * 32767);
@@ -680,12 +841,20 @@ function stemKey(
     context.score.beatsPerBar,
     context.sampleRate,
     context.samples,
+    // Tempo map, meter changes and fermatas move every note.
+    ...(context.score.time ? [context.score.time] : []),
     // Sampler stems also depend on the decoded files: a replaced or missing
     // sample changes the key even when the score did not change.
     ...(bank && track?.sampler ? [samplerVoiceDigest(track, bank)] : []),
     ...(wavetableId ? [wavetableId] : []),
     // A convolution reverb's impulse (its sha256 for a sample).
     ...(impulseId ? [impulseId] : []),
+    // The song tuning, and the key whose tonic is the default root.
+    ...(context.score.tuning || track?.tuning
+      ? [context.score.tuning ?? null, context.score.key]
+      : []),
+    // Seeded noise follows the window origin of an arranged render.
+    ...(context.seedTick ? [`seed:${context.seedTick}`] : []),
   ]);
 }
 
@@ -708,7 +877,11 @@ function renderSamplerNotes(
   context: RenderContext,
   bank: SampleBank,
 ): void {
-  const timing = { score: context.score, sampleRate: context.sampleRate };
+  const timing = {
+    score: context.score,
+    sampleRate: context.sampleRate,
+    ...(context.warp ? { warp: context.warp } : {}),
+  };
   renderSamplerVoices(
     target,
     planSamplerVoices(track, notes, bank, timing),
@@ -732,7 +905,8 @@ function noteSpan(
   note: Note,
   context: RenderContext,
 ): { start: number; length: number } {
-  const { score, sampleRate } = context;
+  const { score, sampleRate, warp } = context;
+  if (warp) return warpedSpan(warp, note.startTick, note.durationTicks);
   const start = Math.max(
     0,
     Math.floor(
@@ -755,13 +929,18 @@ function renderToneNote(
   note: Note,
   track: Track | undefined,
   context: RenderContext,
+  tuning?: TuningTable,
 ): void {
   const { sampleRate, samples, samplesPerTick } = context;
   const instrument = track?.instrument ?? "sine";
   const { start, length } = noteSpan(note, context);
   const end = Math.min(samples, start + length);
-  const frequency = 440 * 2 ** ((note.pitch - 69) / 12);
+  const frequency = noteHz(note.pitch, note.cents, tuning);
+  if (!(frequency > 0)) return;
   const velocity = Math.max(0, Math.min(1, note.velocity));
+  const performance = (note as PerformedNote).performance;
+  const cents = performance?.cents;
+  let bent = 0;
   for (let index = start; index < end; index += 1) {
     const elapsed = index - start;
     const remaining = end - index;
@@ -771,9 +950,24 @@ function renderToneNote(
       Math.min(attack, release) *
       velocity *
       0.28 *
-      trackGainAt(track, note.startTick + elapsed / samplesPerTick);
-    const phase = (frequency * elapsed) / sampleRate;
-    target[index]! += legacyWave(instrument, phase) * envelope;
+      trackGainAt(
+        track,
+        context.warp
+          ? context.warp.tick(index)
+          : note.startTick + elapsed / samplesPerTick,
+      );
+    // Plain notes keep the closed-form phase (byte-identical output).
+    let phase = (frequency * elapsed) / sampleRate;
+    if (cents) {
+      phase = bent;
+      bent +=
+        (frequency * 2 ** (cents(elapsed / sampleRate) / 1200)) / sampleRate;
+    }
+    const damp = performance?.damp;
+    const t = elapsed / sampleRate;
+    const held =
+      damp && t > damp.from ? Math.exp(-(t - damp.from) / damp.tau) : 1;
+    target[index]! += legacyWave(instrument, phase) * envelope * held;
   }
 }
 
@@ -799,7 +993,9 @@ function renderDrumNote(
     start + Math.ceil((kit?.seconds ?? MAX_DRUM_SECONDS) * sampleRate),
   );
   const voice = drumVoiceForPitch(note.pitch);
-  const random = seededRandom(`${note.id}:${note.startTick}`);
+  const random = seededRandom(
+    `${note.id}:${note.startTick + (context.seedTick ?? 0)}`,
+  );
   const velocity = Math.max(0, Math.min(1, note.velocity));
   let phase = 0;
   let previousNoise = 0;
@@ -865,7 +1061,12 @@ function renderDrumNote(
       release *
       velocity *
       0.5 *
-      trackGainAt(track, note.startTick + (index - start) / samplesPerTick);
+      trackGainAt(
+        track,
+        context.warp
+          ? context.warp.tick(index)
+          : note.startTick + (index - start) / samplesPerTick,
+      );
   }
 }
 
@@ -892,7 +1093,13 @@ function applyPan(
   for (let index = 0; index < dry.length; index += 1) {
     if (lane.length > 0 && index % CONTROL_SAMPLES === 0)
       [gainL, gainR] = gains(
-        interpolateAutomation(lane, index / context.samplesPerTick, staticPan),
+        interpolateAutomation(
+          lane,
+          context.warp
+            ? context.warp.tick(index)
+            : index / context.samplesPerTick,
+          staticPan,
+        ),
       );
     const sample = dry[index]!;
     left[index] = sample * gainL;
@@ -930,16 +1137,29 @@ function wavetableHook(
     lane.length > 0
       ? (tick: number) => interpolateAutomation(lane, tick, settings.wt ?? 0)
       : undefined;
+  const warp = context.warp;
   return {
     id: table.id,
-    oscillatorFor: (note) =>
-      wavetableOscillator(table, settings, note, {
+    oscillatorFor: (note) => {
+      const span = noteSpan(note, context);
+      return wavetableOscillator(table, settings, note, {
         sampleRate: context.sampleRate,
         samplesPerTick: context.samplesPerTick,
         secondsPerTick: context.samplesPerTick / context.sampleRate,
-        gate: noteSpan(note, context).length / context.sampleRate,
-        positionAt,
-      }),
+        gate: span.length / context.sampleRate,
+        // Through a tempo map the lane is read at the sample's song tick.
+        positionAt:
+          warp && positionAt
+            ? (tick: number) =>
+                positionAt(
+                  warp.tick(
+                    span.start +
+                      (tick - note.startTick) * context.samplesPerTick,
+                  ),
+                )
+            : positionAt,
+      });
+    },
   };
 }
 
@@ -975,3 +1195,58 @@ function writeAscii(target: Uint8Array, offset: number, value: string): void {
 function clamp16(value: number): number {
   return Math.max(-32_768, Math.min(32_767, Math.round(value)));
 }
+
+/** A named point in a WAV export: a sample frame and its label. */
+export type WavCue = Readonly<{ frame: number; label: string }>;
+
+/**
+ * Append a `cue ` chunk and a `LIST adtl` chunk of `labl` labels, so DAWs
+ * and DJ tools show the cues (dawg writes section starts). No cues returns
+ * the bytes unchanged.
+ */
+export function withWavCues(
+  bytes: Uint8Array,
+  cues: readonly WavCue[],
+): Uint8Array {
+  if (cues.length === 0 || bytes.byteLength < 12) return bytes;
+  const encoder = new TextEncoder();
+  const labels = cues.map((cue) =>
+    encoder.encode(`${cue.label.slice(0, 200)}\0`),
+  );
+  const cueSize = 4 + 24 * cues.length;
+  const lablSizes = labels.map((text) => 4 + text.byteLength);
+  const adtlSize =
+    4 + lablSizes.reduce((sum, size) => sum + 8 + size + (size % 2), 0);
+  const base = bytes.byteLength + (bytes.byteLength % 2);
+  const out = new Uint8Array(base + 8 + cueSize + 8 + adtlSize);
+  out.set(bytes);
+  const view = new DataView(out.buffer);
+  let at = base;
+  writeAscii(out, at, "cue ");
+  view.setUint32(at + 4, cueSize, true);
+  view.setUint32(at + 8, cues.length, true);
+  at += 12;
+  cues.forEach((cue, index) => {
+    const frame = Math.max(0, Math.round(cue.frame));
+    view.setUint32(at, index + 1, true);
+    view.setUint32(at + 4, frame, true);
+    writeAscii(out, at + 8, "data");
+    view.setUint32(at + 12, 0, true);
+    view.setUint32(at + 16, 0, true);
+    view.setUint32(at + 20, frame, true);
+    at += 24;
+  });
+  writeAscii(out, at, "LIST");
+  view.setUint32(at + 4, adtlSize, true);
+  writeAscii(out, at + 8, "adtl");
+  at += 12;
+  labels.forEach((text, index) => {
+    writeAscii(out, at, "labl");
+    view.setUint32(at + 4, lablSizes[index]!, true);
+    view.setUint32(at + 8, index + 1, true);
+    out.set(text, at + 12);
+    at += 8 + lablSizes[index]! + (lablSizes[index]! % 2);
+  });
+  view.setUint32(4, out.byteLength - 8, true);
+  return out;
+}