@hraness/dawg 0.6.0 → 0.7.0

package/src/audio/wav.ts

@@ -9,6 +9,7 @@ import {
   type Track,
   type TrackScore,
 } from "../../core/score.ts";
+import { autotuneStemDigests } from "./autotune.ts";
 import { drumVoiceForPitch, isDrumInstrument } from "../../core/drums.ts";
 import {
   performanceTimingFor,
@@ -21,9 +22,19 @@ import {
   renderSamplerVoices,
   samplerTailSeconds,
 } from "./sampler.ts";
-import { EFFECT_NAMES, FX_PRESETS, effectSpec } from "../../core/fx.ts";
+import {
+  EFFECT_NAMES,
+  FX_CHAIN,
+  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,
+  type InstrumentEngine,
+} from "./instruments.ts";
 import {
   isStereoVoice,
   renderSynthNote,
@@ -31,7 +42,7 @@ import {
   usesSynthVoice,
   type VoiceContext,
 } from "./synth/voice.ts";
-import { legacyWave } from "./synth/oscillators.ts";
+import { legacyWaveFor } from "./synth/oscillators.ts";
 import {
   EMPTY_SAMPLE_BANK,
   sampleKey,
@@ -39,13 +50,23 @@ import {
   type SampleBank,
 } from "./samples.ts";
 import { synthKit } from "../../core/kits.ts";
-import { kitDrumSample, kitTailSeconds, newKitVoiceState } from "./kits.ts";
+import {
+  kitDrumSample,
+  kitTailSeconds,
+  METAL_SECONDS,
+  metalKindForPitch,
+  metalSample,
+  newKitVoiceState,
+  tomRatio,
+} from "./kits.ts";
 import {
   addReverbWet,
   applyMonoChain,
   applyStereoChain,
   delayTailFor,
   interpolateAutomation,
+  needsEffectNotes,
+  type EffectNote,
   reverbActive,
   reverbImpulse,
   reverbTailFor,
@@ -73,8 +94,13 @@ import {
   slowestBpmOf,
 } from "../../core/tempo.ts";
 import { sampleWarpFor, warpedSpan, type SampleWarp } from "./warp.ts";
+import { clipsDigest, hasClips, renderClips } from "./clips.ts";
+import { isGuideInstrument } from "../../core/clips.ts";
 import { applyMaster, type MasterReport } from "./master.ts";
 import type { SongMaster } from "../../core/master.ts";
+import { resolveTrackRef } from "../../core/routing.ts";
+import { resolveVocoder, VOCODER_INSTRUMENT } from "../../core/vocoder.ts";
+import { applyVocoder, autoGateDb } from "./vocoder/index.ts";
 
 export type WavOptions = Readonly<{ sampleRate?: number; maxSeconds?: number }>;
 
@@ -86,6 +112,12 @@ export type RenderOptions = WavOptions &
      * what the streaming engine plays; exports keep the default one-shot.
      */
     loop?: boolean;
+    /**
+     * 0.7 clips: a `vocal` track's guide notes sound as a soft sine. The
+     * live loop (audition, play mode) sets it; exports never do, so a
+     * rendered file holds only the clips.
+     */
+    guide?: boolean;
     /**
      * Decoded sampler voices (`SampleLibrary.load`). Without it sampler
      * tracks render silent; scores without samplers are unaffected.
@@ -97,6 +129,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. */
@@ -107,8 +152,36 @@ export type RenderedAudio = Readonly<{
   pcm: Int16Array;
   /** Loudness the song master reached; absent without a master. */
   master?: MasterReport;
+  /**
+   * Non-finite samples (NaN, Infinity) a track's source or effects made,
+   * zeroed before they could poison a feedback stage or the mix (q08);
+   * absent when every sample was finite.
+   */
+  nonFinite?: NonFiniteReport;
+}>;
+
+/** Where a render zeroed non-finite samples. */
+export type NonFiniteReport = Readonly<{
+  samples: number;
+  /** Track ids in render order, then `bus` for the bus returns. */
+  tracks: readonly string[];
 }>;
 
+/**
+ * Zeroes NaN and Infinity in `buffer` and returns how many it found. A
+ * NaN written into an Int16Array stores 0, and one fed to a filter, comb
+ * or reverb feedback silences everything after it.
+ */
+export function scrubNonFinite(buffer: Float64Array): number {
+  let count = 0;
+  for (let i = 0; i < buffer.length; i += 1)
+    if (!Number.isFinite(buffer[i]!)) {
+      buffer[i] = 0;
+      count += 1;
+    }
+  return count;
+}
+
 /** Output channel count for every render and export. */
 export const RENDER_CHANNELS = 2 as const;
 export const DEFAULT_SAMPLE_RATE = 22_050;
@@ -143,6 +216,8 @@ export const AVAILABLE_INSTRUMENTS = Object.freeze([
   // 0.6 instruments (src/audio/instruments.ts), one line per lane.
   "granular",
   "modal",
+  // 0.7 clips: a track of audio clips whose notes are guides.
+  "vocal",
 ] as const);
 
 /** Per-track effects understood by the renderer and the agent, in chain
@@ -191,12 +266,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 +295,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. */
@@ -265,6 +344,8 @@ type Stem = {
   /** Stem, pre-reverb pair and tail (counted in the cache budget). */
   bytes: number;
   used: number;
+  /** Non-finite samples zeroed while rendering it (0 or absent: none). */
+  nonFinite?: number;
   /** For a track with a reverb: its stem before the reverb, and the tail. */
   room?: Readonly<{
     /** `stemKey` of the track with its reverb mix and mix lane left out. */
@@ -283,6 +364,9 @@ type Stem = {
  * byte-identical to a cold render; mute and solo only pick which stems are
  * summed. Scratch buffers are reused across renders.
  */
+/** A guide note's level against a plain sine note (about -12 dB). */
+const GUIDE_LEVEL = 0.25;
+
 export class StemRenderer {
   private readonly maxCacheBytes: number;
   private readonly stems = new Map<string, Stem>();
@@ -293,6 +377,11 @@ export class StemRenderer {
   >();
   private cacheBytes = 0;
   private renders = 0;
+  /** Vocoder modulator taps by source key (0.7), kept one render. */
+  private readonly modSources = new Map<
+    string,
+    { tap: Float64Array; used: number }
+  >();
   private scratch: {
     dry: Float64Array;
     dryR: Float64Array;
@@ -421,9 +510,16 @@ 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);
+    const nonFinite: { samples: number; tracks: string[] } = {
+      samples: 0,
+      tracks: [],
+    };
     mixL.fill(0);
     mixR.fill(0);
     const tracks = new Map(score.tracks.map((track) => [track.id, track]));
@@ -434,6 +530,14 @@ export class StemRenderer {
       if (group) group.push(note);
       else groups.set(note.trackId, [note]);
     }
+    // Tracks with audio clips (0.7) render even without notes, after the
+    // tracks with notes, so songs without clips keep their sum order.
+    for (const track of score.tracks)
+      if (hasClips(track) && !groups.has(track.id)) groups.set(track.id, []);
+    // A built-in vocoder carrier following chords or a drone needs no notes.
+    for (const track of score.tracks)
+      if (!groups.has(track.id) && vocoderPlaysWithoutNotes(track))
+        groups.set(track.id, []);
     // 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);
@@ -482,13 +586,31 @@ export class StemRenderer {
       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 =
+      const clipDigest = track
+        ? clipsDigest(track, bank, options.guide === true)
+        : undefined;
+      const baseDigests =
         engine && track
           ? [
-              ...(engine.assetDigests?.(track, bank) ?? []),
+              ...(engine.assetDigests?.(track, bank, score) ?? []),
               `key:${score.key ?? ""}`,
+              ...(clipDigest === undefined ? [] : [`clips:${clipDigest}`]),
             ]
-          : undefined;
+          : clipDigest === undefined
+            ? undefined
+            : [`clips:${clipDigest}`];
+      // A vocoder carrier (0.7) also keys on its modulator's tap.
+      const vocoderSource = track?.vocoder
+        ? vocoderSourceOf(track, groups, performed, context, bank)
+        : undefined;
+      const withVocoder = vocoderSource
+        ? [...(baseDigests ?? []), vocoderSource.key]
+        : baseDigests;
+      // 0.7 autotune: its targets (guide notes, chords, key, tuning) and the
+      // pitch engine version join the stem key; absent adds nothing.
+      const engineDigests = track?.autotune
+        ? [...(withVocoder ?? []), ...autotuneStemDigests(track, score)]
+        : withVocoder;
       // 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;
@@ -544,67 +666,39 @@ export class StemRenderer {
             }
           : { left, right };
         dry.fill(0);
-        const synthVoice = !engine && !sampler && usesSynthVoice(track);
-        const stereo = engine
-          ? engine.stereo(track!)
-          : synthVoice && isStereoVoice(track);
-        if (stereo) dryR.fill(0);
-        if (engine && track) {
-          engine.render(
+        const stereo = renderVoiceInto(
+          dry,
+          dryR,
+          played,
+          track,
+          context,
+          score,
+          bank,
+          engine,
+          sampler,
+          wavetable,
+          tuning,
+          options.guide === true,
+        );
+        // The vocoder stage (0.7): after the voice, before the chain.
+        if (track && vocoderSource)
+          applyVocoder(
             dry,
             stereo ? dryR : undefined,
-            played,
+            this.vocoderTap(vocoderSource, context, bank),
             track,
-            {
-              ...context,
-              ticksPerBeat: score.ticksPerBeat,
-              ...(tuning ? { tuning } : {}),
-            },
-            bank,
+            context,
+            vocoderSource.gateDb,
           );
-        } else if (sampler) {
-          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 } : {}),
-          };
-          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,
-              note,
-              track,
-              start,
-              length,
-              voice,
-              noteGainAt,
-            );
-          }
-        } else {
-          const drums = isDrumInstrument(track?.instrument);
-          for (const note of played) {
-            if (drums) renderDrumNote(dry, note, track, context);
-            else renderToneNote(dry, note, track, context, tuning);
-          }
-        }
-        if (track) applyMonoChain(dry, track, context);
-        if (stereo && track) applyMonoChain(dryR, track, context);
+        // A non-finite source sample would poison every feedback stage.
+        let bad = scrubNonFinite(dry) + (stereo ? scrubNonFinite(dryR) : 0);
+        // 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,10 +714,12 @@ export class StemRenderer {
             target.left,
             target.right,
             track,
-            context,
+            chain,
             true,
             false,
           );
+          // The room's input: scrubbed so the saved pair is clean too.
+          bad += scrubNonFinite(target.left) + scrubNonFinite(target.right);
           const pre = {
             left: Float64Array.from(target.left),
             right: Float64Array.from(target.right),
@@ -638,9 +734,10 @@ export class StemRenderer {
             target.left,
             target.right,
             track,
-            context,
+            chain,
             busOrbit === undefined,
           );
+        bad += scrubNonFinite(target.left) + scrubNonFinite(target.right);
         stem = {
           key,
           left: target.left,
@@ -648,9 +745,14 @@ export class StemRenderer {
           bytes: target.left.byteLength * (saved ? 6 : 2),
           used: this.renders,
           ...(saved ? { room: saved } : {}),
+          ...(bad > 0 ? { nonFinite: bad } : {}),
         };
         if (caching) this.store(trackId, stem);
       }
+      if (stem.nonFinite) {
+        nonFinite.samples += stem.nonFinite;
+        nonFinite.tracks.push(trackId);
+      }
       if (track && busOrbit !== undefined) {
         let bus = buses.get(busOrbit);
         if (!bus)
@@ -694,7 +796,27 @@ 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);
+    // Bus returns: a last scrub before the master's own feedback stages.
+    const busBad = scrubNonFinite(mixL) + scrubNonFinite(mixR);
+    if (busBad > 0) {
+      nonFinite.samples += busBad;
+      nonFinite.tracks.push("bus");
+    }
     // The song master (src/audio/master.ts); none leaves the mix untouched.
     const mastered = applyMaster(
       mixL,
@@ -715,9 +837,40 @@ export class StemRenderer {
       frames,
       pcm,
       ...(mastered ? { master: mastered.report } : {}),
+      ...(nonFinite.samples > 0
+        ? {
+            nonFinite: Object.freeze({
+              samples: nonFinite.samples,
+              tracks: Object.freeze([...nonFinite.tracks]),
+            }),
+          }
+        : {}),
     });
   }
 
+  /**
+   * A vocoder modulator's mono tap over this render: the source's voice,
+   * through its mono chain for `tap: chain`, stereo summed (L+R)/2. Kept
+   * across renders under the stem cache budget, keyed by the source key.
+   */
+  private vocoderTap(
+    source: VocoderSource,
+    context: RenderContext,
+    bank: SampleBank,
+  ): Float64Array {
+    const known = this.modSources.get(source.key);
+    if (known && known.tap.length === context.samples) {
+      known.used = this.renders;
+      return known.tap;
+    }
+    const tap = renderVocoderTap(source, context, bank);
+    for (const [key, entry] of this.modSources)
+      if (entry.used < this.renders - 1) this.modSources.delete(key);
+    if (this.maxCacheBytes > 0)
+      this.modSources.set(source.key, { tap, used: this.renders });
+    return tap;
+  }
+
   private scratchFor(samples: number) {
     if (this.scratch.dry.length < samples) {
       this.scratch = {
@@ -800,6 +953,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,
@@ -925,8 +1093,14 @@ function stemKey(
     ...(context.score.tuning || track?.tuning
       ? [context.score.tuning ?? null, context.score.key]
       : []),
+    // Calibrated engines (0.7) render differently; absent keeps old keys.
+    ...(context.score.calibration ? [`cal:${context.score.calibration}`] : []),
     // 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 +1115,307 @@ function samplerVoiceDigest(track: Track, bank: SampleBank): string[] {
     });
 }
 
-/** Sample voices of a sampler track into its mono dry buffer. */
+/** A vocoder carrier's modulator: its track, notes, key and gate. */
+/** FX_CHAIN index of pan: a `tap: chain` modulator runs the stages before. */
+const TAP_END = FX_CHAIN.indexOf("pan");
+
+type VocoderSource = Readonly<{
+  track: Track;
+  played: readonly PerformedNote[];
+  tap: "chain" | "dry";
+  key: string;
+  gateDb: number;
+}>;
+
+/** True for a built-in carrier that sounds without notes (chords, drone). */
+function vocoderPlaysWithoutNotes(track: Track): boolean {
+  if (!track.vocoder || track.instrument !== VOCODER_INSTRUMENT) return false;
+  const follow = resolveVocoder(track.vocoder).follow;
+  return follow === "chords" || follow === "drone";
+}
+
+const assetGates = new WeakMap<DecodedSample, number>();
+
+/**
+ * The auto gate from a source's assets (its sampler files): the quietest
+ * file's 10th-percentile 10 ms frame level + 6 dB, never the render span.
+ * A source without assets (a synth) has no noise floor: the gate is off.
+ */
+function sourceGateDb(source: Track, bank: SampleBank): number {
+  let gate: number | undefined;
+  for (const voice of Object.keys(source.sampler?.voices ?? {}).sort()) {
+    const sample = bank.voices.get(sampleKey(source.id, voice));
+    if (!sample) continue;
+    let level = assetGates.get(sample);
+    if (level === undefined) {
+      level = autoGateDb(Float64Array.from(sample.mono), sample.sampleRate);
+      assetGates.set(sample, level);
+    }
+    if (level > -120) gate = gate === undefined ? level : Math.min(gate, level);
+  }
+  return gate ?? -120;
+}
+
+/** Resolves a carrier's modulator, or undefined (the stage is bypassed). */
+function vocoderSourceOf(
+  track: Track,
+  groups: ReadonlyMap<string, readonly Note[]>,
+  performed: ReadonlyMap<string, readonly PerformedNote[]>,
+  context: RenderContext,
+  bank: SampleBank,
+): VocoderSource | undefined {
+  const ref = track.vocoder?.src;
+  if (ref === undefined) return undefined;
+  const source = resolveTrackRef(context.score, ref);
+  if (!source || source.id === track.id) return undefined;
+  const settings = resolveVocoder(track.vocoder);
+  const notes = groups.get(source.id) ?? [];
+  const engine = engineFor(source);
+  // Post-tap fields never change the tap (mute, solo and volume included).
+  const {
+    vocoder: _vocoder,
+    pan: _pan,
+    volume: _volume,
+    volumeAutomation: _volumeAutomation,
+    panAutomation: _panAutomation,
+    delay: _delay,
+    delayFeedbackAutomation: _delayFeedback,
+    delayMixAutomation: _delayMix,
+    reverb: _reverb,
+    ...kept
+  } = source;
+  // Only the stages the tap runs (before pan, and none for `tap: dry`):
+  // a source's reverb, delay, double or other post-pan fx never re-render
+  // its carriers. fxAutomation stays (rarely post-pan; a cheap re-render).
+  const tapped = settings.tap === "chain" ? FX_CHAIN.slice(0, TAP_END) : [];
+  const fx = kept.fx
+    ? Object.fromEntries(
+        Object.entries(kept.fx).filter(
+          ([stage]) =>
+            tapped.includes(stage as never) ||
+            !FX_CHAIN.includes(stage as never),
+        ),
+      )
+    : undefined;
+  const stripped = {
+    ...kept,
+    fx: fx && Object.keys(fx).length > 0 ? fx : undefined,
+  } as unknown as Track;
+  const gateDb =
+    settings.gate === "auto" ? sourceGateDb(source, bank) : settings.gate;
+  // The modulator's clips (0.7) are heard; guide tones never are.
+  const clipDigest = clipsDigest(source, bank, false);
+  // A tuned modulator (0.7 autotune) keys on its targets too: its guide
+  // track's notes, the chord timeline and the key change the tap.
+  const clipKeys = [
+    ...(clipDigest === undefined ? [] : [`clips:${clipDigest}`]),
+    ...(source.autotune ? autotuneStemDigests(source, context.score) : []),
+  ];
+  const key = stemKey(
+    stripped,
+    notes,
+    context,
+    isSamplerInstrument(source.instrument) ? bank : undefined,
+    wavetableHook(source, bank, context)?.id,
+    undefined,
+    engine
+      ? [
+          ...(engine.assetDigests?.(source, bank, context.score) ?? []),
+          `key:${context.score.key ?? ""}`,
+          ...clipKeys,
+        ]
+      : clipKeys.length > 0
+        ? clipKeys
+        : undefined,
+  );
+  return {
+    track: source,
+    played: performed.get(source.id) ?? [],
+    tap: settings.tap,
+    key: `vocsrc:${settings.tap}:${gateDb}:${key}`,
+    gateDb,
+  };
+}
+
+/** Renders a modulator's mono tap (see `StemRenderer.vocoderTap`). */
+function renderVocoderTap(
+  source: VocoderSource,
+  context: RenderContext,
+  bank: SampleBank,
+): Float64Array {
+  const { played } = source;
+  // The tap is rendered at unity gain: the voice bakes track volume in
+  // (trackGainAt), and volume is a post-tap field the cache key leaves out.
+  const track: Track = {
+    ...source.track,
+    volume: 1,
+    volumeAutomation: [],
+  };
+  const { score } = context;
+  const dry = new Float64Array(context.samples);
+  const dryR = new Float64Array(context.samples);
+  const tuning = resolveTuning(score.tuning, track.tuning, score.key);
+  const stereo = renderVoiceInto(
+    dry,
+    dryR,
+    played,
+    track,
+    context,
+    score,
+    bank,
+    engineFor(track),
+    isSamplerInstrument(track.instrument),
+    wavetableHook(track, bank, context),
+    tuning,
+    false,
+  );
+  if (source.tap === "chain") {
+    const chain = needsEffectNotes(track)
+      ? { ...context, notes: effectNotes(played, context, tuning) }
+      : context;
+    applyMonoChain(dry, track, chain);
+    if (stereo) applyMonoChain(dryR, track, chain);
+  }
+  if (stereo)
+    for (let i = 0; i < dry.length; i += 1) dry[i] = (dry[i]! + dryR[i]!) / 2;
+  return dry;
+}
+
+/**
+ * Renders a track's voice (engine, sampler, synth or tone/drum notes) into
+ * `dry` (and `dryR` when stereo) before any effect; returns whether it
+ * wrote a right channel. Shared by the stem pass and the vocoder tap.
+ */
+function renderVoiceInto(
+  dry: Float64Array,
+  dryR: Float64Array,
+  played: readonly PerformedNote[],
+  track: Track | undefined,
+  context: RenderContext,
+  score: TrackScore,
+  bank: SampleBank,
+  engine: InstrumentEngine | undefined,
+  sampler: boolean,
+  wavetable: ReturnType<typeof wavetableHook> | undefined,
+  tuning: TuningTable | undefined,
+  guide: boolean,
+): boolean {
+  const synthVoice = !engine && !sampler && usesSynthVoice(track);
+  let stereo = engine
+    ? engine.stereo(track!)
+    : synthVoice && isStereoVoice(track);
+  if (stereo) dryR.fill(0);
+  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 = {
+      ...context,
+      ticksPerBeat: score.ticksPerBeat,
+      ...(wavetable ? { oscillatorFor: wavetable.oscillatorFor } : {}),
+      ...(tuning ? { tuning } : {}),
+    };
+    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,
+        note,
+        track,
+        start,
+        length,
+        voice,
+        noteGainAt,
+      );
+    }
+  } else if (track?.clips && isGuideInstrument(track.instrument)) {
+    // A `vocal` track's notes guide its clips: silent in a render,
+    // a soft sine in the live loop with `guide` on. (Without clips,
+    // an older project's `vocal` keeps its tone.)
+    if (guide)
+      for (const note of played)
+        renderToneNote(
+          dry,
+          { ...note, velocity: note.velocity * GUIDE_LEVEL },
+          { ...track, instrument: "sine" },
+          context,
+          tuning,
+        );
+  } else {
+    const drums = isDrumInstrument(track?.instrument);
+    // Calibration 1+ (0.7): a closed or pedal hat chokes a ringing open hat.
+    const chokes =
+      drums && (context.score.calibration ?? 0) >= 1
+        ? hatChokes(played, context)
+        : undefined;
+    for (const note of played) {
+      if (drums) renderDrumNote(dry, note, track, context, chokes?.get(note));
+      else renderToneNote(dry, note, track, context, tuning);
+    }
+  }
+  // Audio clips (0.7) sum into the dry buffer before the chain.
+  if (track?.clips) {
+    const gainAt = (tick: number) => trackGainAt(track, tick);
+    renderClips(dry, track, context, bank, gainAt, score);
+    if (stereo) renderClips(dryR, track, context, bank, gainAt, score);
+  }
+  return stereo;
+}
+
+/**
+ * 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 +1429,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,
@@ -1013,6 +1487,7 @@ function renderToneNote(
   const performance = (note as PerformedNote).performance;
   const cents = performance?.cents;
   let bent = 0;
+  const wave = legacyWaveFor(instrument);
   for (let index = start; index < end; index += 1) {
     const elapsed = index - start;
     const remaining = end - index;
@@ -1039,7 +1514,7 @@ function renderToneNote(
     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;
+    target[index]! += wave(phase) * envelope * held;
   }
 }
 
@@ -1048,11 +1523,40 @@ function renderToneNote(
  * id and start tick, so a hit sounds identical on every render and in every
  * window regardless of note order.
  */
+/** Closed hat (42) and pedal hat (44) GM numbers that choke an open hat. */
+const CHOKING_HATS = new Set([42, 44]);
+/** Open hat fade once choked, in seconds. */
+const CHOKE_SECONDS = 0.008;
+
+/**
+ * For each open hat (46), the sample where the next closed or pedal hat
+ * on the same track starts, as on a real hi-hat stand.
+ */
+function hatChokes(
+  notes: readonly Note[],
+  context: RenderContext,
+): Map<Note, number> {
+  const closers = notes
+    .filter((note) => CHOKING_HATS.has(note.pitch))
+    .map((note) => noteSpan(note, context).start)
+    .sort((a, b) => a - b);
+  const chokes = new Map<Note, number>();
+  if (closers.length === 0) return chokes;
+  for (const note of notes) {
+    if (note.pitch !== 46) continue;
+    const start = noteSpan(note, context).start;
+    const next = closers.find((closer) => closer > start);
+    if (next !== undefined) chokes.set(note, next);
+  }
+  return chokes;
+}
+
 function renderDrumNote(
   target: Float64Array,
   note: Note,
   track: Track | undefined,
   context: RenderContext,
+  chokeAt?: number,
 ): void {
   const { sampleRate, samples, samplesPerTick } = context;
   const { start } = noteSpan(note, context);
@@ -1060,9 +1564,24 @@ function renderDrumNote(
   // one the voices below render exactly as they always have.
   const kit = synthKit(track?.kit);
   const kitState = kit ? newKitVoiceState() : undefined;
+  // Calibration 1+ (0.7): pitched toms, GM cymbals and cowbell as metal
+  // instead of a rim click, band-limited kit hats, and hat choke.
+  const calibrated = (context.score.calibration ?? 0) >= 1;
+  const metal = calibrated ? metalKindForPitch(note.pitch) : undefined;
+  const metalState = metal ? newKitVoiceState() : undefined;
+  const ratio = calibrated ? tomRatio(note.pitch) : 1;
+  const chokeEnd =
+    chokeAt === undefined
+      ? Number.POSITIVE_INFINITY
+      : chokeAt + Math.ceil(CHOKE_SECONDS * sampleRate);
   const end = Math.min(
     samples,
-    start + Math.ceil((kit?.seconds ?? MAX_DRUM_SECONDS) * sampleRate),
+    chokeEnd,
+    start +
+      Math.ceil(
+        (metal ? METAL_SECONDS : (kit?.seconds ?? MAX_DRUM_SECONDS)) *
+          sampleRate,
+      ),
   );
   const voice = drumVoiceForPitch(note.pitch);
   const random = seededRandom(
@@ -1079,7 +1598,10 @@ function renderDrumNote(
     const bright = noise - previousNoise;
     previousNoise = noise;
     let sample = 0;
-    if (kit && kitState)
+    if (metal && metalState) {
+      sample = metalSample(metal, t, bright, metalState, sampleRate);
+      if (kit) sample *= kit.gain;
+    } else if (kit && kitState)
       sample = kitDrumSample(
         kit,
         voice,
@@ -1088,6 +1610,7 @@ function renderDrumNote(
         bright,
         kitState,
         sampleRate,
+        calibrated ? { tomRatio: ratio } : undefined,
       );
     else if (voice === "kick") {
       const frequency = 45 + 105 * Math.exp(-t * 28);
@@ -1096,7 +1619,7 @@ function renderDrumNote(
         Math.sin(2 * Math.PI * phase) * Math.exp(-t * 7.5) +
         noise * 0.12 * Math.exp(-t * 300);
     } else if (voice === "tom") {
-      const frequency = 105 + 95 * Math.exp(-t * 18);
+      const frequency = (105 + 95 * Math.exp(-t * 18)) * ratio;
       phase += frequency / sampleRate;
       sample = Math.sin(2 * Math.PI * phase) * Math.exp(-t * 9);
     } else if (voice === "snare") {
@@ -1123,10 +1646,10 @@ function renderDrumNote(
       1,
       (index - start) / Math.max(1, sampleRate * 0.001),
     );
-    const release = Math.min(
-      1,
-      (end - index) / Math.max(1, sampleRate * 0.005),
-    );
+    const release =
+      chokeAt !== undefined && index >= chokeAt
+        ? Math.max(0, chokeEnd - index) / Math.max(1, chokeEnd - chokeAt)
+        : Math.min(1, (end - index) / Math.max(1, sampleRate * 0.005));
     target[index]! +=
       sample *
       attack *