@driftengine/audio 3.61.0

package/src/rhythm/kickCore.ts

@@ -0,0 +1,197 @@
+/**
+ * What a kick is, in one place.
+ *
+ * Two analysers decide it: `beatMap.ts` offline, where an edit is cut, and `kickDetector.ts`
+ * live, where a light flashes. Their headers have always claimed the same bands, the same
+ * whitening and the same gates, because a replay whose cuts disagree with the lights in its own
+ * footage is the most confusing possible bug. They were two copies of that claim, and two copies
+ * drift: by the time this module was written they disagreed in two ways that a reader comparing
+ * the constants would not have seen.
+ *
+ *  - **Whitening.** Offline it was `kickBand - mask`; live it was `rms * 0.6 + kickBand * 0.6 -
+ *    mask`, a different quantity with a term the offline path has no equivalent for.
+ *  - **Time.** Every envelope was a fixed per-*step* lerp, and the two step at different rates:
+ *    a 5 ms hop offline, one call per rendered frame live. The same constant `0.1` is therefore
+ *    a 47 ms time constant in one and a 158 ms time constant in the other, and live it also
+ *    changed with the consumer's frame rate, so the same track detected differently on a 60 Hz
+ *    screen and a 144 Hz one.
+ *
+ * So the shared part lives here and both call it. The envelopes take a `dtSec` and smooth in
+ * *time* rather than per step, which is what makes one set of constants mean one thing at any
+ * rate. The rates are derived from the offline hop the constants were tuned at, so the offline
+ * analyser is unchanged to the last bit and the live one moves onto its terms.
+ *
+ * What stays outside: how the bands are measured (an FFT hop offline, an `AnalyserNode` live),
+ * peak picking and tempo, which need to look forward, and the pulse envelope, which is a
+ * lighting concern rather than a detection one.
+ */
+
+/** The seven band levels a kick is decided from, each 0 to 1. */
+export interface KickBands {
+  readonly sub: number;
+  readonly punch: number;
+  readonly sweet: number;
+  readonly bassline: number;
+  readonly mud: number;
+  readonly lowMid: number;
+  readonly high: number;
+}
+
+/**
+ * The step the constants below were tuned at: `beatMap.ts`'s own analysis hop.
+ *
+ * Every rate is derived from this, so a smoothing factor written as "per hop" keeps meaning
+ * exactly what it meant when it was chosen, and a caller stepping at any other interval gets the
+ * same curve in time rather than a different one.
+ */
+const REFERENCE_STEP_SEC = 0.005;
+
+/** A per-step factor at the reference hop, as a rate per second. */
+function ratePerSecond(perStep: number): number {
+  return -Math.log(1 - perStep) / REFERENCE_STEP_SEC;
+}
+
+/** Envelope smoothing, named for what it follows. Written per hop, applied in time. */
+const ONSET_FAST_RATE = ratePerSecond(0.62);
+const ONSET_SLOW_RATE = ratePerSecond(0.1);
+const FLOOR_MEAN_RATE = ratePerSecond(0.012);
+const FLOOR_DEV_RATE = ratePerSecond(0.04);
+const TRANSIENT_MEAN_RATE = ratePerSecond(0.016);
+const TRANSIENT_DEV_RATE = ratePerSecond(0.05);
+
+/** How much of the low end a sustained bassline is allowed to explain away. */
+const MASK_BASSLINE = 0.68;
+const MASK_MUD = 0.22;
+const MASK_LOW_MID = 0.08;
+const MASK_SCALE = 0.55;
+
+/** Floors, as a minimum and as a multiple of the signal's own deviation. */
+const ENERGY_FLOOR_MIN = 0.0028;
+const ENERGY_FLOOR_DEV = 1.05;
+const ONSET_FLOOR_MIN = 0.0009;
+const ONSET_FLOOR_DEV = 1.35;
+
+/** Shape gates. Each rejects something loud that is not a kick. */
+const PUNCH_OVER_BASSLINE = 0.55;
+const SUB_OVER_MUD = 0.24;
+const LOW_SHARE_MIN = 0.18;
+const BASS_DOMINANCE_MIN = 0.55;
+
+/** Ignore a rise this soon after the last one — one hit is one pulse. */
+export const MIN_INTERVAL_MS = 74;
+
+/** Where a kick's fundamental may sit. Outside this it is not a kick drum. */
+export const PEAK_MIN_HZ = 45;
+export const PEAK_MAX_HZ = 95;
+
+/**
+ * How much of an envelope's remaining distance to cover in `dtSec`.
+ *
+ * Zero for a step that did not advance and one for a step long enough that whatever was held is
+ * stale, which is the right answer to a backgrounded tab: snap to what is true now rather than
+ * ease from a value that describes a minute ago.
+ */
+function approach(rate: number, dtSec: number): number {
+  if (!(dtSec > 0)) return 0;
+  return 1 - Math.exp(-rate * dtSec);
+}
+
+/**
+ * The running state both analysers keep, advanced one step at a time.
+ *
+ * Allocation-free after construction: `step` writes fields and returns nothing, because the live
+ * path calls it every frame.
+ */
+export class KickCore {
+  private onsetFast = 0;
+  private onsetSlow = 0;
+  private lowBandMean = 0;
+  private lowBandDev = 0;
+  private transientMean = 0;
+  private transientDev = 0;
+  private prevSub = 0;
+  private prevPunch = 0;
+
+  /** The kick band with the bassline's contribution taken out of it. */
+  whitened = 0;
+  /** How much of that arrived just now rather than being present. */
+  onset = 0;
+  /** Energy that *arrived* in the kick bands, rather than energy that is there. */
+  flux = 0;
+  /** The adaptive thresholds `onset` and `whitened` have to clear. */
+  onsetFloor = 0;
+  energyFloor = 0;
+  /** Whether the spectral shape is kick-like at all, before any threshold. */
+  shaped = false;
+
+  /**
+   * One step. `dtSec` is how long it covers, which is the hop offline and the frame time live.
+   *
+   * `peakHz` is the tracked fundamental where a caller has one; the offline path has no
+   * band-pass to track and passes the centre of the allowed range, which is the same as saying
+   * it does not use this gate.
+   */
+  step(bands: KickBands, dtSec: number, peakHz: number = (PEAK_MIN_HZ + PEAK_MAX_HZ) / 2): void {
+    const { sub, punch, sweet, bassline, mud, lowMid, high } = bands;
+
+    /*
+     * Whitening: the kick band minus what a sustained bassline contributes to it. This is the
+     * step that turns "the low end is loud" — true for the whole track — into "something just
+     * hit", true for a few steps.
+     */
+    const kickBand = sub * 0.35 + punch * 0.45 + sweet * 0.2;
+    const mask = bassline * MASK_BASSLINE + mud * MASK_MUD + lowMid * MASK_LOW_MID;
+    this.whitened = Math.max(0, kickBand - mask * MASK_SCALE);
+
+    this.onsetFast += (this.whitened - this.onsetFast) * approach(ONSET_FAST_RATE, dtSec);
+    this.onsetSlow += (this.whitened - this.onsetSlow) * approach(ONSET_SLOW_RATE, dtSec);
+    this.onset = Math.max(0, this.onsetFast - this.onsetSlow);
+
+    /*
+     * A decaying kick has plenty of energy present and none arriving, which is what keeps one
+     * hit one beat.
+     */
+    this.flux = Math.max(0, sub - this.prevSub) * 0.58 + Math.max(0, punch - this.prevPunch) * 0.42;
+    this.prevSub = sub;
+    this.prevPunch = punch;
+
+    /*
+     * Adaptive floors, so the same analyser works on tracks mastered ten decibels apart — which
+     * matters the moment somebody imports their own.
+     */
+    this.lowBandMean += (this.whitened - this.lowBandMean) * approach(FLOOR_MEAN_RATE, dtSec);
+    this.lowBandDev +=
+      (Math.abs(this.whitened - this.lowBandMean) - this.lowBandDev) *
+      approach(FLOOR_DEV_RATE, dtSec);
+
+    const transientSignal = this.onset + this.flux * 0.18;
+    this.transientMean +=
+      (transientSignal - this.transientMean) * approach(TRANSIENT_MEAN_RATE, dtSec);
+    this.transientDev +=
+      (Math.abs(transientSignal - this.transientMean) - this.transientDev) *
+      approach(TRANSIENT_DEV_RATE, dtSec);
+
+    this.energyFloor =
+      this.lowBandMean + Math.max(ENERGY_FLOOR_MIN, this.lowBandDev * ENERGY_FLOOR_DEV);
+    this.onsetFloor =
+      this.transientMean + Math.max(ONSET_FLOOR_MIN, this.transientDev * ONSET_FLOOR_DEV);
+
+    const lowSum = sub + punch;
+    const lowShare = lowSum / Math.max(1e-6, lowSum + bassline + mud + lowMid + high);
+    const percussiveBody = lowMid * 0.72 + high * 0.58;
+    const bassDominance = (sub * 0.62 + punch * 0.38) / Math.max(1e-6, percussiveBody + mud * 0.45);
+
+    this.shaped =
+      punch > bassline * PUNCH_OVER_BASSLINE &&
+      sub > mud * SUB_OVER_MUD &&
+      lowShare > LOW_SHARE_MIN &&
+      bassDominance > BASS_DOMINANCE_MIN &&
+      peakHz >= PEAK_MIN_HZ &&
+      peakHz <= PEAK_MAX_HZ;
+  }
+
+  /** Whether this step is a hit, ignoring how recently the last one was. */
+  get rising(): boolean {
+    return this.shaped && this.onset > this.onsetFloor && this.whitened > this.energyFloor;
+  }
+}

package/src/rhythm/kickDetector.ts

@@ -0,0 +1,233 @@
+import { RHYTHM_BANDS } from './bands.ts';
+import { KickCore, MIN_INTERVAL_MS, PEAK_MAX_HZ, PEAK_MIN_HZ } from './kickCore.ts';
+
+/**
+ * Live kick detection, for things that react in the moment.
+ *
+ * The offline analyser in `beatMap.ts` is the one an edit is cut against,
+ * because it can look ahead. This is its counterpart for the running game,
+ * where being a few tens of milliseconds behind the transient is imperceptible
+ * and re-analysing a whole track every frame would be absurd.
+ *
+ * Same bands, same whitening, same gates — so "a kick" means one thing in both
+ * places. A replay whose cuts disagreed with the lights in its own footage
+ * would be the most confusing possible bug.
+ *
+ * That is now shared code rather than a claim: `kickCore.ts` holds the decision and both files
+ * call it. It was a claim until 2026-08-17, and the two had drifted apart in two ways while the
+ * constants still looked identical — see that module's header for what they were.
+ *
+ * Ported from a production music-analysis detector. Every buffer is allocated once;
+ * `update` runs per frame and must not allocate.
+ */
+
+/** How fast a pulse falls back to rest, per second. */
+const PULSE_DECAY = 11;
+
+/** Envelope of a pulse of `peak` strength, `seconds` after it fired. */
+export function kickPulseAfter(peak: number, seconds: number): number {
+  if (!Number.isFinite(seconds) || seconds <= 0) return peak;
+  const value = peak * Math.exp(-PULSE_DECAY * seconds);
+  return value < 1e-3 ? 0 : value;
+}
+
+export interface KickDetectorNodes {
+  /** Full-spectrum analyser on the playing source. */
+  readonly wide: AnalyserNode;
+  /** Analyser at the end of a low-pass → tracking band-pass chain. */
+  readonly kick: AnalyserNode;
+  /** The tracking band-pass, whose centre follows the detected fundamental. */
+  readonly bandpass: BiquadFilterNode;
+  readonly context: BaseAudioContext;
+}
+
+const PEAK_FOLLOW = 0.25;
+const PEAK_FOLLOW_TIME = 0.02;
+
+/**
+ * A decibel magnitude as linear amplitude.
+ *
+ * `getFloatFrequencyData` reports silence as `-Infinity`, which is 0 rather than a very small
+ * number, and every real bin is a negative decibel value.
+ */
+function decibelsToAmplitude(db: number): number {
+  return Number.isFinite(db) ? Math.pow(10, db / 20) : 0;
+}
+
+export class KickDetector {
+  /*
+   * **Decibels, not the byte view, and this is a correctness matter rather than a precision
+   * one.** `getByteFrequencyData` maps the spectrum from `minDecibels` to `maxDecibels` onto 0
+   * to 255, which defaults to a window of -100 to -30 dB. Two things follow, and both were live
+   * for as long as this detector has existed. Everything above -30 dBFS pins at 255, which on a
+   * loud master is most of the low end for most of the track, so the bands this decided from
+   * were clipped flat and `energy` measured 1.000 in every frame of a real track. And what came
+   * back was a decibel scale where the shared arithmetic is tuned for linear amplitude: on a dB
+   * scale a near-silent bin reads about 0.28 rather than about 0.0001, so the masking, the
+   * floors and every ratio gate were comparing quantities they were never meant for. Gates like
+   * `punch > bassline * 0.55` are nearly always true once both sides are compressed into the
+   * same narrow band, which is a detector with its safeguards switched off.
+   *
+   * `getFloatFrequencyData` is the same data in dB with no window and no clipping, and
+   * `band()` converts it back to linear amplitude, which is what `beatMap.ts` measures and what
+   * `kickCore.ts` is tuned against.
+   *
+   * Explicitly backed by an ArrayBuffer: the analyser methods refuse a view that might be over
+   * shared memory, which is what a bare typed array widens to.
+   */
+  private readonly wideFreq: Float32Array<ArrayBuffer>;
+  private readonly kickFreq: Float32Array<ArrayBuffer>;
+  private readonly ranges: Record<string, readonly [number, number]>;
+  private readonly kickBand: readonly [number, number];
+
+  private peakHz = 62;
+  /** The shared decision, stepped once per frame. See `kickCore.ts`. */
+  private readonly core = new KickCore();
+  private lastHitMs = Number.NEGATIVE_INFINITY;
+  private lastUpdateMs = 0;
+  /** Reused so `core.step` is handed one object rather than a fresh literal every frame. */
+  private readonly bands = { sub: 0, punch: 0, sweet: 0, bassline: 0, mud: 0, lowMid: 0, high: 0 };
+
+  /** 0–1, spiking on a kick and decaying back. What a light should follow. */
+  pulse = 0;
+  /** Smoothed low-end presence, for anything that wants level rather than hits. */
+  energy = 0;
+  /**
+   * 0–1, how much low end is arriving that the bassline does not explain.
+   *
+   * **The one to drive a visual from, and `energy` is usually not.** `energy` is the raw sum of
+   * the two lowest bands with a gain on it, which is honest about what it says and useless on
+   * anything mastered loud: on a bass-heavy master it reaches its own ceiling and stays there,
+   * so a consumer reading it draws a constant. Measured on a phonk track through this detector:
+   * `energy` sat at 1.000 in every frame of a two-minute sample.
+   *
+   * This is the whitened signal the detector already computes for its own gating — the level
+   * left after the bassline, the mud and the low mids are masked out of it — which is the part
+   * that actually moves with the kick rather than with how loud the track is. It keeps its
+   * dynamics on the same material where `energy` has none, and it is deliberately not scaled:
+   * it usually runs well under 0.25, and how far a consumer opens that up is a decision about
+   * its own picture rather than about the music.
+   */
+  level = 0;
+
+  constructor(private readonly nodes: KickDetectorNodes) {
+    this.wideFreq = new Float32Array(nodes.wide.frequencyBinCount);
+    this.kickFreq = new Float32Array(nodes.kick.frequencyBinCount);
+
+    const nyquist = nodes.context.sampleRate / 2;
+    const bin = (hz: number, length: number): number =>
+      Math.max(0, Math.min(length, Math.floor((hz / nyquist) * length)));
+
+    const ranges: Record<string, readonly [number, number]> = {};
+    for (const [name, band] of Object.entries(RHYTHM_BANDS)) {
+      const from = bin(band.lowHz, this.wideFreq.length);
+      ranges[name] = [from, Math.max(from + 1, bin(band.highHz, this.wideFreq.length))];
+    }
+    this.ranges = ranges;
+    this.kickBand = [
+      bin(PEAK_MIN_HZ, this.kickFreq.length),
+      Math.max(1, bin(PEAK_MAX_HZ, this.kickFreq.length)),
+    ];
+  }
+
+  /** One frame. Reads the analysers and advances the pulse. */
+  update(nowMs: number): void {
+    const dtSec = this.lastUpdateMs === 0 ? 1 / 60 : (nowMs - this.lastUpdateMs) / 1000;
+    this.lastUpdateMs = nowMs;
+
+    this.nodes.wide.getFloatFrequencyData(this.wideFreq);
+    this.nodes.kick.getFloatFrequencyData(this.kickFreq);
+
+    const bands = this.bands;
+    bands.sub = this.band('sub');
+    bands.punch = this.band('punch');
+    bands.sweet = this.band('sweet');
+    bands.bassline = this.band('bassline');
+    bands.mud = this.band('mud');
+    bands.lowMid = this.band('lowMid');
+    bands.high = this.band('high');
+
+    /*
+     * Follow the track's actual kick fundamental rather than assuming one.
+     * A 55 Hz 808 and an 80 Hz acoustic kick are both kicks, and a fixed
+     * band-pass tuned between them hears neither well.
+     */
+    this.trackPeak();
+
+    /*
+     * The decision itself, shared with `beatMap.ts` — see `kickCore.ts`. It takes `dtSec`, which
+     * is what makes this detector behave the same whether a consumer calls it sixty times a
+     * second or a hundred and forty-four. It used to be a per-call lerp, so the same track was
+     * detected differently on different displays, and differently again from the offline
+     * analyser that the cuts of a replay are made against.
+     */
+    this.core.step(bands, dtSec, this.peakHz);
+
+    const hit = this.core.rising && nowMs - this.lastHitMs > MIN_INTERVAL_MS;
+    const onset = this.core.onset;
+    const onsetFloor = this.core.onsetFloor;
+    const lowSum = bands.sub + bands.punch;
+
+    // Decay first, then let a hit override — so a hit always starts from full
+    // rather than from whatever was left of the previous one.
+    this.pulse = kickPulseAfter(this.pulse, dtSec);
+    if (hit) {
+      this.lastHitMs = nowMs;
+      this.pulse = Math.min(1, 0.55 + (onset - onsetFloor) / Math.max(1e-6, onsetFloor * 3));
+    }
+    this.energy = Math.min(1, lowSum * 1.6);
+    /* Clamped only so the documented range holds; the whitening is what keeps it well below 1
+       on real material, and that is the property a consumer is reading it for. */
+    this.level = Math.min(1, this.core.whitened);
+  }
+
+  /**
+   * The band's RMS amplitude, which is what `beatMap.ts` measures and what `kickCore.ts` is
+   * tuned against.
+   *
+   * **The sum of squares, not the mean of the magnitudes, and the difference is not cosmetic.**
+   * `beatMap` runs a filter bank over the samples and takes the root mean square of what comes
+   * out, so its numbers are the amplitude actually present in that band. A mean of per-bin
+   * magnitudes is that amplitude divided by however many bins the band happens to span, which
+   * changes with the FFT size and is a different quantity from the one every floor and gate here
+   * was tuned on. Measured on a real track through the site: a mean gave one detected kick in
+   * eight seconds, because the absolute floors sat far above a signal that had been divided by
+   * the width of its own band. Parseval is the relation that puts the two back on one scale.
+   */
+  private band(name: string): number {
+    const range = this.ranges[name];
+    if (range === undefined) return 0;
+    let sum = 0;
+    for (let i = range[0]; i < range[1]; i++) {
+      const amplitude = decibelsToAmplitude(this.wideFreq[i] ?? -Infinity);
+      sum += amplitude * amplitude;
+    }
+    return Math.sqrt(sum);
+  }
+
+  /** Slide the band-pass toward whichever bin in the kick range is loudest. */
+  private trackPeak(): void {
+    let peakValue = -Infinity;
+    let peakIndex = this.kickBand[0];
+    for (let i = this.kickBand[0]; i < this.kickBand[1]; i++) {
+      /* Compared in decibels, which is monotonic in amplitude, so the loudest bin is the same
+         one either way and there is nothing to convert for an argmax. */
+      const v = this.kickFreq[i] ?? -Infinity;
+      if (v > peakValue) {
+        peakValue = v;
+        peakIndex = i;
+      }
+    }
+    if (!Number.isFinite(peakValue)) return;
+
+    const nyquist = this.nodes.context.sampleRate / 2;
+    const hz = (peakIndex / Math.max(1, this.kickFreq.length)) * nyquist;
+    const clamped = Math.min(Math.max(hz, PEAK_MIN_HZ), PEAK_MAX_HZ);
+    this.peakHz += (clamped - this.peakHz) * PEAK_FOLLOW;
+    this.nodes.bandpass.frequency.setTargetAtTime(
+      this.peakHz,
+      this.nodes.context.currentTime,
+      PEAK_FOLLOW_TIME,
+    );
+  }
+}

package/src/rhythm/renderedPulse.ts

@@ -0,0 +1,147 @@
+import { RHYTHM_BANDS } from './bands.ts';
+
+/**
+ * The kick envelope of an already-rendered mix, readable at any instant.
+ *
+ * `KickDetector` reacts to a live analyser, which is the only thing possible when the
+ * music has not been written yet. An offline clip render has the opposite problem and
+ * the better one: the score is a finished `AudioBuffer` before the first frame is drawn,
+ * so the pulse for frame `f` can be *read* at exactly `f/60` rather than chased.
+ *
+ * Which matters because without it an offline clip's lights would sit still while the
+ * live game's pulse with the music. A replay and an export have to carry the same
+ * timing, the same effects and the same flashing as the live run.
+ *
+ * The envelope is computed once, at a fixed hop, and read by interpolation — so the
+ * cost is one pass over the score instead of an analysis per frame, and two exports of
+ * the same run flash identically.
+ *
+ * Game-agnostic: a buffer in, a level out.
+ */
+
+/** Analysis hop, seconds. About 5 ms, so a kick's attack lands in one or two windows. */
+const HOP_SEC = 0.005;
+/**
+ * How fast the envelope may fall, per second of level.
+ *
+ * A kick's *attack* is what a light answers to, so the reading rises instantly and
+ * decays: without that the flash ends the moment the transient does, which reads as a
+ * flicker rather than as a pulse. Six is a little under a fifth of a second to fall from
+ * full, which is the length the live detector's own envelope settles to.
+ */
+const DECAY_PER_SEC = 6;
+
+/**
+ * Resonance of each band-pass stage.
+ *
+ * Two is narrow enough to matter and wide enough to keep a kick's whole attack. The
+ * *cascade* is what does the work: one stage leaves a 140 Hz bassline about 12 dB down,
+ * which is not separation. Two measure 20 dB — an amplitude ratio of ten — so a bassline
+ * louder than the kick stops swamping it.
+ */
+const STAGE_Q = 2;
+
+/**
+ * Band-limited energy per hop, over the whole signal in one pass.
+ *
+ * **One pass, with the filter state carried across hops.** The first version filtered
+ * each window from a fresh state, which makes every window boundary an impulse — and an
+ * impulse into a resonant filter rings at the filter's own frequency, so a pure 140 Hz
+ * bassline produced 66 Hz energy out of nothing. Measured: the bassline read 0.47 of the
+ * clip's peak between kicks, where it should have read a tenth of that. A filter is a
+ * thing with memory and cutting its memory up destroys what it is for.
+ *
+ * Centred on the geometric mean of `sub.lowHz` and `sweet.highHz`, so "a kick" means
+ * here what `RHYTHM_BANDS` means everywhere else in the engine — the same numbers drive
+ * the offline edit's cuts, and a light disagreeing with a cut about what a kick is would
+ * be a clip fighting itself.
+ */
+function kickEnergyPerHop(samples: Float32Array, rate: number, hop: number): Float32Array {
+  const centreHz = Math.sqrt(RHYTHM_BANDS.sub.lowHz * RHYTHM_BANDS.sweet.highHz);
+  const f = 2 * Math.sin((Math.PI * centreHz) / rate);
+  const q = 1 / STAGE_Q;
+  const count = Math.max(1, Math.ceil(samples.length / hop));
+  const levels = new Float32Array(count);
+
+  let lowA = 0;
+  let bandA = 0;
+  let lowB = 0;
+  let bandB = 0;
+  let sum = 0;
+  let bin = 0;
+  let taken = 0;
+  for (let i = 0; i < samples.length; i++) {
+    const input = samples[i] ?? 0;
+    const highA = input - lowA - q * bandA;
+    bandA += f * highA;
+    lowA += f * bandA;
+    // The second stage reads the first's band output: two poles become four.
+    const highB = bandA - lowB - q * bandB;
+    bandB += f * highB;
+    lowB += f * bandB;
+    sum += bandB * bandB;
+    taken++;
+    if (taken === hop) {
+      levels[bin] = Math.sqrt(sum / hop);
+      bin++;
+      sum = 0;
+      taken = 0;
+    }
+  }
+  if (taken > 0 && bin < count) levels[bin] = Math.sqrt(sum / taken);
+  return levels;
+}
+
+export class RenderedPulse {
+  private readonly levels: Float32Array;
+  private readonly hopSec: number;
+
+  /**
+   * @param buffer The rendered mix. Channel 0 is read; a kick is not a stereo event.
+   */
+  constructor(buffer: AudioBuffer) {
+    const rate = buffer.sampleRate;
+    const samples = buffer.getChannelData(0);
+    const hop = Math.max(1, Math.round(HOP_SEC * rate));
+    const raw = kickEnergyPerHop(samples, rate, hop);
+    const count = raw.length;
+
+    let peak = 0;
+    for (const level of raw) {
+      if (level > peak) peak = level;
+    }
+
+    /*
+     * Normalised against the loudest moment in this clip, not against an absolute
+     * figure. A quiet track would otherwise never flash and a loud one would sit at
+     * full — and the light is a *reaction to the music*, which is relative by nature.
+     */
+    const scale = peak > 1e-6 ? 1 / peak : 0;
+    const fall = (DECAY_PER_SEC * hop) / rate;
+    let envelope = 0;
+    for (let i = 0; i < count; i++) {
+      const level = (raw[i] ?? 0) * scale;
+      // Rise instantly, fall slowly: a light answers a kick's attack, not its energy.
+      envelope = level > envelope ? level : Math.max(level, envelope - fall);
+      raw[i] = envelope;
+    }
+
+    this.levels = raw;
+    this.hopSec = hop / rate;
+  }
+
+  /**
+   * The pulse at `seconds`, 0–1.
+   *
+   * Interpolated between hops so a light moves smoothly at any frame rate rather than
+   * stepping at the analysis rate.
+   */
+  at(seconds: number): number {
+    const position = Math.max(0, seconds) / this.hopSec;
+    const index = Math.floor(position);
+    const first = this.levels[Math.min(index, this.levels.length - 1)] ?? 0;
+    const second = this.levels[Math.min(index + 1, this.levels.length - 1)] ?? first;
+    const fraction = position - index;
+    return first + (second - first) * fraction;
+  }
+}

package/src/session.ts

@@ -0,0 +1,93 @@
+/**
+ * Getting an AudioContext, and keeping it when a device tries to take it away.
+ *
+ * Separate from the graph because it is a question about the browser rather than about this
+ * engine's mix. An application building its own audio outside `AudioGraph` needs exactly
+ * these two and none of the rest, which is why both are already on the package barrel.
+ */
+
+/**
+ * The page's audio session, where the browser has one to give.
+ *
+ * WebKit-only, and not in the DOM lib, so it is described here structurally rather
+ * than asserted onto `Navigator`.
+ */
+interface AudioSessionLike {
+  type: string;
+}
+
+/**
+ * Claim the **playback** session, so a phone in a pocket is still audible.
+ *
+ * This is the whole of "no audio at all" on an iPhone that plays every other site,
+ * and it is a policy rather than a fault anywhere below. iOS files
+ * Web Audio under the *ambient* session, and an ambient session is exactly what the
+ * hardware ringer switch silences — while a `<video>` or an `<audio>` element is
+ * filed under playback and is not. So a page built out of `AudioContext`, which is
+ * every page this engine draws, is the one kind that goes completely quiet on a
+ * phone whose owner flicked one switch, with nothing wrong in the graph, the gesture
+ * or the files. Everything else on the web keeps working, which is what makes it
+ * read as a bug in the game.
+ *
+ * `playback` is the honest declaration for a game whose sound is a pillar: this
+ * page's audio *is* the point of it. It also means the page interrupts whatever else
+ * the phone was playing — which is the correct trade for a soundtrack that starts
+ * with the world, and the reason this is not claimed until a graph is actually being
+ * built.
+ *
+ * Safari-only today (Chrome and Firefox expose no `audioSession`), and every failure
+ * mode here is a no-op: a browser without the property, or one that refuses the
+ * value, is left exactly as it was.
+ */
+/**
+ * Tell WebKit that this page's audio is the point of it, before any context exists.
+ *
+ * **Exported for a second consumer that cannot use `AudioGraph`.** This class is a stem
+ * player for a game soundtrack; an application that decodes one file and runs it through
+ * its own chain needs this line and not the graph, and a copy of it in another repository
+ * is a second version of an iOS behaviour that will be wrong the next time WebKit moves.
+ *
+ * The ordering is the part a copy gets wrong and the part a diff cannot show: claimed
+ * **before** the context is constructed, so the context is born into the right session.
+ * See `autoplay.test.ts` for what it is for: iOS puts Web Audio in the *ambient* session,
+ * which the ringer switch silences, so a page built out of `AudioContext` is the one kind
+ * that goes quiet in a pocket.
+ */
+export function claimPlaybackSession(): void {
+  if (typeof navigator === 'undefined') return;
+  const session = (navigator as Navigator & { audioSession?: AudioSessionLike }).audioSession;
+  if (session === undefined || session === null) return;
+  try {
+    session.type = 'playback';
+  } catch {
+    // A property that exists but will not take the value is not a failure to
+    // report: the graph below is built either way, at whatever volume the phone
+    // is willing to give it.
+  }
+}
+
+/**
+ * The live-context constructor this browser has, prefixed or not.
+ *
+ * `webkitAudioContext` is the only one on iOS before 14.5, and a browser old enough
+ * to need it is exactly the browser nobody testing this owns.
+ */
+export function audioContextConstructor(): typeof AudioContext | undefined {
+  if (typeof AudioContext !== 'undefined') return AudioContext;
+  const prefixed = (globalThis as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+  return prefixed;
+}
+
+/** A name for a thrown thing, for the one telemetry string that reports silence. */
+export function errorName(error: unknown): string {
+  return error instanceof Error ? error.name : 'unknown';
+}
+
+/**
+ * The long tail: seconds of impulse, and how fast it decays inside them.
+ *
+ * Long enough to carry a whole airborne moment — a jump is under a second, a glide
+ * several — and decaying slowly enough that the music is *spread out* rather than
+ * merely echoed. Beyond about eight seconds it stops sounding like a space and
+ * starts sounding like a stuck effect.
+ */