@driftengine/audio 3.61.0

package/dist/registry.js

@@ -0,0 +1,128 @@
+export class SoundRegistry {
+    fetchImpl;
+    sources = new Map();
+    buffers = new Map();
+    origins = new Map();
+    /** Slots whose stand-in threw. Empty is the normal state; see `unbuilt`. */
+    failed = new Map();
+    constructor(fetchImpl = (url) => fetch(url)) {
+        this.fetchImpl = fetchImpl;
+    }
+    register(slot, source) {
+        this.sources.set(slot, source);
+    }
+    /** Which slots exist, so callers can pick among them (e.g. a daily track). */
+    get slots() {
+        return [...this.sources.keys()];
+    }
+    /**
+     * Slots whose stand-in threw, and what it said.
+     *
+     * Empty is the normal state. A consumer with a dev overlay should show this: a silent slot is
+     * otherwise indistinguishable from one nobody triggered.
+     */
+    get unbuilt() {
+        return this.failed;
+    }
+    get resolved() {
+        return this.origins;
+    }
+    /**
+     * Adopt already-decoded buffers, skipping every fetch and decode.
+     *
+     * For building a second graph over the same sounds — an offline render of a mix that
+     * is already loaded. An `AudioBuffer` is PCM and a sample rate, not a handle onto the
+     * context that made it, so it can be used by any context running at the same rate;
+     * decoding the library again would cost the whole payload a second time and, worse,
+     * could resolve a slot differently from the mix being reproduced.
+     */
+    adopt(from) {
+        for (const [slot, buffer] of from.buffers)
+            this.buffers.set(slot, buffer);
+        for (const [slot, origin] of from.origins)
+            this.origins.set(slot, origin);
+        for (const [slot, source] of from.sources) {
+            if (!this.sources.has(slot))
+                this.sources.set(slot, source);
+        }
+    }
+    get(slot) {
+        return this.buffers.get(slot);
+    }
+    /**
+     * Resolve every slot: the files in parallel, then the stand-ins one at a time.
+     *
+     * Slots settle independently: one missing or corrupt asset must not silence
+     * the rest of the game, which is the likeliest real failure once assets are
+     * being dropped in by hand. Every failure mode — network error, HTTP status,
+     * undecodable bytes — lands on the same fallback, because from the player's
+     * side they are the same event.
+     *
+     * **The two halves are separated because they cost completely different
+     * things.** Fetching is waiting, and twenty slots should wait together.
+     * Synthesis is arithmetic on the main thread — an ambience bed is seven
+     * seconds of filtered noise at the context's sample rate — and twenty of those
+     * settling together lands as one block of work.
+     *
+     * Which is exactly what it did. Traced on 2026-08-07 on a game that starts its
+     * audio at boot, the fallbacks arrived as microtask blocks of 11, 14, 14, 21
+     * and 34 ms while the player was already running, and the frame loop went
+     * 125 ms between frames because the vsync deadline kept landing inside one.
+     * So each stand-in gets its own task. The work is the same; what changes is
+     * that a frame can be drawn between any two of them.
+     *
+     * The yield is a timer rather than a microtask, and that is the whole point —
+     * a microtask would rejoin the block it is trying to leave. Whatever the
+     * browser clamps the delay to only spaces the work further.
+     */
+    async load(ctx) {
+        const entries = [...this.sources.entries()];
+        await Promise.allSettled(entries.map(([slot, source]) => this.loadFile(ctx, slot, source)));
+        for (const [slot, source] of entries) {
+            if (this.buffers.has(slot))
+                continue;
+            await new Promise((resolve) => {
+                setTimeout(resolve, 0);
+            });
+            /*
+             * **Each stand-in settles on its own, which is what the paragraph above already promised
+             * and what this loop did not deliver.** File failures land on `allSettled` and every one of
+             * them is contained; a *synth* that threw took the whole `load` down with it — so every slot
+             * after it in registration order was left with no buffer, and `play` returns silently on an
+             * undefined one. The symptom is a game where the first few sounds work and the rest do not,
+             * with nothing in the console after the one throw, and the boundary falling wherever the
+             * consumer happened to register the bad slot.
+             *
+             * Caught rather than rethrown for the same reason a missing file is: from the player's side
+             * a slot that cannot be built and one that cannot be fetched are the same event, and neither
+             * is worth the rest of the game's audio.
+             */
+            try {
+                this.buffers.set(slot, source.synth(ctx));
+                this.origins.set(slot, 'synth');
+            }
+            catch (error) {
+                this.failed.set(slot, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    /** The first candidate that loads and decodes wins; none of them is normal. */
+    async loadFile(ctx, slot, source) {
+        for (const url of source.urls) {
+            try {
+                const response = await this.fetchImpl(url);
+                if (!response.ok)
+                    throw new Error(`HTTP ${response.status}`);
+                const bytes = await response.arrayBuffer();
+                const buffer = await ctx.decodeAudioData(bytes);
+                this.buffers.set(slot, buffer);
+                this.origins.set(slot, 'file');
+                return;
+            }
+            catch {
+                // Try the next format. A missing candidate is the normal case, not
+                // an error: most slots will only ever have one of these present.
+            }
+        }
+    }
+}

package/dist/rhythm/bands.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The frequency bands every rhythm detector in the engine reads.
+ *
+ * One definition, shared by the offline analyser and the live detector, so
+ * "a kick" means the same thing whether it is being found ahead of time for an
+ * edit or reacted to in the moment for a light. Two sets of numbers that
+ * drifted apart would produce a replay whose cuts disagreed with the lights in
+ * the very footage they are cutting.
+ *
+ * The split is finer than "bass / mid / treble" because the hard problem is not
+ * finding low energy, it is telling a *kick* apart from a sustained bassline
+ * sitting in nearly the same octave. `sub`/`punch`/`sweet` are the kick;
+ * `bassline`/`mud` are what has to be subtracted from it.
+ */
+export interface Band {
+    readonly lowHz: number;
+    readonly highHz: number;
+}
+export declare const RHYTHM_BANDS: {
+    readonly sub: {
+        readonly lowHz: 40;
+        readonly highHz: 60;
+    };
+    readonly punch: {
+        readonly lowHz: 60;
+        readonly highHz: 100;
+    };
+    readonly sweet: {
+        readonly lowHz: 75;
+        readonly highHz: 110;
+    };
+    readonly bassline: {
+        readonly lowHz: 95;
+        readonly highHz: 180;
+    };
+    readonly mud: {
+        readonly lowHz: 180;
+        readonly highHz: 420;
+    };
+    readonly lowMid: {
+        readonly lowHz: 500;
+        readonly highHz: 2500;
+    };
+    readonly high: {
+        readonly lowHz: 5000;
+        readonly highHz: 12000;
+    };
+};
+export type BandName = keyof typeof RHYTHM_BANDS;
+/** Energy in each band, 0–1, filled in place so nothing allocates per hop. */
+export interface BandEnergies {
+    sub: number;
+    punch: number;
+    sweet: number;
+    bassline: number;
+    mud: number;
+    lowMid: number;
+    high: number;
+}
+export declare function createBandEnergies(): BandEnergies;

package/dist/rhythm/bands.js

@@ -0,0 +1,12 @@
+export const RHYTHM_BANDS = {
+    sub: { lowHz: 40, highHz: 60 },
+    punch: { lowHz: 60, highHz: 100 },
+    sweet: { lowHz: 75, highHz: 110 },
+    bassline: { lowHz: 95, highHz: 180 },
+    mud: { lowHz: 180, highHz: 420 },
+    lowMid: { lowHz: 500, highHz: 2500 },
+    high: { lowHz: 5000, highHz: 12000 },
+};
+export function createBandEnergies() {
+    return { sub: 0, punch: 0, sweet: 0, bassline: 0, mud: 0, lowMid: 0, high: 0 };
+}

package/dist/rhythm/beatGrid.d.ts

@@ -0,0 +1,32 @@
+import type { BeatMap } from './beatMap.ts';
+/**
+ * A beat map from a tempo the player supplies rather than one we detected.
+ *
+ * The reason this exists is the workflow, not the maths. On TikTok and Reels
+ * the trending sound is added *in the app*, replacing whatever audio the clip
+ * arrived with — so the thing that has to line up is not our audio against
+ * theirs, it is our *cuts* against their sound. A player who taps along to the
+ * track they intend to use gets an edit that fits it, and it works with any
+ * song in existence precisely because we never touch the song.
+ *
+ * The output is an ordinary `BeatMap`, so nothing downstream needs to know
+ * where its beats came from.
+ */
+export declare function beatGrid(bpm: number, offsetSec: number, durationSec: number): BeatMap;
+/**
+ * Tempo and phase, from somebody tapping along.
+ *
+ * Phase is the part that matters. A player could type a BPM; what they cannot
+ * type is *where the downbeat falls* in the sound they are about to add, and a
+ * grid at the right tempo with the wrong phase is off by up to half a beat
+ * everywhere — worse than not syncing at all.
+ */
+export declare class TapTempo {
+    private readonly taps;
+    tap(nowMs: number): void;
+    /** Null until there is enough to be sure, and for anything implausible. */
+    get bpm(): number | null;
+    /** Seconds, from the same clock the taps were given in. */
+    get offsetSec(): number;
+    reset(): void;
+}

package/dist/rhythm/beatGrid.js

@@ -0,0 +1,98 @@
+/**
+ * A beat map from a tempo the player supplies rather than one we detected.
+ *
+ * The reason this exists is the workflow, not the maths. On TikTok and Reels
+ * the trending sound is added *in the app*, replacing whatever audio the clip
+ * arrived with — so the thing that has to line up is not our audio against
+ * theirs, it is our *cuts* against their sound. A player who taps along to the
+ * track they intend to use gets an edit that fits it, and it works with any
+ * song in existence precisely because we never touch the song.
+ *
+ * The output is an ordinary `BeatMap`, so nothing downstream needs to know
+ * where its beats came from.
+ */
+export function beatGrid(bpm, offsetSec, durationSec) {
+    const safeBpm = Number.isFinite(bpm) && bpm > 0 ? bpm : 120;
+    const period = 60 / safeBpm;
+    const length = Math.max(0, Number.isFinite(durationSec) ? durationSec : 0);
+    /*
+     * Wrapped into the first beat. A player nudging the offset will run it past a
+     * whole beat without thinking about it, and a grid that then started a second
+     * in would silently lose the opening cut.
+     */
+    const raw = Number.isFinite(offsetSec) ? offsetSec : 0;
+    const first = ((raw % period) + period) % period;
+    const count = length <= 0 ? 0 : Math.max(0, Math.floor((length - first) / period) + 1);
+    const beats = new Float32Array(count);
+    const strength = new Float32Array(count);
+    for (let i = 0; i < count; i++) {
+        beats[i] = first + i * period;
+        // Every fourth beat is the downbeat. Not detected — asserted, because that
+        // is what a player tapping four to the bar means by it.
+        strength[i] = i % 4 === 0 ? 1 : 0.6;
+    }
+    return {
+        beats,
+        strength,
+        bpm: safeBpm,
+        bpmConfidence: 1,
+        energy: new Float32Array([1]),
+        energyHz: 10,
+        durationSec: length,
+    };
+}
+/** Taps this far apart are two separate attempts, not one tempo. */
+const STALE_MS = 3000;
+/** Below four taps there are too few intervals to reject a fumble. */
+const MIN_TAPS = 4;
+const MAX_TAPS = 8;
+/** Outside this a "tempo" is a double-tap or somebody who wandered off. */
+const MIN_BPM = 60;
+const MAX_BPM = 200;
+/**
+ * Tempo and phase, from somebody tapping along.
+ *
+ * Phase is the part that matters. A player could type a BPM; what they cannot
+ * type is *where the downbeat falls* in the sound they are about to add, and a
+ * grid at the right tempo with the wrong phase is off by up to half a beat
+ * everywhere — worse than not syncing at all.
+ */
+export class TapTempo {
+    taps = [];
+    tap(nowMs) {
+        const previous = this.taps[this.taps.length - 1];
+        // A gap means they stopped and started again. Averaging across it would
+        // produce a tempo of a couple of beats a minute.
+        if (previous !== undefined && nowMs - previous > STALE_MS)
+            this.taps.length = 0;
+        this.taps.push(nowMs);
+        if (this.taps.length > MAX_TAPS)
+            this.taps.shift();
+    }
+    /** Null until there is enough to be sure, and for anything implausible. */
+    get bpm() {
+        if (this.taps.length < MIN_TAPS)
+            return null;
+        const intervals = [];
+        for (let i = 1; i < this.taps.length; i++) {
+            intervals.push((this.taps[i] ?? 0) - (this.taps[i - 1] ?? 0));
+        }
+        // Median, not mean: anybody tapping along will fumble one, and a mean turns
+        // a single 400 ms stumble into a double-digit BPM error.
+        intervals.sort((a, b) => a - b);
+        const median = intervals[intervals.length >> 1] ?? 0;
+        if (median <= 0)
+            return null;
+        const bpm = 60_000 / median;
+        if (bpm < MIN_BPM || bpm > MAX_BPM)
+            return null;
+        return bpm;
+    }
+    /** Seconds, from the same clock the taps were given in. */
+    get offsetSec() {
+        return (this.taps[this.taps.length - 1] ?? 0) / 1000;
+    }
+    reset() {
+        this.taps.length = 0;
+    }
+}

package/dist/rhythm/beatMap.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Offline rhythm analysis: where the kicks are in a whole track.
+ *
+ * Computed once, ahead of time, from decoded samples. That is the important
+ * difference from a live detector, and it buys three things a live one cannot:
+ *
+ *   1. **Cuts land on the beat.** A real-time detector necessarily fires
+ *      *after* the transient it is detecting, and by a varying amount. Offline
+ *      we can look ahead — pick the peak of the onset curve and then walk back
+ *      to where the transient actually began, which is a fixed reference rather
+ *      than "whenever the level happened to cross a threshold".
+ *   2. **Determinism.** Two people watching the same shared run see the same
+ *      edit, and the same run watched twice is identical. Nothing here reads a
+ *      clock or `Math.random`.
+ *   3. **Structure.** Choosing where to spend the best shot needs to see the
+ *      whole track. Real-time analysis by definition cannot.
+ *
+ * The detection is ported from a production kick detector, whose central idea is
+ * *whitening*: in bass-led electronic music the low end is dominated by a sustained
+ * 808, so raw low energy is loud all the time and useless. Subtract a weighted
+ * bassline/mud/low-mid mask from the kick band and take the difference between
+ * a fast and a slow envelope, and only the transient survives.
+ */
+export interface BeatMap {
+    /**
+     * Detected kick onsets in seconds, ascending. These are the hits the
+     * analyser is *sure* about — deliberately not every beat in the track.
+     */
+    readonly beats: Float32Array;
+    /** 0–1 per detected beat, for weighting cuts and flashes. */
+    readonly strength: Float32Array;
+    readonly bpm: number;
+    /** 0–1. Low means the hits are real but irregular — a rubato passage. */
+    readonly bpmConfidence: number;
+    /** Coarse loudness envelope, for finding drops and quiet passages. */
+    readonly energy: Float32Array;
+    readonly energyHz: number;
+    readonly durationSec: number;
+}
+/** A map with no beats in it, for when there is no music to analyse. */
+export declare function emptyBeatMap(durationSec?: number): BeatMap;
+export declare function analyseTrack(samples: Float32Array, sampleRate: number): BeatMap;