@hraness/dawg 0.5.0 → 0.6.1

package/src/audio/warp.ts

@@ -84,3 +84,64 @@ export function warpedSpan(
     length: Math.max(1, Math.floor(to - from)),
   };
 }
+
+/**
+ * A fitted sample window's position map (0.6 `bpm`/`len`/`fit`): output
+ * frames after the note start to window frames and back, both at the
+ * render rate. Through a tempo map the window follows ramps and steps;
+ * at constant tempo both directions are linear.
+ */
+export type FitMap = Readonly<{
+  /** Output frames the whole window takes. */
+  length: number;
+  /** Window frame sounding `e` output frames after the start. */
+  at(e: number): number;
+  /** Output frame (after the start) where window frame `p` sounds. */
+  outAt(p: number): number;
+}>;
+
+/**
+ * The map for a window of `frames` render-rate frames that advances
+ * `perBeat` window frames per song beat from `startTick`. Without a warp the
+ * song runs at `tempoBpm` throughout.
+ */
+export function beatFitMap(
+  warp: SampleWarp | undefined,
+  timing: Readonly<{
+    tempoBpm: number;
+    ticksPerBeat: number;
+    sampleRate: number;
+  }>,
+  startTick: number,
+  frames: number,
+  perBeat: number,
+): FitMap {
+  const { tempoBpm, ticksPerBeat, sampleRate } = timing;
+  if (!warp) {
+    const ratio = perBeat / ((sampleRate * 60) / tempoBpm);
+    return Object.freeze({
+      length: frames / ratio,
+      at: (e: number) => e * ratio,
+      outAt: (p: number) => p / ratio,
+    });
+  }
+  const origin = warp.sample(startTick);
+  const outAt = (p: number) =>
+    warp.sample(startTick + (p / perBeat) * ticksPerBeat) - origin;
+  return Object.freeze({
+    length: outAt(frames),
+    at: (e: number) =>
+      ((warp.tick(origin + e) - startTick) / ticksPerBeat) * perBeat,
+    outAt,
+  });
+}
+
+/** `fit`: the window fills `held` output frames, linearly. */
+export function spanFitMap(frames: number, held: number): FitMap {
+  const ratio = frames / Math.max(1, held);
+  return Object.freeze({
+    length: held,
+    at: (e: number) => e * ratio,
+    outAt: (p: number) => p / ratio,
+  });
+}

package/src/audio/wav.ts

@@ -23,6 +23,11 @@ import {
 } from "./sampler.ts";
 import { EFFECT_NAMES, FX_PRESETS, effectSpec } from "../../core/fx.ts";
 import { seededRandom } from "./random.ts";
+import {
+  engineFor,
+  engineTailSeconds,
+  RING_OUT_FADE_SECONDS,
+} from "./instruments.ts";
 import {
   isStereoVoice,
   renderSynthNote,
@@ -45,6 +50,8 @@ import {
   applyStereoChain,
   delayTailFor,
   interpolateAutomation,
+  needsEffectNotes,
+  type EffectNote,
   reverbActive,
   reverbImpulse,
   reverbTailFor,
@@ -96,6 +103,19 @@ export type RenderOptions = WavOptions &
      * a single pass of the whole song. Zero (the default) changes nothing.
      */
     seedTick?: number;
+    /**
+     * Song seconds at an arranged window's first frame (with a tempo map,
+     * more than `seedTick` at the base tempo); engines whose state runs on
+     * the song clock (organ wheels and rotors) start there.
+     */
+    seedSeconds?: number;
+    /** Per-track engine state at the window origin (`windowSeed`). */
+    seedState?: Readonly<Record<string, string>>;
+    /**
+     * The song whose chords a granular `quant chord` reads, at `tick` for
+     * this render's tick 0 (a live note renders alone). Absent: the score.
+     */
+    quantChord?: Readonly<{ score: TrackScore; tick: number }>;
   }>;
 
 /** Interleaved stereo 16-bit PCM plus its frame count. */
@@ -139,6 +159,9 @@ export const AVAILABLE_INSTRUMENTS = Object.freeze([
   "z_square",
   "z_tan",
   "z_noise",
+  // 0.6 instruments (src/audio/instruments.ts), one line per lane.
+  "granular",
+  "modal",
 ] as const);
 
 /** Per-track effects understood by the renderer and the agent, in chain
@@ -180,8 +203,33 @@ function oneShotSeconds(
 }
 /** Loop renders fold at most this much tail back onto the loop start. */
 const MAX_LOOP_TAIL_SECONDS = 8;
+/** A 0.6 engine's one-shot ring-out is capped here, not at the loop fold. */
+const MAX_ENGINE_TAIL_SECONDS = 30;
 
-type RenderContext = Readonly<{
+/**
+ * The longest 0.6 engine ring-out in `score`, capped at 30 s. One-shot
+ * renders (exports, previews) let engine tails reach their own cap; the
+ * 8 s cap applies only to loop folding. Zero without an engine, so legacy
+ * renders are unchanged. `ringing` counts only ring-out tracks (0.6.1).
+ */
+function oneShotEngineTail(score: TrackScore, ringing = false): number {
+  let tail = 0;
+  for (const track of score.tracks) {
+    const engine = engineFor(track);
+    if (!engine || (ringing && engine.ringOut?.(track) !== true)) continue;
+    let lowest: number | undefined;
+    for (const note of score.notes)
+      if (
+        note.trackId === track.id &&
+        (lowest === undefined || note.pitch < lowest)
+      )
+        lowest = note.pitch;
+    tail = Math.max(tail, engineTailSeconds(track, lowest));
+  }
+  return Math.min(MAX_ENGINE_TAIL_SECONDS, tail);
+}
+
+export type RenderContext = Readonly<{
   score: TrackScore;
   sampleRate: number;
   samples: number;
@@ -191,6 +239,9 @@ type RenderContext = Readonly<{
   /** Tempo map in samples (core/tempo.ts); absent: constant tempo. */
   warp?: SampleWarp;
   seedTick?: number;
+  seedSeconds?: number;
+  seedState?: Readonly<Record<string, string>>;
+  quantChord?: Readonly<{ score: TrackScore; tick: number }>;
 }>;
 
 /** Exact (fractional) loop length in frames at a sample rate. */
@@ -314,9 +365,15 @@ export class StemRenderer {
       Math.max(
         samplerTailSeconds(score, bank, sampleRate),
         ...score.tracks.map(synthTailSeconds),
+        // Zero without a registered 0.6 instrument engine.
+        ...score.tracks.map((track) => engineTailSeconds(track)),
       ),
     );
-    return oneShotSeconds(loopSecondsOf(score), samplerTail, reverbTail);
+    return oneShotSeconds(
+      loopSecondsOf(score),
+      Math.max(samplerTail, oneShotEngineTail(score)),
+      reverbTail,
+    );
   }
 
   public render(score: TrackScore, options: RenderOptions = {}): RenderedAudio {
@@ -338,6 +395,8 @@ export class StemRenderer {
       Math.max(
         samplerTailSeconds(score, bank, sampleRate),
         ...score.tracks.map(synthTailSeconds),
+        // Zero without a registered 0.6 instrument engine.
+        ...score.tracks.map((track) => engineTailSeconds(track)),
       ),
     );
     let frames: number;
@@ -367,7 +426,11 @@ export class StemRenderer {
     } else {
       const seconds = Math.min(
         maxSeconds,
-        oneShotSeconds(loopSeconds, samplerTail, reverbTail),
+        oneShotSeconds(
+          loopSeconds,
+          Math.max(samplerTail, oneShotEngineTail(score)),
+          reverbTail,
+        ),
       );
       frames = Math.max(1, Math.ceil(seconds * sampleRate));
       samples = frames;
@@ -381,6 +444,9 @@ export class StemRenderer {
       ...(bank.irs ? { irs: bank.irs } : {}),
       ...(warp ? { warp } : {}),
       ...(options.seedTick ? { seedTick: options.seedTick } : {}),
+      ...(options.seedSeconds ? { seedSeconds: options.seedSeconds } : {}),
+      ...(options.seedState ? { seedState: options.seedState } : {}),
+      ...(options.quantChord ? { quantChord: options.quantChord } : {}),
     };
     this.renders += 1;
     const { dry, dryR, left, right, mixL, mixR } = this.scratchFor(samples);
@@ -437,6 +503,18 @@ export class StemRenderer {
       const played = performed.get(trackId)!;
       const busOrbit = sharedOrbitOf(track);
       const sampler = isSamplerInstrument(track?.instrument);
+      // A 0.6 instrument engine (src/audio/instruments.ts), if registered
+      // and the track carries its field; undefined keeps today's voices.
+      const engine = engineFor(track);
+      // The song key always joins an engine's stem key: engines may tune to
+      // it (sympathetic strings) without a song tuning.
+      const engineDigests =
+        engine && track
+          ? [
+              ...(engine.assetDigests?.(track, bank, score) ?? []),
+              `key:${score.key ?? ""}`,
+            ]
+          : undefined;
       // 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;
@@ -449,6 +527,7 @@ export class StemRenderer {
         sampler ? bank : undefined,
         wavetable?.id,
         track ? reverbImpulse(track, sampleRate, bank.irs)?.id : undefined,
+        engineDigests,
       );
       let stem = this.stems.get(trackId);
       const caching = this.maxCacheBytes > 0;
@@ -464,6 +543,7 @@ export class StemRenderer {
               sampler ? bank : undefined,
               wavetable?.id,
               reverbImpulse(track, sampleRate, bank.irs)?.id,
+              engineDigests,
             )
           : undefined;
       if (stem?.key === key) stem.used = this.renders;
@@ -490,11 +570,35 @@ export class StemRenderer {
             }
           : { left, right };
         dry.fill(0);
-        const synthVoice = !sampler && usesSynthVoice(track);
-        const stereo = synthVoice && isStereoVoice(track);
+        const synthVoice = !engine && !sampler && usesSynthVoice(track);
+        let stereo = engine
+          ? engine.stereo(track!)
+          : synthVoice && isStereoVoice(track);
         if (stereo) dryR.fill(0);
-        if (sampler) {
-          if (track) renderSamplerNotes(dry, played, track, context, bank);
+        if (engine && track) {
+          engine.render(
+            dry,
+            stereo ? dryR : undefined,
+            played,
+            track,
+            {
+              ...context,
+              ticksPerBeat: score.ticksPerBeat,
+              ...(tuning ? { tuning } : {}),
+            },
+            bank,
+          );
+        } else if (sampler) {
+          // A resampled stereo file plays as stereo (0.6.1).
+          if (track)
+            stereo = renderSamplerNotes(
+              dry,
+              played,
+              track,
+              context,
+              bank,
+              dryR,
+            );
         } else if (synthVoice && track) {
           const gainAt = (tick: number) => trackGainAt(track, tick);
           const voice = {
@@ -534,8 +638,13 @@ export class StemRenderer {
             else renderToneNote(dry, note, track, context, tuning);
           }
         }
-        if (track) applyMonoChain(dry, track, context);
-        if (stereo && track) applyMonoChain(dryR, track, context);
+        // Note-aware stages (bloom, swell) see the notes; others never do.
+        const chain =
+          track && needsEffectNotes(track)
+            ? { ...context, notes: effectNotes(played, context, tuning) }
+            : context;
+        if (track) applyMonoChain(dry, track, chain);
+        if (stereo && track) applyMonoChain(dryR, track, chain);
         applyPan(
           dry,
           target.left,
@@ -551,7 +660,7 @@ export class StemRenderer {
             target.left,
             target.right,
             track,
-            context,
+            chain,
             true,
             false,
           );
@@ -569,7 +678,7 @@ export class StemRenderer {
             target.left,
             target.right,
             track,
-            context,
+            chain,
             busOrbit === undefined,
           );
         stem = {
@@ -625,6 +734,20 @@ export class StemRenderer {
       if (!groups.has(trackId)) this.evict(trackId);
     // Linear effects superpose, so folding the tail onto the start yields
     // the steady state of the loop playing forever.
+    // A ring-out longer than the fold (a gong past 8 s) would be cut there:
+    // fade its last RING_OUT_FADE_SECONDS so the fold never clicks. Only
+    // ringing 0.6 engine tracks qualify, so legacy loops are untouched.
+    if (
+      options.loop &&
+      samples > frames &&
+      oneShotEngineTail(score, true) > (samples - frames) / sampleRate
+    )
+      fadeEnd(
+        mixL,
+        mixR,
+        samples,
+        Math.round(RING_OUT_FADE_SECONDS * sampleRate),
+      );
     if (samples > frames) foldTail(mixL, mixR, frames, samples);
     // The song master (src/audio/master.ts); none leaves the mix untouched.
     const mastered = applyMaster(
@@ -731,6 +854,21 @@ function addStem(
 }
 
 /** Fold everything past `frames` back onto the loop start. */
+/** Fade the last `fade` of `samples` mix frames linearly to zero. */
+function fadeEnd(
+  mixL: Float64Array,
+  mixR: Float64Array,
+  samples: number,
+  fade: number,
+): void {
+  const n = Math.min(fade, samples);
+  for (let i = 0; i < n; i += 1) {
+    const gain = (n - 1 - i) / n;
+    mixL[samples - n + i]! *= gain;
+    mixR[samples - n + i]! *= gain;
+  }
+}
+
 function foldTail(
   mixL: Float64Array,
   mixR: Float64Array,
@@ -826,6 +964,7 @@ function stemKey(
   bank?: SampleBank,
   wavetableId?: string,
   impulseId?: string,
+  engineDigests?: readonly string[],
 ): string {
   let settings: Record<string, unknown> | null = null;
   if (track) {
@@ -849,12 +988,18 @@ function stemKey(
     ...(wavetableId ? [wavetableId] : []),
     // A convolution reverb's impulse (its sha256 for a sample).
     ...(impulseId ? [impulseId] : []),
+    // Assets a 0.6 instrument engine reads (absent without an engine).
+    ...(engineDigests ? [engineDigests] : []),
     // 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}`] : []),
+    ...(context.seedSeconds ? [`at:${context.seedSeconds}`] : []),
+    ...(track && context.seedState?.[track.id]
+      ? [`state:${context.seedState[track.id]}`]
+      : []),
   ]);
 }
 
@@ -869,25 +1014,34 @@ function samplerVoiceDigest(track: Track, bank: SampleBank): string[] {
     });
 }
 
-/** Sample voices of a sampler track into its mono dry buffer. */
+/**
+ * Sample voices of a sampler track into its mono dry buffer. When a voice
+ * plays a resampled stereo file (0.6.1), `target` takes the left channel,
+ * `targetRight` the right, and the result is true (the track is stereo).
+ */
 function renderSamplerNotes(
   target: Float64Array,
   notes: readonly Note[],
   track: Track,
   context: RenderContext,
   bank: SampleBank,
-): void {
+  targetRight: Float64Array,
+): boolean {
   const timing = {
     score: context.score,
     sampleRate: context.sampleRate,
     ...(context.warp ? { warp: context.warp } : {}),
   };
-  renderSamplerVoices(
-    target,
-    planSamplerVoices(track, notes, bank, timing),
-    timing,
-    (tick) => trackGainAt(track, tick),
-  );
+  const voices = planSamplerVoices(track, notes, bank, timing);
+  const gainAt = (tick: number) => trackGainAt(track, tick);
+  if (!voices.some((voice) => voice.stereo)) {
+    renderSamplerVoices(target, voices, timing, gainAt);
+    return false;
+  }
+  targetRight.fill(0);
+  renderSamplerVoices(target, voices, timing, gainAt, "left");
+  renderSamplerVoices(targetRight, voices, timing, gainAt, "right");
+  return true;
 }
 
 /** Track volume and volume automation at a score tick (pan is applied in stereo). */
@@ -901,6 +1055,24 @@ function trackGainAt(track: Track | undefined, tick: number): number {
   return trackGain * automatedGain;
 }
 
+/** The notes as note-aware effects see them (EffectContext.notes). */
+function effectNotes(
+  notes: readonly Note[],
+  context: RenderContext,
+  tuning: TuningTable | undefined,
+): EffectNote[] {
+  return notes.map((note) => {
+    const { start, length } = noteSpan(note, context);
+    return {
+      id: note.id,
+      start,
+      length,
+      hz: noteHz(note.pitch, note.cents, tuning),
+      velocity: note.velocity,
+    };
+  });
+}
+
 function noteSpan(
   note: Note,
   context: RenderContext,