@hraness/dawg 0.4.0 → 0.5.0

package/src/audio/effects/space.ts

@@ -5,8 +5,9 @@
 import type { Track } from "../../../core/score.ts";
 import type { DecodedSample } from "../samples.ts";
 import {
+  addConvolved,
   builtinImpulse,
-  convolveStereo,
+  convolveRaw,
   sampleImpulse,
   type Impulse,
 } from "./convolution.ts";
@@ -15,6 +16,7 @@ import {
   OnePole,
   Param,
   interpolateAutomation,
+  tickAtSample,
   type EffectContext,
 } from "./common.ts";
 
@@ -48,7 +50,12 @@ export function applyDelay(
   const feedbackLane = track.delayFeedbackAutomation ?? [];
   const mixLane = track.delayMixAutomation ?? [];
   if (delay.mix <= 0 && mixLane.length === 0) return;
-  const { sampleRate, samplesPerTick } = context;
+  const { sampleRate } = context;
+  const synced = !(delay.time !== undefined && delay.time > 0);
+  if (context.warp && synced) {
+    applyWarpedDelay(left, right, track, context, wetOnly);
+    return;
+  }
   const length = Math.max(
     1,
     Math.round(delaySeconds(track, context.tempoBpm) * sampleRate),
@@ -68,7 +75,7 @@ export function applyDelay(
         ];
   for (let index = 0; index < left.length; index += 1) {
     if (automated && index % CONTROL_SAMPLES === 0) {
-      const tick = index / samplesPerTick;
+      const tick = tickAtSample(context, index);
       feedback = interpolateAutomation(feedbackLane, tick, delay.feedback);
       mix = interpolateAutomation(mixLane, tick, delay.mix);
     }
@@ -97,6 +104,89 @@ export function applyDelay(
   }
 }
 
+/**
+ * The beat-synced delay under a tempo map: the read head trails the write
+ * head by `beats` of score time at every control block, read with linear
+ * interpolation, so each echo lands `beats` later on the grid through tempo
+ * steps, ramps and fermatas. Same routing and lanes as `applyDelay`.
+ */
+function applyWarpedDelay(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  context: EffectContext,
+  wetOnly: boolean,
+): void {
+  const delay = track.delay!;
+  const warp = context.warp!;
+  const { sampleRate } = context;
+  const feedbackLane = track.delayFeedbackAutomation ?? [];
+  const mixLane = track.delayMixAutomation ?? [];
+  // Ticks per beat, recovered from the context's start-tempo sample rate.
+  const ticksPerBeat = Math.round(
+    (sampleRate * 60) / (context.tempoBpm * context.samplesPerTick),
+  );
+  const lag = delay.beats * ticksPerBeat;
+  const lagAt = (index: number) =>
+    Math.max(2, index - warp.sample(warp.tick(index) - lag));
+  // Longest lag over the buffer sizes the lines.
+  let longest = 1;
+  for (let index = 0; index <= left.length; index += CONTROL_SAMPLES)
+    longest = Math.max(longest, lagAt(index));
+  const size = Math.ceil(longest) + 2;
+  const lineL = new Float64Array(size);
+  const lineR = new Float64Array(size);
+  const pingpong = delay.pingpong === true;
+  const highcut =
+    delay.highcut === undefined
+      ? undefined
+      : [
+          new OnePole(delay.highcut, sampleRate),
+          new OnePole(delay.highcut, sampleRate),
+        ];
+  let feedback = delay.feedback;
+  let mix = delay.mix;
+  let lagNow = lagAt(0);
+  let lagStep = 0;
+  for (let index = 0; index < left.length; index += 1) {
+    if (index % CONTROL_SAMPLES === 0) {
+      const tick = tickAtSample(context, index);
+      feedback = interpolateAutomation(feedbackLane, tick, delay.feedback);
+      mix = interpolateAutomation(mixLane, tick, delay.mix);
+      lagNow = lagAt(index);
+      lagStep = (lagAt(index + CONTROL_SAMPLES) - lagNow) / CONTROL_SAMPLES;
+    } else lagNow += lagStep;
+    const read = index - Math.min(size - 2, lagNow);
+    const base = Math.floor(read);
+    const fraction = read - base;
+    const at = (line: Float64Array, position: number) =>
+      position < 0 ? 0 : line[position % size]!;
+    const wetL =
+      at(lineL, base) * (1 - fraction) + at(lineL, base + 1) * fraction;
+    const wetR =
+      at(lineR, base) * (1 - fraction) + at(lineR, base + 1) * fraction;
+    const dryL = left[index]!;
+    const dryR = right[index]!;
+    let writeL: number;
+    let writeR: number;
+    if (pingpong) {
+      writeL = (dryL + dryR) * 0.5 + wetR * feedback;
+      writeR = wetL * feedback;
+    } else {
+      writeL = dryL + wetR * feedback;
+      writeR = dryR + wetL * feedback;
+    }
+    if (highcut) {
+      writeL = highcut[0]!.process(writeL);
+      writeR = highcut[1]!.process(writeR);
+    }
+    lineL[index % size] = writeL;
+    lineR[index % size] = writeR;
+    left[index] = (wetOnly ? 0 : dryL) + wetL * mix;
+    right[index] = (wetOnly ? 0 : dryR) + wetR * mix;
+  }
+}
+
 /** Seconds until the track's delay decays below -60 dB, bounded. */
 export function delayTailFor(track: Track, tempoBpm: number): number {
   if (!track.delay) return 0;
@@ -181,6 +271,10 @@ export function reverbTailFor(
  * feedback for an exact -60 dB decay time; `dim` sets the in-loop damping
  * frequency, `lowpass` filters the input and `predelay` delays it.
  * `wetOnly` (a shared orbit bus) replaces the input with the tail alone.
+ *
+ * It runs in two steps: `reverbWet` (the tail before its mix gain, which
+ * does not depend on `mix`) and `addReverbWet`. The stem cache keeps the
+ * first, so a mix-only edit skips the room entirely.
  */
 export function applyReverb(
   left: Float64Array,
@@ -189,28 +283,51 @@ export function applyReverb(
   context: EffectContext,
   wetOnly = false,
 ): void {
-  const reverb = track.reverb;
-  if (!reverb) return;
-  const mixParam = new Param(
-    reverb.mix,
+  const wet = reverbWet(left, right, track, context);
+  if (wet) addReverbWet(left, right, wet, track, context, wetOnly);
+}
+
+/** A reverb's tail before its mix gain (`scale` for an impulse response). */
+export type ReverbWet = Readonly<{
+  left: Float64Array;
+  right: Float64Array;
+  /** The convolution's inverse-FFT scale; absent for the algorithmic room. */
+  scale?: number;
+}>;
+
+function mixParamOf(track: Track, context: EffectContext): Param {
+  return new Param(
+    track.reverb?.mix ?? 0,
     track.fxAutomation?.["reverb-mix"],
     context.samplesPerTick,
+    context.warp,
+  );
+}
+
+/** Whether the track's reverb sounds at all (a mix above 0, or a lane). */
+export function reverbActive(track: Track): boolean {
+  const reverb = track.reverb;
+  if (!reverb) return false;
+  return (
+    reverb.mix > 0 || (track.fxAutomation?.["reverb-mix"] ?? []).length > 0
   );
-  if (reverb.mix <= 0 && !mixParam.automated) return;
+}
+
+/**
+ * The reverb tail of the pair, before the mix gain; `left`/`right` are
+ * read, not changed. Undefined when the reverb is off.
+ */
+export function reverbWet(
+  left: Float64Array,
+  right: Float64Array,
+  track: Track,
+  context: EffectContext,
+): ReverbWet | undefined {
+  const reverb = track.reverb;
+  if (!reverb || !reverbActive(track)) return undefined;
   const { sampleRate } = context;
   const impulse = reverbImpulse(track, sampleRate, context.irs);
-  if (impulse) {
-    applyConvolutionReverb(
-      left,
-      right,
-      track,
-      context,
-      impulse,
-      mixParam,
-      wetOnly,
-    );
-    return;
-  }
+  if (impulse) return convolutionWet(left, right, track, context, impulse);
   const scale = sampleRate / 44_100;
   const sizeFeedback = 0.7 + 0.28 * reverb.size;
   const damp =
@@ -219,7 +336,6 @@ export function applyReverb(
       : Math.exp(
           (-2 * Math.PI * Math.min(reverb.dim, sampleRate * 0.45)) / sampleRate,
         );
-  let wet = reverb.mix * REVERB_WET_SCALE;
   const channel = (spread: number) => ({
     combs: COMB_TUNING.map((tuning) => {
       const length = Math.max(1, Math.round((tuning + spread) * scale));
@@ -266,9 +382,9 @@ export function applyReverb(
   const predelaySamples = Math.round((reverb.predelay ?? 0) * sampleRate);
   const predelay =
     predelaySamples > 0 ? new Float64Array(predelaySamples) : undefined;
+  const wetL = new Float64Array(left.length);
+  const wetR = new Float64Array(left.length);
   for (let index = 0; index < left.length; index += 1) {
-    if (mixParam.automated && index % CONTROL_SAMPLES === 0)
-      wet = mixParam.at(index) * REVERB_WET_SCALE;
     let input = (left[index]! + right[index]!) * REVERB_INPUT_GAIN;
     if (inputFilter) input = inputFilter.process(input);
     if (predelay) {
@@ -277,12 +393,60 @@ export function applyReverb(
       predelay[slot] = input;
       input = delayed;
     }
+    wetL[index] = process(sides[0], input);
+    wetR[index] = process(sides[1], input);
+  }
+  return { left: wetL, right: wetR };
+}
+
+/**
+ * Add (or with `wetOnly`, write) a tail from `reverbWet` at the track's
+ * mix and mix lane, in the order the one-pass reverb always used, so a
+ * cached tail mixes to the same samples.
+ */
+export function addReverbWet(
+  left: Float64Array,
+  right: Float64Array,
+  tail: ReverbWet,
+  track: Track,
+  context: EffectContext,
+  wetOnly = false,
+): void {
+  const mixParam = mixParamOf(track, context);
+  if (tail.scale !== undefined) {
+    if (wetOnly) {
+      left.fill(0);
+      right.fill(0);
+    }
+    if (tail.scale === 0) return;
+    let wet = mixParam.fallback * IR_WET_SCALE;
+    addConvolved(
+      tail.left,
+      tail.right,
+      tail.scale,
+      left,
+      right,
+      wet,
+      mixParam.automated
+        ? (index) => {
+            if (index % CONTROL_SAMPLES === 0)
+              wet = mixParam.at(index) * IR_WET_SCALE;
+            return wet;
+          }
+        : undefined,
+    );
+    return;
+  }
+  let wet = mixParam.fallback * REVERB_WET_SCALE;
+  for (let index = 0; index < left.length; index += 1) {
+    if (mixParam.automated && index % CONTROL_SAMPLES === 0)
+      wet = mixParam.at(index) * REVERB_WET_SCALE;
     if (wetOnly) {
-      left[index] = process(sides[0], input) * wet;
-      right[index] = process(sides[1], input) * wet;
+      left[index] = tail.left[index]! * wet;
+      right[index] = tail.right[index]! * wet;
     } else {
-      left[index]! += process(sides[0], input) * wet;
-      right[index]! += process(sides[1], input) * wet;
+      left[index]! += tail.left[index]! * wet;
+      right[index]! += tail.right[index]! * wet;
     }
   }
 }
@@ -293,15 +457,13 @@ export function applyReverb(
  * `size`, `fade` and `dim` describe the algorithmic tail and do nothing
  * here: the impulse is the room.
  */
-function applyConvolutionReverb(
+function convolutionWet(
   left: Float64Array,
   right: Float64Array,
   track: Track,
   context: EffectContext,
   impulse: Impulse,
-  mixParam: Param,
-  wetOnly: boolean,
-): void {
+): ReverbWet {
   const reverb = track.reverb!;
   const { sampleRate } = context;
   const input = new Float64Array(left.length);
@@ -315,23 +477,8 @@ function applyConvolutionReverb(
     if (inputFilter) value = inputFilter.process(value);
     input[index + offset] = value;
   }
-  if (wetOnly) {
-    left.fill(0);
-    right.fill(0);
-  }
-  let wet = reverb.mix * IR_WET_SCALE;
-  convolveStereo(
-    input,
-    impulse,
-    left,
-    right,
-    wet,
-    mixParam.automated
-      ? (index) => {
-          if (index % CONTROL_SAMPLES === 0)
-            wet = mixParam.at(index) * IR_WET_SCALE;
-          return wet;
-        }
-      : undefined,
-  );
+  const wetL = new Float64Array(left.length);
+  const wetR = new Float64Array(left.length);
+  const scale = convolveRaw(input, impulse, wetL, wetR);
+  return { left: wetL, right: wetR, scale };
 }

package/src/audio/engine.ts

@@ -2,10 +2,19 @@ import type { TrackScore } from "../../core/score.ts";
 import { PlaybackLock } from "./lock.ts";
 import { LoopPlayer } from "./player.ts";
 import { LoopRenderer, type LoopRender } from "./renderer.ts";
-import { clickSounds, clicksIn, type ClickLevel } from "./click.ts";
+import {
+  clickSounds,
+  clicksIn,
+  type ClickGrid,
+  type ClickLevel,
+} from "./click.ts";
 import type { LiveNotePcm } from "./live.ts";
+import { measureLoudness, pcmChannels } from "./loudness.ts";
+import type { MasterReport } from "./master.ts";
 import { levelOf, type SoundLevel } from "./preview.ts";
 import { DEFAULT_SAMPLE_RATE, RENDER_CHANNELS } from "./wav.ts";
+import { playbackTime } from "./arrange.ts";
+import { transportMapFor, type TransportMap } from "./clock.ts";
 
 /**
  * How dawgd (or a file-mode window) makes sound.
@@ -170,6 +179,17 @@ function parseCommand(value: string): string[] {
   return parts;
 }
 
+/**
+ * Swaps crossfade old to new over this window with equal-power gains
+ * (cos/sin), reading both loops at the same beat. 20 ms is long enough that
+ * the step a hard cut makes is spread below ~50 Hz (no click, even on a
+ * full-scale low bass), short enough to sit inside the transport's 30 ms
+ * resync tolerance and below the shortest audible echo (~30-50 ms), so an
+ * edit never sounds smeared or doubled. Playback only: renders, exports and
+ * the loop buffers themselves never pass through it.
+ */
+export const SWAP_FADE_SECONDS = 0.02;
+
 /** Swaps re-anchor to the transport only past this disagreement. */
 const RESYNC_SECONDS = 0.03;
 
@@ -226,8 +246,45 @@ type Loop = Readonly<{
   pcm: Int16Array;
   frames: number;
   framesPerBeat: number;
+  /** The song's tempo map; absent, a beat is `framesPerBeat` frames. */
+  map?: TransportMap;
+  sampleRate: number;
 }>;
 
+/** Loop frame (unwrapped without a map) where transport `beat` sounds. */
+function frameOfBeat(loop: Loop, beat: number): number {
+  const map = loop.map;
+  if (!map) return beat * loop.framesPerBeat;
+  const inner = ((beat % map.loopBeats) + map.loopBeats) % map.loopBeats;
+  return map.seconds(inner) * loop.sampleRate;
+}
+
+/** Transport beat at loop `frame` (inside one pass with a map). */
+function beatOfFrame(loop: Loop, frame: number): number {
+  const map = loop.map;
+  if (!map) return frame / loop.framesPerBeat;
+  const seconds = frame / loop.sampleRate;
+  const inner =
+    ((seconds % map.loopSeconds) + map.loopSeconds) % map.loopSeconds;
+  return map.beat(inner);
+}
+
+/** The beat `frames` stream frames after `beat`. */
+function beatAfter(loop: Loop, beat: number, frames: number): number {
+  if (!loop.map) return beat + frames / loop.framesPerBeat;
+  return beatOfFrame(loop, frameOfBeat(loop, beat) + frames);
+}
+
+/** A loop fading out after a swap, read on from where it was. */
+type FadeOut = {
+  loop: Loop;
+  cursor: number;
+  /** Its gain when the fade began (below 1 when swapped out mid-fade). */
+  from: number;
+  /** Frames of the fade already written. */
+  done: number;
+};
+
 /**
  * The click bus: the engine asks `beatAt` for the transport beat at a stream
  * frame's wall time (undefined while the transport is stopped; negative
@@ -238,6 +295,8 @@ export type ClickBus = Readonly<{
   volume: number;
   beatsPerBar: number;
   subdivision: number;
+  /** Meter-aware clicks (core/tempo.ts) replacing the fixed grid. */
+  grid?: ClickGrid;
   beatAt: (monotonicMs: number) => number | undefined;
 }>;
 
@@ -293,6 +352,11 @@ export class AudioEngine {
   private child: PlayerProcess | undefined;
   private timer: ReturnType<typeof setInterval> | undefined;
   private loop: Loop | undefined;
+  /** Loops fading out after swaps (see `SWAP_FADE_SECONDS`). */
+  private fades: FadeOut[] = [];
+  /** Frames of the current loop's fade-in already written, while fading. */
+  private fadeIn: number | undefined;
+  private readonly fadeFrames: number;
   /** Monotonic ms that stream frame 0 belongs to. */
   private startMs = 0;
   /** Stream frames written since `startMs`. */
@@ -308,6 +372,9 @@ export class AudioEngine {
   /** The loop last swapped in, for `level` (measured on demand, once). */
   private lastLoopPcm: Int16Array | undefined;
   private measured: { pcm: Int16Array; level: SoundLevel } | undefined;
+  private loudnessOf: { pcm: Int16Array; report: MasterReport } | undefined;
+  /** Loudness the song master reached on the loop now playing. */
+  private lastMaster: MasterReport | undefined;
   private respawns = 0;
   private respawnTimer: ReturnType<typeof setTimeout> | undefined;
   /** Play mode: keep a player running without a loop for live voices. */
@@ -328,6 +395,10 @@ export class AudioEngine {
       ((options.leadMs ?? 200) * this.sampleRate) / 1000,
     );
     this.defaultLeadFrames = this.leadFrames;
+    this.fadeFrames = Math.max(
+      1,
+      Math.round(SWAP_FADE_SECONDS * this.sampleRate),
+    );
     this.tickMs = options.tickMs ?? 20;
     this.now = options.now ?? (() => performance.now());
     this.useTimer = options.timer ?? true;
@@ -391,6 +462,33 @@ export class AudioEngine {
     return this.measured.level;
   }
 
+  /**
+   * Integrated loudness and true peak of the loop now playing, after the
+   * song master when there is one (the header meter). Without a master the
+   * loop's PCM is measured once per render, on first read. Undefined before
+   * any render.
+   */
+  public get loudness(): MasterReport | undefined {
+    const pcm = this.lastLoopPcm;
+    if (!pcm) return undefined;
+    if (this.lastMaster) return this.lastMaster;
+    if (this.loudnessOf?.pcm !== pcm) {
+      const [left, right] = pcmChannels(pcm);
+      const measured = measureLoudness(left, right, this.sampleRate, {
+        loop: true,
+      });
+      this.loudnessOf = {
+        pcm,
+        report: {
+          gainDb: 0,
+          integrated: measured.integrated,
+          truePeak: measured.truePeak,
+        },
+      };
+    }
+    return this.loudnessOf.report;
+  }
+
   public get canMonitor(): boolean {
     return this.info.backend !== "none" && !this.fallback;
   }
@@ -522,6 +620,7 @@ export class AudioEngine {
           if (request.generation === this.generation) {
             await this.apply(this.toLoop(render, request.score), request);
             this.lastLoopPcm = render.pcm;
+            this.lastMaster = render.master;
           }
           for (const waiter of request.waiters) waiter.resolve();
         } catch (error) {
@@ -541,10 +640,11 @@ export class AudioEngine {
     const beat =
       request.beat === undefined
         ? undefined
-        : request.beat +
-          ((this.now() - request.atMs) * this.sampleRate) /
-            1000 /
-            loop.framesPerBeat;
+        : beatAfter(
+            loop,
+            request.beat,
+            ((this.now() - request.atMs) * this.sampleRate) / 1000,
+          );
     if (this.child) {
       this.swap(loop, beat);
       return;
@@ -565,19 +665,10 @@ export class AudioEngine {
     if (!this.loop || !this.child) return;
     this.cursor = this.frameForBeat(
       this.loop,
-      beat + this.queuedBeats(this.loop),
+      beatAfter(this.loop, beat, this.queuedFrames()),
     );
   }
 
-  /**
-   * Beats already queued ahead of the wall clock. The next frame written
-   * sounds this far after now, so a transport beat maps to the write head
-   * by adding it.
-   */
-  private queuedBeats(loop: Loop): number {
-    return this.queuedFrames() / loop.framesPerBeat;
-  }
-
   private queuedFrames(): number {
     const elapsed = Math.floor(
       ((this.now() - this.startMs) * this.sampleRate) / 1000,
@@ -592,6 +683,7 @@ export class AudioEngine {
   public async stopAsync(): Promise<void> {
     this.generation += 1;
     this.lastLoopPcm = undefined;
+    this.lastMaster = undefined;
     this.respawns = 0;
     if (this.respawnTimer) clearTimeout(this.respawnTimer);
     this.respawnTimer = undefined;
@@ -603,6 +695,7 @@ export class AudioEngine {
     if (this.monitoring && this.child) {
       // Play mode: the transport stopped, the live player keeps running.
       this.loop = undefined;
+      this.endFades();
       return;
     }
     if (this.timer) clearInterval(this.timer);
@@ -610,6 +703,7 @@ export class AudioEngine {
     const child = this.child;
     this.child = undefined;
     this.loop = undefined;
+    this.endFades();
     if (child) {
       try {
         child.stdin.end?.();
@@ -646,6 +740,7 @@ export class AudioEngine {
     if (remaining > this.sampleRate) {
       const skipped = remaining - this.sampleRate;
       if (loop) this.cursor = (this.cursor + skipped) % loop.frames;
+      this.endFades();
       this.written += skipped;
       remaining = this.sampleRate;
     }
@@ -663,6 +758,7 @@ export class AudioEngine {
       offset += take;
       this.cursor = (this.cursor + take) % loop.frames;
     }
+    if (loop) this.crossfade(out, remaining);
     this.mixLive(out, this.written, remaining);
     this.written += remaining;
     try {
@@ -673,6 +769,49 @@ export class AudioEngine {
     }
   }
 
+  /** Equal-power gain of a fade-in `done` frames along (0 to 1). */
+  private rampGain(done: number): number {
+    return Math.sin((Math.PI / 2) * Math.min(1, done / this.fadeFrames));
+  }
+
+  /**
+   * Blend the start of a block (already the current loop) with the loops
+   * fading out: new·sin + old·cos over `fadeFrames`, both read at the same
+   * beat, so a swap never steps the waveform.
+   */
+  private crossfade(out: Int16Array, frames: number): void {
+    if (this.fadeIn === undefined) return;
+    const start = this.fadeIn;
+    const count = Math.min(frames, this.fadeFrames - start);
+    for (let index = 0; index < count; index += 1) {
+      const gain = this.rampGain(start + index);
+      const at = index * RENDER_CHANNELS;
+      let left = out[at]! * gain;
+      let right = out[at + 1]! * gain;
+      for (const fade of this.fades) {
+        if (fade.done >= this.fadeFrames) continue;
+        const g =
+          fade.from * Math.cos((Math.PI / 2) * (fade.done / this.fadeFrames));
+        const from = fade.cursor * RENDER_CHANNELS;
+        left += fade.loop.pcm[from]! * g;
+        right += fade.loop.pcm[from + 1]! * g;
+        fade.cursor = (fade.cursor + 1) % fade.loop.frames;
+        fade.done += 1;
+      }
+      out[at] = clamp16(left);
+      out[at + 1] = clamp16(right);
+    }
+    this.fadeIn = start + count;
+    // Older fades that began earlier finish before the newest fade-in does.
+    this.fades = this.fades.filter((fade) => fade.done < this.fadeFrames);
+    if (this.fadeIn >= this.fadeFrames) this.endFades();
+  }
+
+  private endFades(): void {
+    this.fades = [];
+    this.fadeIn = undefined;
+  }
+
   /** Wall time (monotonic ms) stream frame `frame` sounds at. */
   private frameMs(frame: number): number {
     return this.startMs + (frame * 1000) / this.sampleRate;
@@ -736,15 +875,19 @@ export class AudioEngine {
   }
 
   private toLoop(render: LoopRender, score: TrackScore): Loop {
+    const timeline = playbackTime(score);
+    const map = transportMapFor(timeline);
     return {
       pcm: render.pcm,
       frames: render.frames,
-      framesPerBeat: (60 * this.sampleRate) / score.tempoBpm,
+      framesPerBeat: (60 * this.sampleRate) / timeline.tempoBpm,
+      sampleRate: this.sampleRate,
+      ...(map ? { map } : {}),
     };
   }
 
   private frameForBeat(loop: Loop, beat: number): number {
-    const frame = Math.round(Math.max(0, beat) * loop.framesPerBeat);
+    const frame = Math.round(frameOfBeat(loop, Math.max(0, beat)));
     return ((frame % loop.frames) + loop.frames) % loop.frames;
   }
 
@@ -752,17 +895,28 @@ export class AudioEngine {
     const previous = this.loop;
     // Keep the musical position: the same beat inside the new loop.
     let cursor = previous
-      ? this.frameForBeat(next, this.cursor / previous.framesPerBeat)
+      ? this.frameForBeat(next, beatOfFrame(previous, this.cursor))
       : 0;
     if (beat !== undefined) {
       // Re-anchor to the transport only when it disagrees audibly (a seek
       // or a tempo change); sub-frame rounding must not click on edits.
-      const anchored = this.frameForBeat(next, beat + this.queuedBeats(next));
+      // The next frame written sounds `queuedFrames` after now.
+      const anchored = this.frameForBeat(
+        next,
+        beatAfter(next, beat, this.queuedFrames()),
+      );
       const distance = Math.abs(anchored - cursor);
       const wrapped = Math.min(distance, next.frames - distance);
       if (!previous || wrapped > this.sampleRate * RESYNC_SECONDS)
         cursor = anchored;
     }
+    if (previous && this.child) {
+      // The outgoing loop keeps its current gain (below 1 when it was
+      // itself still fading in) and fades from there.
+      const from = this.fadeIn === undefined ? 1 : this.rampGain(this.fadeIn);
+      this.fades.push({ loop: previous, cursor: this.cursor, from, done: 0 });
+      this.fadeIn = 0;
+    }
     this.cursor = cursor;
     this.loop = next;
   }
@@ -784,6 +938,7 @@ export class AudioEngine {
     this.spawns += 1;
     this.child = child;
     this.loop = loop;
+    this.endFades();
     this.startMs = this.now();
     this.written = 0;
     this.cursor = loop ? this.frameForBeat(loop, beat) : 0;
@@ -835,7 +990,7 @@ export class AudioEngine {
         if (generation !== this.generation || this.child || this.starting)
           return;
         const frame = heard + ((this.now() - diedAt) * this.sampleRate) / 1000;
-        const beat = loop ? frame / loop.framesPerBeat : 0;
+        const beat = loop ? beatOfFrame(loop, frame) : 0;
         this.starting = this.start(loop, beat).finally(() => {
           this.starting = undefined;
         });