@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/live.ts

@@ -19,10 +19,18 @@ import {
 import { bpmAtTick } from "../../core/tempo.ts";
 import { EMPTY_SAMPLE_BANK, sampleKey, type SampleBank } from "./samples.ts";
 import { RENDER_CHANNELS, renderScorePcm } from "./wav.ts";
-import { engineFor } from "./instruments.ts";
+import { engineFor, RING_OUT_FADE_SECONDS } from "./instruments.ts";
+import { chordDigest, chordTimeline } from "./granular.ts";
+import { resolveGranular } from "../../core/granular.ts";
 import { noteHz, resolveTuning } from "../../core/tuning.ts";
 import { liveFitPending, withLiveFit } from "./fit.ts";
+import { isOrganFamily } from "../../core/keys.ts";
 import type { LiveFullReply, LiveFullRequest } from "./live-worker.ts";
+import { isBowed, liveStringTrack } from "./strings/engine.ts";
+import { resolveString } from "../../core/strings.ts";
+import { singTrack } from "../../core/sing.ts";
+import { warmGlottal } from "./dsp/glottal.ts";
+import { withSingHorizon } from "./sing/engine.ts";
 
 /** A rendered live note: interleaved stereo 16-bit PCM. */
 export type LiveNotePcm = Readonly<{
@@ -37,11 +45,22 @@ export type LiveNotePcm = Readonly<{
    */
   fitting?: true;
   /**
-   * True when this is only the first window of a guitar-rig note
+   * True when this is only the first window of a guitar-rig or bowed note
    * (`LIVE_RIG_WINDOW_SECONDS`): call `LiveSynth.render` again with
    * `full: true` off the key path and swap the result in by voice id.
    */
   partial?: boolean;
+  /**
+   * The organ clock tick a first window rendered at: pass it back as the
+   * request's `clock` for the full pass so the wheels and rotors continue.
+   */
+  clock?: number;
+  /**
+   * The key's release does not fade the voice: it rings to the end of its
+   * rendered tail (0.6.1 modal `damp 0`), which ends in a `RING_OUT_FADE_SECONDS`
+   * fade when the length cap cut it.
+   */
+  ringOut?: true;
 }>;
 
 export type LiveNoteRequest = Readonly<{
@@ -58,6 +77,8 @@ export type LiveNoteRequest = Readonly<{
   tick?: number;
   /** Render the whole note even through a guitar rig (the background pass). */
   full?: boolean;
+  /** An organ note's clock tick from its first window (`LiveNotePcm.clock`). */
+  clock?: number;
 }>;
 
 /**
@@ -78,8 +99,21 @@ const CACHE_ENTRIES = 96;
  */
 export class LiveSynth {
   private readonly cache = new Map<string, LiveNotePcm>();
+  /** f061-organ: the live organ clock's origin (performance.now ms). */
+  private readonly organEpoch = performance.now();
 
-  public constructor(private readonly sampleRate: number) {}
+  /**
+   * `fastTail: false` always renders the whole tail window (tests compare
+   * the release-sized buffer against it).
+   */
+  public constructor(
+    private readonly sampleRate: number,
+    private readonly options: Readonly<{
+      fastTail?: boolean;
+      /** Called with each one-note render's buffer length, in frames. */
+      onRender?: (frames: number) => void;
+    }> = {},
+  ) {}
 
   public get rate(): number {
     return this.sampleRate;
@@ -122,6 +156,38 @@ export class LiveSynth {
     );
     const velocity = Math.max(0, Math.min(1, request.velocity));
     const pitch = Math.max(0, Math.min(127, Math.round(request.pitch)));
+    // f061-organ: one rotating speaker and one set of free-running wheels
+    // per organ track. Each key renders from the song tick it sounds at
+    // (or the synth's own clock when stopped), so successive notes share
+    // the track's rotor and wheel phases instead of restarting them.
+    const organTick =
+      track.keys && isOrganFamily(track.instrument)
+        ? Math.max(
+            0,
+            Math.round(
+              request.clock ??
+                request.tick ??
+                ((performance.now() - this.organEpoch) / 1000) * ticksPerSecond,
+            ),
+          )
+        : undefined;
+    // Granular `quant chord` (0.6.1): a live note snaps to the song's
+    // chords at the played tick, as the offline render of the same note.
+    const quantChord =
+      track.granular !== undefined &&
+      liveEngine?.id === "granular" &&
+      resolveGranular(track.granular).quant === "chord"
+        ? { score, tick: request.tick ?? 0 }
+        : undefined;
+    const chord = quantChord
+      ? chordDigest(
+          chordTimeline(score),
+          quantChord.tick,
+          quantChord.tick +
+            durationTicks +
+            Math.ceil(liveEngine!.tailSeconds(track, pitch) * ticksPerSecond),
+        )
+      : undefined;
     const key = JSON.stringify([
       liveTrack(track),
       pitch,
@@ -137,6 +203,7 @@ export class LiveSynth {
       ...(score.tuning || track.tuning
         ? [score.tuning ?? null, score.key]
         : []),
+      ...(organTick !== undefined ? [`organ:${organTick}`] : []),
       // A 0.6 engine's assets, and the key it may tune to.
       ...(liveEngine
         ? [
@@ -147,21 +214,48 @@ export class LiveSynth {
             score.key ?? null,
           ]
         : []),
+      ...(chord ? [chord] : []),
     ]);
-    return { track, score, bpm, seconds, durationTicks, velocity, pitch, key };
+    return {
+      track,
+      score,
+      bpm,
+      seconds,
+      durationTicks,
+      velocity,
+      pitch,
+      key,
+      organTick,
+      quantChord,
+    };
   }
 
   public render(request: LiveNoteRequest): LiveNotePcm | undefined {
     const plan = this.plan(request);
     if (!plan) return undefined;
-    const { track, score, bpm, seconds, durationTicks, velocity, pitch, key } =
-      plan;
+    const {
+      track,
+      score,
+      bpm,
+      seconds,
+      durationTicks,
+      velocity,
+      pitch,
+      key,
+      organTick,
+      quantChord,
+    } = plan;
     const liveEngine = engineFor(track);
     // The first window of a rig note: its own cache entry, swapped for the
     // whole note once the background pass has rendered it.
+    // Organs too: wheels, rotors and drive cost 4-8 ms per note-second.
     const windowed =
       request.full !== true &&
-      hasRig(track) &&
+      (hasRig(track) ||
+        organTick !== undefined ||
+        bowedTrack(track) ||
+        hasFormant(track) ||
+        singTrack(track)) &&
       seconds > LIVE_RIG_WINDOW_SECONDS &&
       !this.cache.has(key);
     if (windowed) {
@@ -206,22 +300,8 @@ export class LiveSynth {
       : 0;
     // Fitted sample windows over 8 s fit in the background (silent until
     // ready, never at the wrong pitch); shorter ones fit synchronously.
-    const audio = withLiveFit(() =>
-      renderScorePcm(single, {
-        sampleRate: this.sampleRate,
-        // The renderer's shortest one-shot is 1 s; the window is cut below.
-        maxSeconds: windowed
-          ? 1
-          : Math.max(MAX_LIVE_NOTE_SECONDS + 4, seconds + tail),
-        ...(request.samples ? { samples: request.samples } : {}),
-      }),
-    );
-    const frames = windowed
-      ? Math.min(
-          audibleFrames(audio.pcm),
-          Math.round(LIVE_RIG_WINDOW_SECONDS * this.sampleRate),
-        )
-      : audibleFrames(audio.pcm);
+    const windowFrames = Math.round(LIVE_RIG_WINDOW_SECONDS * this.sampleRate);
+    const horizon = windowed ? windowFrames : Infinity;
     const release = liveEngine?.releaseSeconds
       ? liveEngine.releaseSeconds(
           track,
@@ -233,9 +313,51 @@ export class LiveSynth {
           ),
         )
       : tail;
+    const renderFor = (maxSeconds: number) => {
+      const out = withLiveFit(() =>
+        withSingHorizon(horizon, () =>
+          renderScorePcm(single, {
+            sampleRate: this.sampleRate,
+            maxSeconds,
+            ...(request.samples ? { samples: request.samples } : {}),
+            ...(organTick ? { seedTick: organTick } : {}),
+            ...(quantChord ? { quantChord } : {}),
+          }),
+        ),
+      );
+      this.options.onRender?.(out.frames);
+      return out;
+    };
+    const fullSeconds = Math.max(MAX_LIVE_NOTE_SECONDS + 4, seconds + tail);
+    // A damped key decays 60 dB per 4.6 x its release (a linear fade of the
+    // same energy), so 12 x release is past -150 dB: silent in 16 bits. The
+    // renderer is causal, so the short buffer is the full one's prefix; a
+    // note still sounding at its end falls back to the full window.
+    const shortSeconds =
+      !windowed &&
+      this.options.fastTail !== false &&
+      liveFastTail(track, liveEngine !== undefined)
+        ? seconds + Math.min(tail, LIVE_TAIL_RELEASES * release) + 0.1
+        : Infinity;
+    let audio =
+      // The renderer's shortest one-shot is 1 s; the window is cut below.
+      windowed ? renderFor(1) : renderFor(Math.min(fullSeconds, shortSeconds));
+    if (
+      shortSeconds < fullSeconds &&
+      audibleFrames(audio.pcm) >
+        audio.frames - Math.round(LIVE_TAIL_GUARD_SECONDS * this.sampleRate)
+    )
+      audio = renderFor(fullSeconds);
+    const frames = windowed
+      ? Math.min(audibleFrames(audio.pcm), windowFrames)
+      : audibleFrames(audio.pcm);
+    const ringOut = !windowed && liveEngine?.ringOut?.(track) === true;
+    const pcm = audio.pcm.subarray(0, frames * RENDER_CHANNELS);
+    if (ringOut) fadeCutTail(pcm, frames, this.sampleRate);
     const rendered: LiveNotePcm = {
-      pcm: audio.pcm.subarray(0, frames * RENDER_CHANNELS),
+      pcm,
       frames,
+      ...(ringOut ? { ringOut: true as const } : {}),
       ...(liveEngine
         ? {
             releaseSeconds: Math.min(
@@ -245,8 +367,11 @@ export class LiveSynth {
           }
         : {}),
       ...(windowed ? { partial: true } : {}),
+      ...(windowed && organTick !== undefined ? { clock: organTick } : {}),
     };
     if (liveFitPending()) return { ...rendered, fitting: true };
+    // Organ keys render at their song tick: caching them would only evict.
+    if (organTick !== undefined) return rendered;
     this.cache.set(windowed ? `${key}#window` : key, rendered);
     this.trim();
     return rendered;
@@ -261,22 +386,70 @@ export class LiveSynth {
   }
 }
 
+/**
+ * Pays a voice's one-off costs before a key can sound (formant.md 4.5): the
+ * sing engine builds its LF glottal tables (about 50 ms) on first use and
+ * its inner loops need a pass to compile, so the first sing key of a session
+ * would miss the 15 ms first-window budget by 4x. Every other voice has the
+ * same shape at a smaller scale: a cold first press of a grand, a bowed
+ * cello, a granular swarm or a track with effects costs 2-4x a warm one
+ * (docs/perf.md, `live.*`). Play mode calls this when it opens on a track,
+ * so the first key costs what later keys do. The warm render goes
+ * through a throwaway synth, so no cache entry or state is left behind.
+ */
+export function warmLive(
+  score: TrackScore,
+  trackId: string,
+  sampleRate: number,
+): void {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (!track) return;
+  if (singTrack(track)) warmGlottal();
+  const synth = new LiveSynth(sampleRate);
+  for (const pitch of [48, 60])
+    synth.render({ score, trackId, pitch, velocity: 0.8, seconds: 0.3 });
+}
+
 /**
  * The track as it sounds live: audible regardless of mute and solo, and
  * without track `time`, so a key sounds once, as played, not re-placed.
  */
 function liveTrack(track: Track): Track {
-  // A held key is the performance: the recorded pedal and the render-time
+  // A held key is the performance: the recorded pedals and the render-time
   // humanize stay out of it. The velocity curve stays, so a key sounds like
   // the note it records as.
   const {
     solo: _solo,
     time: _time,
     pedal: _pedal,
+    softPedal: _softPedal,
+    sostenuto: _sostenuto,
     humanize: _humanize,
     ...rest
   } = track;
-  return { ...rest, muted: false };
+  // A bowed section plays two players live (f061-bowed render budget).
+  return liveStringTrack({ ...rest, muted: false });
+}
+
+/**
+ * Whether the track is a bowed string: a held bow costs about 5 ms per
+ * second, so it windows like a rig (the bow loop is causal too).
+ */
+function bowedTrack(track: Track): boolean {
+  return (
+    track.instrument === "string" &&
+    track.string !== undefined &&
+    isBowed(resolveString(track.string))
+  );
+}
+
+/**
+ * Whether the track plays through the 0.7 formant fx. It is not causal (one
+ * STFT frame of lookahead), but the window renders a 1 s source, well past
+ * the 0.75 s window plus one frame, so the window is an exact prefix.
+ */
+function hasFormant(track: Track): boolean {
+  return Boolean(track.fx?.formant);
 }
 
 /** Whether the track plays through a guitar rig stage. */
@@ -299,6 +472,53 @@ function samplerDigest(track: Track, bank: SampleBank | undefined): string[] {
 }
 
 /** Frames up to the last non-silent sample, so mixing skips the dead tail. */
+/**
+ * A ring-out note cut by the render length still sounds at its last frame:
+ * fade its final `RING_OUT_FADE_SECONDS` linearly to zero so the cap never
+ * clicks (each step stays under -60 dB of full scale). A tail that already
+ * decayed to silence is left alone.
+ */
+export function fadeCutTail(
+  pcm: Int16Array,
+  frames: number,
+  sampleRate: number,
+): void {
+  if (frames === 0) return;
+  const last = (frames - 1) * RENDER_CHANNELS;
+  // Below -60 dBFS the cut is inaudible.
+  if (Math.abs(pcm[last]!) < 33 && Math.abs(pcm[last + 1]!) < 33) return;
+  const fade = Math.min(frames, Math.round(RING_OUT_FADE_SECONDS * sampleRate));
+  for (let i = 0; i < fade; i += 1) {
+    const frame = frames - fade + i;
+    const gain = (fade - 1 - i) / fade;
+    for (let c = 0; c < RENDER_CHANNELS; c += 1) {
+      const at = frame * RENDER_CHANNELS + c;
+      pcm[at] = Math.round(pcm[at]! * gain);
+    }
+  }
+}
+
+/** A short live render ends at 12 x the engine's release past the note. */
+const LIVE_TAIL_RELEASES = 12;
+/** Audio within this much of a short render's end means it was cut. */
+const LIVE_TAIL_GUARD_SECONDS = 0.05;
+
+/**
+ * Whether a live note may render a buffer sized by its engine's release
+ * rather than the whole tail window: only a 0.6 engine's dry track (echoes
+ * and reverb tails are not bounded by the key's release).
+ */
+function liveFastTail(track: Track, engine: boolean): boolean {
+  return (
+    engine &&
+    track.delay === undefined &&
+    track.reverb === undefined &&
+    (track.fx === undefined || Object.keys(track.fx).length === 0) &&
+    (track.fxAutomation === undefined ||
+      Object.keys(track.fxAutomation).length === 0)
+  );
+}
+
 function audibleFrames(pcm: Int16Array): number {
   let last = pcm.length - 1;
   while (last >= 0 && pcm[last] === 0) last -= 1;
@@ -344,6 +564,7 @@ export class LiveFullRenderer {
         velocity: request.velocity,
         seconds: request.seconds,
         ...(request.tick === undefined ? {} : { tick: request.tick }),
+        ...(request.clock === undefined ? {} : { clock: request.clock }),
         ...(request.samples ? { samples: request.samples } : {}),
       };
       try {