@driftengine/audio 3.61.0

package/dist/rhythm/kickDetector.d.ts

@@ -0,0 +1,65 @@
+/** Envelope of a pulse of `peak` strength, `seconds` after it fired. */
+export declare function kickPulseAfter(peak: number, seconds: number): number;
+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;
+}
+export declare class KickDetector {
+    private readonly nodes;
+    private readonly wideFreq;
+    private readonly kickFreq;
+    private readonly ranges;
+    private readonly kickBand;
+    private peakHz;
+    /** The shared decision, stepped once per frame. See `kickCore.ts`. */
+    private readonly core;
+    private lastHitMs;
+    private lastUpdateMs;
+    /** Reused so `core.step` is handed one object rather than a fresh literal every frame. */
+    private readonly bands;
+    /** 0–1, spiking on a kick and decaying back. What a light should follow. */
+    pulse: number;
+    /** Smoothed low-end presence, for anything that wants level rather than hits. */
+    energy: number;
+    /**
+     * 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: number;
+    constructor(nodes: KickDetectorNodes);
+    /** One frame. Reads the analysers and advances the pulse. */
+    update(nowMs: number): void;
+    /**
+     * 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;
+    /** Slide the band-pass toward whichever bin in the kick range is loudest. */
+    private trackPeak;
+}

package/dist/rhythm/kickDetector.js

@@ -0,0 +1,202 @@
+import { RHYTHM_BANDS } from './bands.js';
+import { KickCore, MIN_INTERVAL_MS, PEAK_MAX_HZ, PEAK_MIN_HZ } from './kickCore.js';
+/**
+ * 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, seconds) {
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return peak;
+    const value = peak * Math.exp(-PULSE_DECAY * seconds);
+    return value < 1e-3 ? 0 : value;
+}
+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) {
+    return Number.isFinite(db) ? Math.pow(10, db / 20) : 0;
+}
+export class KickDetector {
+    nodes;
+    /*
+     * **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.
+     */
+    wideFreq;
+    kickFreq;
+    ranges;
+    kickBand;
+    peakHz = 62;
+    /** The shared decision, stepped once per frame. See `kickCore.ts`. */
+    core = new KickCore();
+    lastHitMs = Number.NEGATIVE_INFINITY;
+    lastUpdateMs = 0;
+    /** Reused so `core.step` is handed one object rather than a fresh literal every frame. */
+    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(nodes) {
+        this.nodes = nodes;
+        this.wideFreq = new Float32Array(nodes.wide.frequencyBinCount);
+        this.kickFreq = new Float32Array(nodes.kick.frequencyBinCount);
+        const nyquist = nodes.context.sampleRate / 2;
+        const bin = (hz, length) => Math.max(0, Math.min(length, Math.floor((hz / nyquist) * length)));
+        const ranges = {};
+        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) {
+        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.
+     */
+    band(name) {
+        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. */
+    trackPeak() {
+        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/dist/rhythm/renderedPulse.d.ts

@@ -0,0 +1,15 @@
+export declare class RenderedPulse {
+    private readonly levels;
+    private readonly hopSec;
+    /**
+     * @param buffer The rendered mix. Channel 0 is read; a kick is not a stereo event.
+     */
+    constructor(buffer: AudioBuffer);
+    /**
+     * 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;
+}

package/dist/rhythm/renderedPulse.js

@@ -0,0 +1,138 @@
+import { RHYTHM_BANDS } from './bands.js';
+/**
+ * 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, rate, hop) {
+    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 {
+    levels;
+    hopSec;
+    /**
+     * @param buffer The rendered mix. Channel 0 is read; a kick is not a stereo event.
+     */
+    constructor(buffer) {
+        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) {
+        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/dist/session.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function claimPlaybackSession(): void;
+/**
+ * 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 declare function audioContextConstructor(): typeof AudioContext | undefined;
+/** A name for a thrown thing, for the one telemetry string that reports silence. */
+export declare function errorName(error: unknown): string;
+/**
+ * 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.
+ */

package/dist/session.js

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ */
+/**
+ * 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() {
+    if (typeof navigator === 'undefined')
+        return;
+    const session = navigator.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() {
+    if (typeof AudioContext !== 'undefined')
+        return AudioContext;
+    const prefixed = globalThis.webkitAudioContext;
+    return prefixed;
+}
+/** A name for a thrown thing, for the one telemetry string that reports silence. */
+export function errorName(error) {
+    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.
+ */