@driftengine/audio 3.61.0

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Sound: layered stems, synthesis, rhythm analysis, and where a source sits.
+ *
+ * A package because nothing in the renderer ever imported it — the cleanest boundary in the
+ * tree, and 3,151 lines a silent game does not carry.
+ */
+export { SoundRegistry } from './registry.ts';
+export { AudioGraph } from './graph.ts';
+export { cutoffForSpeed } from './filters.ts';
+export { audioContextConstructor, claimPlaybackSession } from './session.ts';
+export { AUDIO_FORMATS, audioCandidateUrls } from './formats.ts';
+export { fetchAudioManifest, parseAudioManifest } from './manifest.ts';
+export type { AudioFormat } from './formats.ts';
+export { AmbientLoop } from './ambientLoop.ts';
+export { analyseTrack, emptyBeatMap } from './rhythm/beatMap.ts';
+export { TapTempo, beatGrid } from './rhythm/beatGrid.ts';
+export { KickDetector, kickPulseAfter } from './rhythm/kickDetector.ts';
+export type { KickDetectorNodes } from './rhythm/kickDetector.ts';
+export type { BeatMap } from './rhythm/beatMap.ts';
+export { RHYTHM_BANDS } from './rhythm/bands.ts';
+export type { Band, BandEnergies, BandName } from './rhythm/bands.ts';
+export { distanceGain, stereoPan } from './positional.ts';
+export { MixConsole } from './mix/console.ts';
+export { MixBus } from './mix/bus.ts';
+export type { MixInsert, InsertOptions, BusOptions } from './mix/bus.ts';
+export type { MixConsoleOptions, MixSnapshot } from './mix/console.ts';
+export { liftInsert, masterFilterInsert, slamInsert } from './mix/inserts.ts';
+export type { LiftInsert, MasterFilterInsert, SlamInsert } from './mix/inserts.ts';
+export { convolverInsert, delayInsert, impulseResponse } from './mix/returns.ts';
+export type { DelayInsert } from './mix/returns.ts';
+export { defaultLayout } from './mix/defaultLayout.ts';
+export type { DefaultLayout } from './mix/defaultLayout.ts';
+export { createListener, AudioListenerGraph } from './spatial/listener.ts';
+export type { OcclusionProbe } from './spatial/listener.ts';
+export { createSpatialSource, SpatialSource } from './spatial/source.ts';
+export type { SpatialOptions } from './spatial/source.ts';
+export { occlusionCutoffHz, occlusionGainFor, smoothToward, ProbeScheduler, } from './spatial/occlusion.ts';
+export { MAX_OPEN_ZONES, addReverbZone, ReverbZone, SourceZoneSend } from './spatial/zones.ts';
+export { ACN_W, ACN_X, ACN_Y, ACN_Z, AmbisonicSoundfield, FOA_CHANNELS, FOA_SPEAKERS, ambisonicFromWorld, createAmbisonicSoundfield, encodeFoa, foaDecodeGain, foaDecodeMatrix, } from './spatial/ambisonic.ts';
+export type { AmbisonicOptions } from './spatial/ambisonic.ts';
+export type { ZoneShape, ZoneOptions } from './spatial/zones.ts';
+export { ambienceBuffer, driftScrapeBuffer, fireLoopBuffer, metalBuffer, noiseBuffer, silentBuffer, toneBuffer, waterLoopBuffer, windLoopBuffer, } from './synth.ts';
+export type { AmbienceOptions } from './synth.ts';
+export type { AudioGraphOptions, MixLevels } from './graph.ts';
+export type { SoundSlot, SoundSource, SoundOrigin, FetchLike } from './registry.ts';
+export { RenderedPulse } from './rhythm/renderedPulse.ts';

package/dist/index.js

@@ -0,0 +1,39 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * Sound: layered stems, synthesis, rhythm analysis, and where a source sits.
+ *
+ * A package because nothing in the renderer ever imported it — the cleanest boundary in the
+ * tree, and 3,151 lines a silent game does not carry.
+ */
+export { SoundRegistry } from './registry.js';
+export { AudioGraph } from './graph.js';
+export { cutoffForSpeed } from './filters.js';
+/* The two lines that make Web Audio audible on an iPhone, for a consumer whose audio is one
+   decoded file through its own chain rather than a stem player. `AudioGraph` already calls both
+   and in this order; anything building its own context has to do the same. */
+export { audioContextConstructor, claimPlaybackSession } from './session.js';
+export { AUDIO_FORMATS, audioCandidateUrls } from './formats.js';
+export { fetchAudioManifest, parseAudioManifest } from './manifest.js';
+export { AmbientLoop } from './ambientLoop.js';
+export { analyseTrack, emptyBeatMap } from './rhythm/beatMap.js';
+export { TapTempo, beatGrid } from './rhythm/beatGrid.js';
+export { KickDetector, kickPulseAfter } from './rhythm/kickDetector.js';
+export { RHYTHM_BANDS } from './rhythm/bands.js';
+export { distanceGain, stereoPan } from './positional.js';
+/* The mix as a tree. `AudioGraph` is built on this and forwards to it, so a consumer only reaches
+   for these when it wants a bus of its own. */
+export { MixConsole } from './mix/console.js';
+export { MixBus } from './mix/bus.js';
+export { liftInsert, masterFilterInsert, slamInsert } from './mix/inserts.js';
+export { convolverInsert, delayInsert, impulseResponse } from './mix/returns.js';
+export { defaultLayout } from './mix/defaultLayout.js';
+/* Placing a sound in the world. Standalone rather than methods on the console, so a consumer that
+   never places one does not carry the panner — see `SpatialSource` and the size gate. */
+export { createListener, AudioListenerGraph } from './spatial/listener.js';
+export { createSpatialSource, SpatialSource } from './spatial/source.js';
+export { occlusionCutoffHz, occlusionGainFor, smoothToward, ProbeScheduler, } from './spatial/occlusion.js';
+export { MAX_OPEN_ZONES, addReverbZone, ReverbZone, SourceZoneSend } from './spatial/zones.js';
+/* A soundfield rather than a source: four channels of direction, decoded at a fixed cost. */
+export { ACN_W, ACN_X, ACN_Y, ACN_Z, AmbisonicSoundfield, FOA_CHANNELS, FOA_SPEAKERS, ambisonicFromWorld, createAmbisonicSoundfield, encodeFoa, foaDecodeGain, foaDecodeMatrix, } from './spatial/ambisonic.js';
+export { ambienceBuffer, driftScrapeBuffer, fireLoopBuffer, metalBuffer, noiseBuffer, silentBuffer, toneBuffer, waterLoopBuffer, windLoopBuffer, } from './synth.js';
+export { RenderedPulse } from './rhythm/renderedPulse.js';

package/dist/manifest.d.ts

@@ -0,0 +1,28 @@
+import type { FetchLike } from './registry.ts';
+/**
+ * Discovering how many sound assets exist, without a hard limit.
+ *
+ * A browser cannot list a directory, so an asset folder has to announce itself
+ * somehow. The three options are a fixed list in code (which caps the library
+ * at whatever number somebody typed), probing upward until requests start
+ * failing (a burst of 404s on every load, and one gap in the numbering silently
+ * truncates the set), or a manifest.
+ *
+ * A manifest, generated from the folder at build time, is the only one of the
+ * three with no ceiling and no wasted requests. Adding an asset stays a matter
+ * of dropping the file in; the manifest catches up on the next build.
+ *
+ * Deliberately not a game concept: this returns names, and the caller decides
+ * that some of them are music.
+ */
+/** Every name in a manifest, or an empty list if there is not one. */
+export declare function fetchAudioManifest(url: string, fetchImpl?: FetchLike): Promise<string[]>;
+/**
+ * Validate a manifest's contents.
+ *
+ * Separated from fetching so the rules can be tested without a network, and
+ * because the rules are the part that matters: a manifest is generated by a
+ * script, and a script that emits one bad entry must not take the rest of the
+ * library down with it.
+ */
+export declare function parseAudioManifest(value: unknown): string[];

package/dist/manifest.js

@@ -0,0 +1,71 @@
+/**
+ * Discovering how many sound assets exist, without a hard limit.
+ *
+ * A browser cannot list a directory, so an asset folder has to announce itself
+ * somehow. The three options are a fixed list in code (which caps the library
+ * at whatever number somebody typed), probing upward until requests start
+ * failing (a burst of 404s on every load, and one gap in the numbering silently
+ * truncates the set), or a manifest.
+ *
+ * A manifest, generated from the folder at build time, is the only one of the
+ * three with no ceiling and no wasted requests. Adding an asset stays a matter
+ * of dropping the file in; the manifest catches up on the next build.
+ *
+ * Deliberately not a game concept: this returns names, and the caller decides
+ * that some of them are music.
+ */
+/** Every name in a manifest, or an empty list if there is not one. */
+export async function fetchAudioManifest(url, fetchImpl = (target) => fetch(target)) {
+    let parsed;
+    try {
+        const response = await fetchImpl(url);
+        if (!response.ok)
+            return [];
+        parsed = await response.json();
+    }
+    catch {
+        /*
+         * A missing or unreadable manifest is silence, never a failure. The whole
+         * asset system is built so a game runs with no files at all — a folder that
+         * has not been scanned yet must behave exactly like an empty one.
+         */
+        return [];
+    }
+    return parseAudioManifest(parsed);
+}
+/**
+ * Validate a manifest's contents.
+ *
+ * Separated from fetching so the rules can be tested without a network, and
+ * because the rules are the part that matters: a manifest is generated by a
+ * script, and a script that emits one bad entry must not take the rest of the
+ * library down with it.
+ */
+export function parseAudioManifest(value) {
+    if (!Array.isArray(value))
+        return [];
+    const names = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'string')
+            continue;
+        const name = entry.trim();
+        if (name.length === 0 || seen.has(name))
+            continue;
+        // A name is a slot, not a path. Anything with a separator or an extension
+        // in it is a generator bug, and following it would mean fetching whatever
+        // the manifest asked for from wherever it asked.
+        if (name.includes('/') || name.includes('\\') || name.includes('.'))
+            continue;
+        seen.add(name);
+        names.push(name);
+    }
+    /*
+     * Sorted, because the caller picks one by seed and that pick has to be the
+     * same everywhere. Directory order is filesystem order, which differs between
+     * machines — two players on the same day would get different music, and the
+     * daily would quietly stop being shared.
+     */
+    names.sort();
+    return names;
+}

package/dist/mix/bus.d.ts

@@ -0,0 +1,203 @@
+import type { ScheduleClock } from '../ambientLoop.ts';
+/**
+ * One bus: everything that reaches it, through whatever it inserts, at whatever level it is set to.
+ *
+ * Three nodes rather than one, and each earns its place:
+ *
+ * ```
+ *   input ─ [inserts] ─ tap ─ [post-send inserts] ─ output ─→ parent.input
+ *                        └─ send gain ─→ a return bus
+ * ```
+ *
+ * **`input` is the fader**, and it is at the *top* of the chain rather than the bottom. That is not
+ * a preference: it is what makes a send post-fader, and it is what the mix this replaces already
+ * did — the level sat ahead of the lift, and the sends hung off the lift. A fader at the bottom
+ * would leave every insert and every send working on unattenuated signal, so turning a bus down
+ * would leave its reverb at full strength.
+ *
+ * **`tap` is where sends listen from**, and it exists as a real node so that rewiring the chain
+ * cannot silently move what the sends hear. Inserts added normally land above it and are heard by
+ * the sends; an insert added `postSend` lands below it and is not. The slam is the reason that flag
+ * exists: `graph.ts` says the sends hang off the stage before it "so the reverb tail never hears
+ * the slam", because a six-second convolution of a clipped bass hit is a mess still arriving three
+ * gates later.
+ *
+ * **`output` is a unity sum**, for the reason `AudioGraph.out` gives: what a parent hears has to be
+ * a node and not an implicit sum at somebody else's input, or nothing can ever be inserted between
+ * a bus and its parent.
+ *
+ * Cost: two multiplications by unity per bus that a hand-wired graph would not have. Both are exact
+ * in floating point, so they cannot move a mix — measured, by the gate in `scripts/audio-baseline.mjs`,
+ * which is bit-exact and passes across this change. What would make this wrong is a tree deep
+ * enough for the node count itself to matter, which at the depth a game mixes at — a master, a few
+ * groups, their children — it is not.
+ */
+/**
+ * Smoothing for parameter moves, seconds.
+ *
+ * The same 0.08 the mix has always used, and it lives here now because a bus is where every level
+ * move goes. Long enough to never click; short enough that a fader feels immediate.
+ */
+export declare const RAMP = 0.08;
+/** A stage a bus can put in its own signal path. Internally it may be anything, including parallel. */
+export interface MixInsert {
+    readonly input: AudioNode;
+    readonly output: AudioNode;
+}
+export interface InsertOptions {
+    /**
+     * Place this insert *below* the send tap, so the sends do not hear it.
+     *
+     * Cost: an insert down here cannot be heard in a reverb tail even when a caller wants it to be.
+     * What would make this wrong is an insert that is a colour rather than an event — a bus-wide EQ
+     * belongs above the tap, because a reverb of an unequalised signal is a reverb of a different
+     * instrument.
+     */
+    readonly postSend?: boolean;
+}
+export interface BusOptions {
+    /**
+     * Where this bus sends its output. Omitted, the console parents it to `master`.
+     *
+     * **`null` means nowhere**, and the caller wires the output itself. That is not a hole in the
+     * model: a return bus joins the mix *downstream* of the master filter, so parenting one to master
+     * would put every reverb tail through a filter the dry signal has already been through. The mix
+     * this replaces has always done it that way, and `mixOutput.test.ts` exists because getting it
+     * wrong once meant every exported clip carried the dry track and nothing wet.
+     */
+    readonly parent?: MixBus | null;
+    /**
+     * Where the fader starts. Unity when omitted.
+     *
+     * Assigned rather than ramped, for the reason `AudioGraphOptions.levels` gives: a level that does
+     * not change for the whole of a render is not a move, it is where the parameter starts, and
+     * ramping it would open every rendered clip with a glide down from unity.
+     */
+    readonly level?: number;
+}
+export declare class MixBus {
+    readonly name: string;
+    private readonly context;
+    private readonly scheduleAt;
+    /** The fader. Sources and child buses connect here. */
+    readonly input: GainNode;
+    /** Where sends listen from. Unity, always. */
+    readonly tap: GainNode;
+    /** What the parent hears. Unity, always. */
+    readonly output: GainNode;
+    readonly parent: MixBus | null;
+    private readonly kids;
+    private readonly inserts;
+    /**
+     * Nodes fed from this bus's pre-insert signal, restored whenever the chain is rewired.
+     *
+     * For a stage that needs the bus as it arrives rather than as its own position in the chain would
+     * give it. The slam is the case: its wet path is tapped upstream of the lift's high-pass, because
+     * a low-cut ahead of the tap would make the effect vanish exactly when the player is in the air,
+     * which is where half of it is used. Registered rather than connected once, because `rebuild`
+     * disconnects `input` and would otherwise silently drop it the next time an insert is added.
+     */
+    private readonly inputTaps;
+    private readonly sends;
+    /**
+     * What each send was last asked for.
+     *
+     * Mirrored rather than read back off the parameter, for the reason `AudioGraph.mixLevels` gives:
+     * a send is ramped, and mid-ramp `gain.value` is somewhere between where it was and where it is
+     * going. A snapshot capturing sends would otherwise record whatever instant it happened to ask on.
+     */
+    private readonly sendAmounts;
+    private levelValue;
+    private mutedValue;
+    private soloedValue;
+    /**
+     * What solo has decided about this bus, from the console that can see the whole tree.
+     *
+     * A separate factor rather than a second write to the level, because a bus silenced by somebody
+     * else's solo must come back to the level its own fader is at, and a single value cannot remember
+     * two decisions.
+     */
+    private soloGateValue;
+    /**
+     * A temporary move over the top of the fader, without disturbing it.
+     *
+     * The distinction `AudioGraph.fadeMusic` and `AudioGraph.levels` spent two paragraphs on: a fade
+     * is part of an *edit* and has to end by returning to whatever the player chose, so it cannot be
+     * allowed to overwrite that choice. Here the choice stays in `levelValue` and the edit is a
+     * factor beside it, which means the value to come back to is `1` rather than something the caller
+     * has to have remembered.
+     */
+    private duckFactor;
+    constructor(name: string, context: BaseAudioContext, scheduleAt: ScheduleClock, options?: BusOptions);
+    get children(): readonly MixBus[];
+    get level(): number;
+    get muted(): boolean;
+    get soloed(): boolean;
+    /** Feed a node from this bus's signal as it arrives, before any insert. See `inputTaps`. */
+    feedFromInput(node: AudioNode): void;
+    /** Append a stage to this bus's own signal path. See `InsertOptions.postSend`. */
+    insert(insert: MixInsert, options?: InsertOptions): void;
+    /**
+     * Feed a return bus from this one, at `amount`.
+     *
+     * Idempotent per target: asking twice moves the existing send rather than building a second one,
+     * because this is called from per-frame code in every consumer that has ever used it and a send
+     * node per frame is a graph that grows until the page stops.
+     */
+    send(returnBus: MixBus, amount: number): void;
+    /** What this bus was last asked to send to that return, or 0 if it has never sent to it. */
+    sendAmount(returnBus: MixBus): number;
+    /** Every return this bus feeds, for a snapshot to capture. */
+    get sendTargets(): readonly MixBus[];
+    setLevel(level: number): void;
+    /**
+     * Move to a level over an explicit time, rather than at the fader's own smoothing.
+     *
+     * A fader is a control and wants to feel immediate; a snapshot recall is an edit and takes as
+     * long as it was asked to take. Both write the same mirrored level, so the mix knows where it is
+     * either way — which `AudioGraph.fadeMusic` deliberately does *not* do, because a fade there is
+     * part of an edit that has to return to the player's setting when it is over.
+     */
+    fadeLevel(level: number, seconds: number): void;
+    /**
+     * Move over the top of the fader and back, without moving the fader.
+     *
+     * `duck(0, 0.4)` takes this bus away over four tenths of a second; `duck(1, 0.4)` brings it back
+     * to exactly whatever the fader is set to, including a setting the player changed in between.
+     * Cost: this is a second thing multiplying into one parameter, so a caller that ducks and forgets
+     * to release leaves a bus quiet with a fader that says otherwise — which is why `duckedTo` is
+     * readable rather than private.
+     */
+    duck(factor: number, seconds: number): void;
+    /** What this bus is ducked to, 1 when it is not. See `duck`. */
+    get duckedTo(): number;
+    setMute(muted: boolean): void;
+    setSolo(soloed: boolean): void;
+    /** Set by the console when it adopts this bus, so a solo anywhere re-resolves the whole tree. */
+    onSoloChanged: (() => void) | null;
+    /** Written by the console alone. 1 is audible, 0 is silenced by somebody else's solo. */
+    setSoloGate(gate: number): void;
+    /**
+     * Level, mute and the solo gate are one number, written once.
+     *
+     * Three writers to one parameter race, and the loser is whichever ran first — which is heard as a
+     * fader that sometimes does not take, and is nearly impossible to reproduce deliberately.
+     */
+    private applyGain;
+    /**
+     * Rewire the series path.
+     *
+     * Only `input`, the insert outputs and `tap` are disconnected — never `output`, which carries this
+     * bus's connection to its parent and would take the whole subtree with it. The sends are
+     * reconnected here because `tap` was just disconnected, and a send silently dropped by a later
+     * insert is exactly the kind of fault that reads as "the reverb stopped working" days afterwards.
+     */
+    private rebuild;
+    /**
+     * Every parameter move is ramped and every one lands on the console's instant.
+     *
+     * `scheduleAt`, never `currentTime`: offline there is no now, and a move left to the clock lands
+     * on instant zero along with every other move a render ever makes.
+     */
+    private ramp;
+}