@hraness/dawg 0.6.0 → 0.6.1

package/src/audio/strings/engine.ts

@@ -22,6 +22,12 @@ import type { EngineContext, InstrumentEngine } from "../instruments.ts";
 import { applyBody, bodyFor, symKeys, sympathetic } from "./body.ts";
 import { clamp } from "./loop.ts";
 import { PluckString, type Exciter, type PluckSpec } from "./pluck.ts";
+import {
+  BowedString,
+  type BowControl,
+  type BowSpec,
+  type BowNote,
+} from "./bow.ts";
 
 const BLOCK = 128;
 /** Longest a single string may ring (seconds). */
@@ -84,8 +90,155 @@ export function noteSpec(
   };
 }
 
+/** Whether resolved values play the bowed voice (`exciter bow`). */
+export function isBowed(values: StringValues): boolean {
+  return values.exciter === "bow";
+}
+
+/** Play mode keeps a bowed section to two players (live budget). */
+export const LIVE_BOW_UNISON = 2;
+
+/** The track as play mode hears it: a bowed section capped at 2 players. */
+export function liveStringTrack(track: Track): Track {
+  if (track.instrument !== "string" || !track.string) return track;
+  const values = resolveString(track.string);
+  if (!isBowed(values) || (values.unison as number) <= LIVE_BOW_UNISON)
+    return track;
+  return { ...track, string: { ...track.string, unison: LIVE_BOW_UNISON } };
+}
+
+/** Bow lanes read every 32 samples (`string-<name>`, absent: the value). */
+const BOW_LANES = ["pressure", "speed", "sord", "dyn"] as const;
+
+/** The bowed spec and note fields for one note. */
+export function bowSpec(
+  values: StringValues,
+  note: PerformedNote,
+  track: Track,
+  context: EngineContext,
+): { spec: BowSpec; velocity: number; control?: (t: number) => BowControl } {
+  const at = (name: string) => valueAt(track, values, name, note.startTick);
+  let velocity = clamp(note.velocity, 0, 1);
+  const articulation = note.articulation;
+  const sens = clamp(values.vel as number, 0, 1);
+  velocity = 1 - sens * (1 - velocity);
+  let attack = values.attack as number;
+  let release = values.release as number;
+  // Detache (spec 4): staccato and ghost are short strokes, quick on and off.
+  if (articulation === "staccato" || articulation === "ghost") {
+    attack = Math.min(attack, 0.01);
+    release = Math.min(release, 0.03);
+  }
+  // A harder stroke presses harder (spec 4: pressure += 0.3 (vel - 0.5)).
+  const press = (p: number) => clamp(p + 0.3 * (velocity - 0.5), 0, 1);
+  // Accent and marcato bite: pressure +0.2 for the first 80 ms.
+  const bite = articulation === "accent" || articulation === "marcato";
+  const spec: BowSpec = {
+    decay: Math.max(0.02, at("ring")),
+    track: values.track as number,
+    damp: clamp(values.damp as number, 0, 1),
+    pos: clamp(at("pos"), 0.01, 0.5),
+    pressure: press(at("pressure")),
+    speed: clamp(at("speed"), 0, 1),
+    attack,
+    release,
+    tremhz: values.tremhz as number,
+    sord: clamp(at("sord"), 0, 1),
+  };
+  const lanes = BOW_LANES.filter(
+    (name) =>
+      (track.fxAutomation?.[`string-${name}` as FxLane]?.length ?? 0) > 0,
+  );
+  const dyn = clamp(values.dyn as number, 0, 1);
+  if (lanes.length === 0 && dyn === 1 && !bite) return { spec, velocity };
+  const fixed: BowControl = {
+    pressure: spec.pressure,
+    speed: spec.speed,
+    sord: spec.sord,
+    dyn,
+  };
+  const bitten: BowControl = {
+    ...fixed,
+    pressure: clamp(spec.pressure + 0.2, 0, 1),
+  };
+  if (lanes.length === 0)
+    return {
+      spec,
+      velocity,
+      control: bite ? (t) => (t < 0.08 ? bitten : fixed) : () => fixed,
+    };
+  // Lanes are read in ticks; warped songs read them at the note's tempo.
+  const ticksPerSecond = context.sampleRate / context.samplesPerTick;
+  const control = (t: number): BowControl => {
+    const tick = note.startTick + t * ticksPerSecond;
+    const lane = (name: string) =>
+      clamp(valueAt(track, values, name, tick), 0, 1);
+    return {
+      pressure: clamp(
+        press(lane("pressure")) + (bite && t < 0.08 ? 0.2 : 0),
+        0,
+        1,
+      ),
+      speed: lane("speed"),
+      sord: lane("sord"),
+      dyn: lane("dyn"),
+    };
+  };
+  return { spec, velocity, control };
+}
+
+/** The preset vibrato alone (a slur keeps it running). */
+function vibratoCurve(
+  note: PerformedNote,
+  values: StringValues,
+  track: Track,
+  player: Readonly<{ rate: number; depth: number; phase: number }> = SOLO,
+): ((t: number) => number) | undefined {
+  if (note.performance?.replaceVibrato) return undefined;
+  const rate = valueAt(track, values, "vib", note.startTick) * player.rate;
+  const depth =
+    valueAt(track, values, "vibmod", note.startTick) * 100 * player.depth;
+  const delay = values.vibdelay as number;
+  if (!(rate > 0 && depth > 0)) return undefined;
+  const phase = player.phase;
+  return (t: number) => {
+    if (t <= delay) return 0;
+    const fade = Math.min(1, (t - delay) / 0.15);
+    return depth * fade * Math.sin(2 * Math.PI * (rate * (t - delay) + phase));
+  };
+}
+
+const SOLO = { rate: 1, depth: 1, phase: 0 } as const;
+
+/** Longest seeded onset spread of a bowed section's players (spec 2). */
+export const SECTION_SPREAD = 0.025;
+
+/**
+ * One section player (spec 2, Ensemble): seeded vibrato rate x0.92-1.08,
+ * depth x0.8-1.2 and phase, and an onset up to 25 ms late (scaled down
+ * for notes under 0.25 s). The first player stays on the grid.
+ */
+export function sectionPlayer(
+  seed: number,
+  index: number,
+  hold: number,
+): { rate: number; depth: number; phase: number; onset: number } {
+  const h = seedHash(`${seed}:${index}:player`);
+  return {
+    rate: 0.92 + 0.16 * unit(h, 0, 1),
+    depth: 0.8 + 0.4 * unit(h, 1, 1),
+    phase: unit(h, 2, 1),
+    onset:
+      index === 0
+        ? 0
+        : SECTION_SPREAD * unit(h, 3, 1) * Math.min(1, hold / 0.25),
+  };
+}
+
 type Voice = {
-  string: PluckString;
+  string: PluckString | BowedString;
+  /** The string's pitch over the note's base pitch (a slur keeps it). */
+  ratio: number;
   start: number;
   pitch: number;
   group: number;
@@ -94,6 +247,26 @@ type Voice = {
   damp?: Readonly<{ from: number; tau: number }>;
 };
 
+/**
+ * Whether pending note `index` (starting at `start`) is a lone note: no
+ * other note starts with it, so a held single note may slur into it.
+ */
+function slurs(
+  pending: readonly { start: number }[],
+  index: number,
+  start: number,
+): boolean {
+  return (
+    pending[index - 1]?.start !== start && pending[index + 1]?.start !== start
+  );
+}
+
+/** A 64th note in samples at the song's start tempo (the slur window). */
+function slurWindow(context: EngineContext): number {
+  const ticks = (context.score.ticksPerBeat ?? 480) / 16;
+  return ticks * context.samplesPerTick;
+}
+
 /** Ring-out after the last note-off, in seconds. */
 export function stringTailSeconds(track: Track): number {
   const values = resolveString(track.string);
@@ -163,6 +336,7 @@ export function renderStrings(
   const octbelow = values.octbelow as number;
   const cap = Math.max(1, Math.round(values.voices as number));
   const tuning = context.tuning;
+  const bowed = isBowed(values);
   const L = new Float64Array(total);
   const R = dryR ? new Float64Array(total) : undefined;
   const voices: Voice[] = [];
@@ -183,6 +357,47 @@ export function renderStrings(
       next += 1;
       const baseHz = noteHz(note.pitch, note.cents, tuning);
       if (!(baseHz > 0) || baseHz >= 0.45 * sr) continue;
+      // Slur (bowed): a single note that starts while one earlier single
+      // note is still bowed moves that bow to the new pitch in 7 ms, with
+      // no new attack (legato articulation overlaps its notes, so it
+      // slurs too). Chords and double stops start new strokes.
+      if (bowed && slurs(pending, next - 1, start)) {
+        const held = voices.filter(
+          (v) => !v.string.done && v.string.offAt > start - v.start,
+        );
+        const groups = new Set(held.map((v) => v.group));
+        const pitches = new Set(held.map((v) => v.pitch));
+        // A true legato only: the held note lets go within a short window
+        // of the new one (a 64th note or 150 ms, legato's own overlap), or
+        // the new note is marked legato. A pedal or a note held under a
+        // moving line keeps sounding and the new note takes a new stroke.
+        const window = Math.max(0.15 * sr, slurWindow(context));
+        const letsGo =
+          note.articulation === "legato" ||
+          held.every((v) => v.start + v.string.offAt <= start + window);
+        const range = held.every((v) =>
+          (v.string as BowedString).canSlurTo(baseHz * v.ratio),
+        );
+        if (
+          letsGo &&
+          range &&
+          groups.size === 1 &&
+          pitches.size === 1 &&
+          held[0]!.start < start
+        ) {
+          const hold = holdSamples(note, start, context) / sr;
+          for (const v of held) {
+            (v.string as BowedString).slurTo(
+              baseHz * v.ratio,
+              start - v.start,
+              Math.max(0.01, hold),
+              note.performance?.cents,
+            );
+            v.pitch = note.pitch;
+          }
+          continue;
+        }
+      }
       // Restrike: the same key damps its previous string.
       for (const v of voices)
         if (v.pitch === note.pitch) v.string.releaseAt(start - v.start);
@@ -197,11 +412,10 @@ export function renderStrings(
         for (const v of held)
           if (v.group === oldest) v.string.releaseAt(start - v.start);
       }
-      const { spec, velocity } = noteSpec(values, note, track);
       const seed = seedHash(
         `${note.id}:${note.startTick + (context.seedTick ?? 0)}:string`,
       );
-      const strings: { hz: number; gain: number }[] = [];
+      const strings: { hz: number; gain: number; ratio: number }[] = [];
       // The course's tuning error belongs to the key, not to the strike: it
       // is seeded by track and key (so every velocity of a key beats the
       // same way) and centred, so the course's mean pitch is the table's.
@@ -213,42 +427,74 @@ export function renderStrings(
       for (let i = 0; i < unison; i += 1) {
         const d = unison > 1 ? (i / (unison - 1) - 0.5) * detune : 0;
         const jitter = jitters[i]! - meanJitter;
+        const ratio = 2 ** ((d * 100 + jitter) / 1200);
         strings.push({
-          hz: baseHz * 2 ** ((d * 100 + jitter) / 1200),
+          hz: baseHz * ratio,
           gain: 1 / Math.sqrt(unison),
+          ratio,
         });
       }
       if (oct > 0 && note.pitch < octbelow) {
         const up = noteHz(Math.min(127, note.pitch + 12), note.cents, tuning);
         const hz = up > 0 ? up : baseHz * 2;
-        if (hz < 0.45 * sr)
+        if (hz < 0.45 * sr) {
+          const tuned =
+            hz * 2 ** (((unit(course, unison, 1) - 0.5) * 4) / 1200);
           strings.push({
-            hz: hz * 2 ** (((unit(course, unison, 1) - 0.5) * 4) / 1200),
+            hz: tuned,
             gain: oct / Math.sqrt(unison),
+            ratio: tuned / baseHz,
           });
+        }
       }
       const hold = holdSamples(note, start, context) / sr;
-      const cents = centsCurve(note, values, track);
+      const pluck = bowed ? undefined : noteSpec(values, note, track);
+      const bow = bowed ? bowSpec(values, note, track, context) : undefined;
+      const cents = bowed
+        ? note.performance?.cents
+        : centsCurve(note, values, track);
+      const section = bowed && unison > 1;
       strings.forEach((s, i) => {
+        // Section players (not the octave string) are seeded as players.
+        const player =
+          section && i < unison ? sectionPlayer(seed, i, hold) : undefined;
+        const onset = player ? Math.round(player.onset * sr) : 0;
+        const vibrato = bowed
+          ? vibratoCurve(note, values, track, player)
+          : undefined;
         const pan =
           strings.length > 1 ? (i / (strings.length - 1) - 0.5) * spread : 0;
-        const string = new PluckString(
-          spec,
-          {
-            hz: s.hz,
-            velocity,
-            hold: Math.max(0.01, hold),
-            seed: seedHash(`${seed}:${i}`),
-            ...(cents ? { cents } : {}),
-          },
-          sr,
-          MAX_RING,
-        );
+        const common = {
+          hz: s.hz,
+          hold: Math.max(0.01, hold - onset / sr),
+          seed: seedHash(`${seed}:${i}`),
+          ...(cents ? { cents } : {}),
+        };
+        const string = bow
+          ? new BowedString(
+              bow.spec,
+              {
+                ...common,
+                velocity: bow.velocity,
+                ...(vibrato ? { vibrato } : {}),
+                ...(bow.control ? { control: bow.control } : {}),
+              } satisfies BowNote,
+              sr,
+              // A bow sustains for as long as the note is held.
+              Math.max(MAX_RING, hold + bow.spec.release + 1),
+            )
+          : new PluckString(
+              pluck!.spec,
+              { ...common, velocity: pluck!.velocity },
+              sr,
+              MAX_RING,
+            );
         const gl = R ? s.gain * Math.sqrt(0.5 - pan / 2) * Math.SQRT2 : s.gain;
         const gr = s.gain * Math.sqrt(0.5 + pan / 2) * Math.SQRT2;
         voices.push({
           string,
-          start,
+          ratio: s.ratio,
+          start: start + onset,
           pitch: note.pitch,
           group: start,
           gainL: gl,

package/src/audio/strings/measure.test-helpers.ts

@@ -24,6 +24,7 @@ export type TestNote = {
   seconds?: number;
   velocity?: number;
   performance?: PerformedNote["performance"];
+  articulation?: PerformedNote["articulation"];
 };
 
 /** Renders notes on a string track (mono, before effects). */
@@ -58,6 +59,7 @@ export function render(
     startTick: Math.round(((n.start ?? 0) * SR) / SPT),
     durationTicks: Math.round(((n.seconds ?? seconds) * SR) / SPT),
     ...(n.performance ? { performance: n.performance } : {}),
+    ...(n.articulation ? { articulation: n.articulation } : {}),
   })) as unknown as PerformedNote[];
   const dry = new Float64Array(samples);
   renderStrings(dry, undefined, performed, track, context);

package/src/audio/wav.ts

@@ -23,7 +23,11 @@ import {
 } from "./sampler.ts";
 import { EFFECT_NAMES, FX_PRESETS, effectSpec } from "../../core/fx.ts";
 import { seededRandom } from "./random.ts";
-import { engineFor, engineTailSeconds } from "./instruments.ts";
+import {
+  engineFor,
+  engineTailSeconds,
+  RING_OUT_FADE_SECONDS,
+} from "./instruments.ts";
 import {
   isStereoVoice,
   renderSynthNote,
@@ -46,6 +50,8 @@ import {
   applyStereoChain,
   delayTailFor,
   interpolateAutomation,
+  needsEffectNotes,
+  type EffectNote,
   reverbActive,
   reverbImpulse,
   reverbTailFor,
@@ -97,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. */
@@ -191,12 +210,13 @@ const MAX_ENGINE_TAIL_SECONDS = 30;
  * 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.
+ * renders are unchanged. `ringing` counts only ring-out tracks (0.6.1).
  */
-function oneShotEngineTail(score: TrackScore): number {
+function oneShotEngineTail(score: TrackScore, ringing = false): number {
   let tail = 0;
   for (const track of score.tracks) {
-    if (!engineFor(track)) continue;
+    const engine = engineFor(track);
+    if (!engine || (ringing && engine.ringOut?.(track) !== true)) continue;
     let lowest: number | undefined;
     for (const note of score.notes)
       if (
@@ -219,6 +239,9 @@ export 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. */
@@ -421,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);
@@ -485,7 +511,7 @@ export class StemRenderer {
       const engineDigests =
         engine && track
           ? [
-              ...(engine.assetDigests?.(track, bank) ?? []),
+              ...(engine.assetDigests?.(track, bank, score) ?? []),
               `key:${score.key ?? ""}`,
             ]
           : undefined;
@@ -545,7 +571,7 @@ export class StemRenderer {
           : { left, right };
         dry.fill(0);
         const synthVoice = !engine && !sampler && usesSynthVoice(track);
-        const stereo = engine
+        let stereo = engine
           ? engine.stereo(track!)
           : synthVoice && isStereoVoice(track);
         if (stereo) dryR.fill(0);
@@ -563,7 +589,16 @@ export class StemRenderer {
             bank,
           );
         } else if (sampler) {
-          if (track) renderSamplerNotes(dry, played, track, context, bank);
+          // 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 = {
@@ -603,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,
@@ -620,7 +660,7 @@ export class StemRenderer {
             target.left,
             target.right,
             track,
-            context,
+            chain,
             true,
             false,
           );
@@ -638,7 +678,7 @@ export class StemRenderer {
             target.left,
             target.right,
             track,
-            context,
+            chain,
             busOrbit === undefined,
           );
         stem = {
@@ -694,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(
@@ -800,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,
@@ -927,6 +996,10 @@ function stemKey(
       : []),
     // 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]}`]
+      : []),
   ]);
 }
 
@@ -941,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). */
@@ -973,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,