@driftengine/audio 3.61.0

package/dist/audioHarness.js

@@ -0,0 +1,244 @@
+/**
+ * A Web Audio context that answers everything, for tests that need a graph and not a browser.
+ *
+ * **Not a `.test.ts` file, and that is the point.** Vitest registers a test when the file declaring
+ * it is imported, so a test file importing a stub from beside another file's tests would re-run
+ * every test in that file too. Split out so importing the harness costs nothing but the harness —
+ * the same reasoning, and the same shape, as `rendererHarness.ts` in core.
+ *
+ * **It exists because there were three of these.** `autoplay.test.ts`, `graph.test.ts` and
+ * `mixOutput.test.ts` each carried their own `StubNode` and their own `param()`, and they had
+ * already drifted: one recorded what was connected to it and two did not, one had an
+ * `fftSize` of 512 and another 2048, one could decode audio and the others could not. `AGENTS.md`'s
+ * 2026-08-17 rule is exactly this — two implementations of one decision drift, and they drift
+ * invisibly when the constants look identical.
+ *
+ * **A stub is not a contract and nothing here is tested directly.** What it must do is let the real
+ * graph build and let a test read back what the graph did. Where a member exists only so a
+ * constructor does not throw, it does nothing and says so.
+ */
+export function stubParam() {
+    const ramps = [];
+    return {
+        value: 0,
+        ramps,
+        setValueAtTime: (value, at) => ramps.push({ value, at }),
+        linearRampToValueAtTime: (value, at) => ramps.push({ value, at }),
+        cancelScheduledValues: () => undefined,
+        setTargetAtTime: (value, at) => ramps.push({ value, at }),
+    };
+}
+/**
+ * A node that remembers what was connected to it. Enough graph to build against.
+ *
+ * `inputs` is what makes a topology assertable at all: the browser's own graph is write-only, so a
+ * test asking "is the send taken from the output or the input" has nowhere else to look.
+ */
+export class StubNode {
+    inputs = [];
+    /** Instants `stop` was asked for, so a test can see whether a fade preceded one. */
+    stops = [];
+    /** Instants `start` was asked for, so a test can see an offline launch has no lead. */
+    starts = [];
+    type = '';
+    buffer = null;
+    loop = false;
+    gain = stubParam();
+    frequency = stubParam();
+    Q = stubParam();
+    delayTime = stubParam();
+    playbackRate = stubParam();
+    pan = stubParam();
+    fftSize = 2048;
+    smoothingTimeConstant = 0;
+    frequencyBinCount = 1024;
+    /** A buffer source answers this; the spatial layer drives it for doppler. */
+    detune = stubParam();
+    /**
+     * The channel plumbing a multi-channel source needs.
+     *
+     * `channelInterpretation` is the one that matters and is the one a test asserts: the default
+     * up-mixes or down-mixes by *meaning*, and W, Y, Z, X are not left, right, centre and low
+     * frequency, so a field read that way comes out as a blur that still plays.
+     */
+    channelCount = 2;
+    channelCountMode = 'max';
+    channelInterpretation = 'speakers';
+    /* What a panner answers. */
+    panningModel = 'equalpower';
+    distanceModel = 'inverse';
+    refDistance = 1;
+    maxDistance = 10000;
+    rolloffFactor = 1;
+    positionX = stubParam();
+    positionY = stubParam();
+    positionZ = stubParam();
+    /**
+     * `output` is accepted and ignored, which is enough for what these tests ask.
+     *
+     * A splitter's outputs go to different nodes, and what a test here checks is *which node* was
+     * connected rather than from which output — the coefficient gains are one per (speaker, channel)
+     * pair, so the pair is already carried by the node's identity.
+     */
+    connect(target, output) {
+        void output;
+        target.inputs.push(this);
+        return target;
+    }
+    disconnect() { }
+    start(at = 0) {
+        this.starts.push(at);
+    }
+    stop(at = 0) {
+        this.stops.push(at);
+    }
+    getByteFrequencyData() { }
+    getFloatFrequencyData() { }
+}
+/**
+ * The listener, in both shapes a browser might offer it.
+ *
+ * Both are present deliberately, because the code under test picks one and the choice is a feature
+ * detection rather than a preference: a test that only had the modern form could not tell whether
+ * the legacy branch was ever written. `positions` records the legacy calls so a test can assert
+ * which branch ran.
+ */
+export class StubListener {
+    positionX = stubParam();
+    positionY = stubParam();
+    positionZ = stubParam();
+    forwardX = stubParam();
+    forwardY = stubParam();
+    forwardZ = stubParam();
+    upX = stubParam();
+    upY = stubParam();
+    upZ = stubParam();
+    positions = [];
+    orientations = [];
+    setPosition(x, y, z) {
+        this.positions.push([x, y, z]);
+    }
+    setOrientation(fx, fy, fz, ux, uy, uz) {
+        this.orientations.push([fx, fy, fz, ux, uy, uz]);
+    }
+}
+export class StubContext {
+    options;
+    destination = new StubNode();
+    /** Every buffer source built, in order, so a test can inspect the transport. */
+    sources = [];
+    listener = new StubListener();
+    /** Every panner built, in order, so a test can inspect what was placed in the world. */
+    panners = [];
+    /**
+     * Every convolver built, in order.
+     *
+     * Counted because "a second routing rather than a second convolver" is a claim about how many of
+     * them exist, and a convolver is the most expensive node in this graph. A test that asserted the
+     * send worked would not notice one being built per source.
+     */
+    convolvers = [];
+    outputLatency = 0;
+    tap = { stream: {}, ...new StubNode() };
+    state;
+    currentTime = 0;
+    sampleRate = 48000;
+    /** How many times a resume was attempted, for the tests about a context that will not start. */
+    resumeCalls = 0;
+    constructor(options = {}) {
+        this.options = options;
+        this.state = options.state ?? 'running';
+        if (options.stereoPanner === false) {
+            this.createStereoPanner = undefined;
+        }
+        if (options.listenerParams === false) {
+            for (const name of ['positionX', 'forwardX', 'upX']) {
+                this.listener[name] = undefined;
+            }
+        }
+    }
+    createGain() {
+        return new StubNode();
+    }
+    createBiquadFilter() {
+        // `type` is assigned by the graph right after creation; tests read it back to find the
+        // master low-pass without knowing the construction order.
+        return new StubNode();
+    }
+    createConvolver() {
+        const convolver = new StubNode();
+        this.convolvers.push(convolver);
+        return convolver;
+    }
+    createWaveShaper() {
+        return new StubNode();
+    }
+    createDelay() {
+        return new StubNode();
+    }
+    createAnalyser() {
+        return new StubNode();
+    }
+    createPanner() {
+        const panner = new StubNode();
+        this.panners.push(panner);
+        return panner;
+    }
+    createBufferSource() {
+        const source = new StubNode();
+        this.sources.push(source);
+        return source;
+    }
+    createStereoPanner() {
+        return new StubNode();
+    }
+    createMediaStreamDestination() {
+        return this.tap;
+    }
+    createChannelSplitter() {
+        return new StubNode();
+    }
+    createChannelMerger() {
+        return new StubNode();
+    }
+    /*
+     * `numberOfChannels` is answered because a decoder that refuses a buffer of the wrong shape has
+     * to be able to see the shape. It was absent, so every such refusal fired against `undefined` —
+     * which happened to be right and for the wrong reason.
+     */
+    createBuffer(channels, length) {
+        const data = new Float32Array(length);
+        return { numberOfChannels: channels, length, getChannelData: () => data };
+    }
+    async decodeAudioData() {
+        return {};
+    }
+    async resume() {
+        this.resumeCalls++;
+        if (this.options.refuseResume === true) {
+            throw new DOMException('play() blocked', 'NotAllowedError');
+        }
+    }
+    async close() { }
+}
+/** The context most tests want: running, complete, and recording what was done to it. */
+export function stubContext(options) {
+    return new StubContext(options);
+}
+/**
+ * Install a stub as the page's `AudioContext` and hand back the one that gets built.
+ *
+ * The graph constructs its own context through the global, so a test that wants to look at the
+ * nodes has to intercept the construction rather than pass one in. Returns a getter rather than
+ * the context, because nothing exists until the code under test asks for it.
+ */
+export function installStubAudioContext(options) {
+    let built = null;
+    globalThis.AudioContext = class {
+        constructor() {
+            built = new StubContext(options);
+            return built;
+        }
+    };
+    return () => built;
+}

package/dist/filters.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The curves: how a cutoff follows speed, and what the lift and slam controls do.
+ *
+ * Pure functions of a number, with the constants they are made of beside them. Separated
+ * from the graph because none of them touches an AudioContext, a node or any class state,
+ * and reading what a control does should not mean paging through the mix that applies it.
+ *
+ * The constants are exported rather than split: `AudioGraph` reads several of them directly,
+ * and tearing a documented block in half so each half sits nearer its caller would put the
+ * numbers in one file and the arithmetic in another.
+ */
+/**
+ * Master low-pass cutoff in Hz for a given speed.
+ *
+ * Exponential in frequency because hearing is: a linear sweep spends most of
+ * its travel in a range that sounds like almost nothing is happening. This is
+ * the "filter opens as you hit full sprint" moment, so it has to track the
+ * *feeling* of accelerating rather than the number.
+ */
+export declare function cutoffForSpeed(speed: number, maxSpeed: number): number;
+export declare function clamp01(value: number): number;
+/**
+ * The lift, at rest and at full.
+ *
+ * 20 Hz is below hearing, so at rest the high-pass is not there. 340 Hz takes the kick
+ * and the bass line out while leaving the body of the track — far enough that the ground
+ * goes with it, short of the telephone-speaker sound a build-up filter reaches for.
+ *
+ * The duck is what makes room for the wet: at 0.62 the dry track sits back far enough
+ * for a six-second tail to be the loudest thing in the air, which is the whole point of
+ * having one.
+ */
+export declare const LIFT_FLOOR_HZ = 20;
+/**
+ * The gate slam: how it is shaped, and how hard it hits.
+ *
+ * `SLAM_SHELF_HZ` is where the boost stops being bass and starts being body — a
+ * shelf much above this pulls the kick's click and the bass line's fundamentals up
+ * together, which is a volume jump rather than a low-end one.
+ *
+ * `SLAM_ATTACK_SEC` is deliberately shorter than a frame at 60 Hz. The hit has to
+ * land on the tick the character crosses the plane; anything that swells into it reads
+ * as the music doing something rather than the gate doing something.
+ *
+ * `SLAM_DUCK` pulls the dry path down as the wet comes up, so what changes is the
+ * *character* of the moment and not simply the volume of it. Without it the slam is
+ * a loudness spike, and a loudness spike on every gate is exhausting by the third.
+ */
+export declare const SLAM_SHELF_HZ = 120;
+export declare const SLAM_SHELF_DB = 15;
+export declare const SLAM_DRIVE = 0.7;
+/**
+ * Where the wet path's low-pass sits at rest and at the bottom of a slam.
+ *
+ * Open is above hearing, so the filter is a no-op between gates and the wet path is
+ * whatever the shelf made of it. Closed is 240 Hz — bass and the very bottom of the
+ * mid, which is the band a kick and a bass line live in and nothing else does.
+ */
+export declare const SLAM_OPEN_HZ = 20000;
+export declare const SLAM_CLOSED_HZ = 240;
+/**
+ * How far the dry path ducks under the wet.
+ *
+ * Raised with the low-pass: the point of the pair is that for an instant the score is
+ * *only* its bottom end, and that cannot happen while the unfiltered track is still
+ * playing underneath at full level.
+ */
+export declare const SLAM_DUCK = 0.72;
+export declare const SLAM_ATTACK_SEC = 0.012;
+export declare const SLAM_DECAY_SEC = 0.11;
+/**
+ * How hard the soft clipper bites, as the `tanh` input scale.
+ *
+ * At 2.4 a signal at full scale comes back at about 0.4 of the way to a square wave
+ * — audibly driven, still recognisably the track. The curve is normalised so unity
+ * in is unity out, which keeps the wet path's own level honest.
+ */
+export declare const SLAM_CLIP_KNEE = 2.4;
+/**
+ * Where the high-pass sits at a given lift, in hertz.
+ *
+ * **Geometric, not linear.** Pitch is logarithmic: a linear sweep from 20 Hz to 340
+ * spends half its travel between 20 and 180, which is almost entirely below the notes a
+ * track is made of — so the first half of a jump would do nothing and the second half
+ * would lurch. Geometrically, half a lift is the geometric mean (82 Hz) and every equal
+ * step of the knob is an equal musical interval, which is what makes the effect read as a
+ * sweep rather than as a switch.
+ */
+export declare function liftFrequencyHz(amount: number): number;
+/** How far the dry track ducks at a given lift: 1 on the ground, `LIFT_DUCK` in the air. */
+export declare function liftGainFor(amount: number): number;

package/dist/filters.js

@@ -0,0 +1,103 @@
+/**
+ * The curves: how a cutoff follows speed, and what the lift and slam controls do.
+ *
+ * Pure functions of a number, with the constants they are made of beside them. Separated
+ * from the graph because none of them touches an AudioContext, a node or any class state,
+ * and reading what a control does should not mean paging through the mix that applies it.
+ *
+ * The constants are exported rather than split: `AudioGraph` reads several of them directly,
+ * and tearing a documented block in half so each half sits nearer its caller would put the
+ * numbers in one file and the arithmetic in another.
+ */
+/**
+ * Master low-pass cutoff in Hz for a given speed.
+ *
+ * Exponential in frequency because hearing is: a linear sweep spends most of
+ * its travel in a range that sounds like almost nothing is happening. This is
+ * the "filter opens as you hit full sprint" moment, so it has to track the
+ * *feeling* of accelerating rather than the number.
+ */
+export function cutoffForSpeed(speed, maxSpeed) {
+    const safeMax = maxSpeed > 1e-6 ? maxSpeed : 1;
+    const t = Math.min(Math.max(speed / safeMax, 0), 1);
+    return 320 * (18000 / 320) ** t;
+}
+export function clamp01(value) {
+    return Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : 0;
+}
+/**
+ * The lift, at rest and at full.
+ *
+ * 20 Hz is below hearing, so at rest the high-pass is not there. 340 Hz takes the kick
+ * and the bass line out while leaving the body of the track — far enough that the ground
+ * goes with it, short of the telephone-speaker sound a build-up filter reaches for.
+ *
+ * The duck is what makes room for the wet: at 0.62 the dry track sits back far enough
+ * for a six-second tail to be the loudest thing in the air, which is the whole point of
+ * having one.
+ */
+export const LIFT_FLOOR_HZ = 20;
+/**
+ * The gate slam: how it is shaped, and how hard it hits.
+ *
+ * `SLAM_SHELF_HZ` is where the boost stops being bass and starts being body — a
+ * shelf much above this pulls the kick's click and the bass line's fundamentals up
+ * together, which is a volume jump rather than a low-end one.
+ *
+ * `SLAM_ATTACK_SEC` is deliberately shorter than a frame at 60 Hz. The hit has to
+ * land on the tick the character crosses the plane; anything that swells into it reads
+ * as the music doing something rather than the gate doing something.
+ *
+ * `SLAM_DUCK` pulls the dry path down as the wet comes up, so what changes is the
+ * *character* of the moment and not simply the volume of it. Without it the slam is
+ * a loudness spike, and a loudness spike on every gate is exhausting by the third.
+ */
+export const SLAM_SHELF_HZ = 120;
+export const SLAM_SHELF_DB = 15;
+export const SLAM_DRIVE = 0.7;
+/**
+ * Where the wet path's low-pass sits at rest and at the bottom of a slam.
+ *
+ * Open is above hearing, so the filter is a no-op between gates and the wet path is
+ * whatever the shelf made of it. Closed is 240 Hz — bass and the very bottom of the
+ * mid, which is the band a kick and a bass line live in and nothing else does.
+ */
+export const SLAM_OPEN_HZ = 20000;
+export const SLAM_CLOSED_HZ = 240;
+/**
+ * How far the dry path ducks under the wet.
+ *
+ * Raised with the low-pass: the point of the pair is that for an instant the score is
+ * *only* its bottom end, and that cannot happen while the unfiltered track is still
+ * playing underneath at full level.
+ */
+export const SLAM_DUCK = 0.72;
+export const SLAM_ATTACK_SEC = 0.012;
+export const SLAM_DECAY_SEC = 0.11;
+/**
+ * How hard the soft clipper bites, as the `tanh` input scale.
+ *
+ * At 2.4 a signal at full scale comes back at about 0.4 of the way to a square wave
+ * — audibly driven, still recognisably the track. The curve is normalised so unity
+ * in is unity out, which keeps the wet path's own level honest.
+ */
+export const SLAM_CLIP_KNEE = 2.4;
+const LIFT_CEILING_HZ = 340;
+const LIFT_DUCK = 0.62;
+/**
+ * Where the high-pass sits at a given lift, in hertz.
+ *
+ * **Geometric, not linear.** Pitch is logarithmic: a linear sweep from 20 Hz to 340
+ * spends half its travel between 20 and 180, which is almost entirely below the notes a
+ * track is made of — so the first half of a jump would do nothing and the second half
+ * would lurch. Geometrically, half a lift is the geometric mean (82 Hz) and every equal
+ * step of the knob is an equal musical interval, which is what makes the effect read as a
+ * sweep rather than as a switch.
+ */
+export function liftFrequencyHz(amount) {
+    return LIFT_FLOOR_HZ * (LIFT_CEILING_HZ / LIFT_FLOOR_HZ) ** clamp01(amount);
+}
+/** How far the dry track ducks at a given lift: 1 on the ground, `LIFT_DUCK` in the air. */
+export function liftGainFor(amount) {
+    return 1 - (1 - LIFT_DUCK) * clamp01(amount);
+}

package/dist/formats.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Audio formats a slot will accept, in preference order.
+ *
+ * Opus first because it is the smallest at equal quality and payload budgets
+ * are always tight, but nothing requires it: whatever format a sound was made
+ * in can be dropped straight in. Every one of these decodes natively in the
+ * browsers a WebGL2 game already requires, so demanding a transcode would buy
+ * nothing and cost the person making the sound a round trip every time they
+ * wanted to hear it in context.
+ */
+export declare const AUDIO_FORMATS: readonly ['opus', 'mp3', 'ogg', 'm4a', 'wav'];
+export type AudioFormat = (typeof AUDIO_FORMATS)[number];
+/**
+ * Every filename a named slot answers to. Feed the result to
+ * `SoundSource.urls`, which tries them in order and takes the first that
+ * loads.
+ */
+export declare function audioCandidateUrls(name: string, baseDir?: string): string[];

package/dist/formats.js

@@ -0,0 +1,19 @@
+/**
+ * Audio formats a slot will accept, in preference order.
+ *
+ * Opus first because it is the smallest at equal quality and payload budgets
+ * are always tight, but nothing requires it: whatever format a sound was made
+ * in can be dropped straight in. Every one of these decodes natively in the
+ * browsers a WebGL2 game already requires, so demanding a transcode would buy
+ * nothing and cost the person making the sound a round trip every time they
+ * wanted to hear it in context.
+ */
+export const AUDIO_FORMATS = ['opus', 'mp3', 'ogg', 'm4a', 'wav'];
+/**
+ * Every filename a named slot answers to. Feed the result to
+ * `SoundSource.urls`, which tries them in order and takes the first that
+ * loads.
+ */
+export function audioCandidateUrls(name, baseDir = '/audio') {
+    return AUDIO_FORMATS.map((ext) => `${baseDir}/${name}.${ext}`);
+}