@driftengine/audio 3.61.0

package/dist/spatial/listener.js

@@ -0,0 +1,186 @@
+import { resolveZones } from './zones.js';
+/**
+ * The largest speed a listener is allowed to be moving, metres per second.
+ *
+ * Not a physical limit — it is a guard against a position that jumped. Roughly Mach 1, so anything
+ * a game moves a camera at is under it and a teleport that slipped past `warp` is clamped to
+ * something that merely sounds wrong rather than dividing by zero in the doppler ratio.
+ */
+const MAX_SPEED = 340;
+export class AudioListenerGraph {
+    mix;
+    /** Set by the consumer; called by whatever wants to know if something is in the way. */
+    probe = null;
+    posX = 0;
+    posY = 0;
+    posZ = 0;
+    velX = 0;
+    velY = 0;
+    velZ = 0;
+    placed = false;
+    elapsed = 0;
+    zones = [];
+    /**
+     * What each zone is being sent, owned here rather than read back off the send.
+     *
+     * Reused across frames rather than rebuilt: this is written every time the listener moves, and a
+     * map per frame is an allocation in a per-frame path.
+     */
+    zoneAmounts = new Map();
+    /** How many sources are placed against this listener, for spreading their probes apart. */
+    sourceCount = 0;
+    constructor(mix) {
+        this.mix = mix;
+    }
+    /** The mix this listener belongs to. A source needs it for a bus and for the context. */
+    get console() {
+        return this.mix;
+    }
+    /**
+     * Seconds of listener time, accumulated from the frame steps it is given.
+     *
+     * Accumulated rather than read off a clock, because nothing under this package may reach for
+     * `performance.now` on a path a consumer might simulate, and because an offline render has no
+     * wall time at all — a mix rendered faster than real time still has to stagger its probes the
+     * same way the live one does.
+     */
+    get elapsedSec() {
+        return this.elapsed;
+    }
+    /** Register a space this listener can be inside. See `addReverbZone`. */
+    addZone(zone) {
+        this.zones.push(zone);
+    }
+    /** What that zone is currently being sent, from where the listener is standing. */
+    zoneSend(zone) {
+        return this.zoneAmounts.get(zone) ?? 0;
+    }
+    /** Claim a probe slot. The index is what spreads one source's turn away from its neighbours'. */
+    claimProbeSlot() {
+        return this.sourceCount++;
+    }
+    get probeSlots() {
+        return this.sourceCount;
+    }
+    get x() {
+        return this.posX;
+    }
+    get y() {
+        return this.posY;
+    }
+    get z() {
+        return this.posZ;
+    }
+    get velocityX() {
+        return this.velX;
+    }
+    get velocityY() {
+        return this.velY;
+    }
+    get velocityZ() {
+        return this.velZ;
+    }
+    /**
+     * Place and point the listener for this frame.
+     *
+     * `yaw` 0 faces −Z and `pitch` is positive looking up, which is the convention every camera in
+     * this engine uses and the one `stereoPan` already documents. The two agree by construction here
+     * rather than by coincidence, so a source panned the cheap way and a source panned through a
+     * panner land on the same side of the head.
+     *
+     * **Velocity is derived rather than taken.** A caller passing both a position and a velocity can
+     * make them disagree, and doppler needs only the component along the line to a source. Cost: a
+     * position that jumps reads as enormous speed, which is what `warp` and `MAX_SPEED` are between.
+     */
+    set(x, y, z, yaw, pitch, dtSec) {
+        if (dtSec > 0)
+            this.elapsed += dtSec;
+        if (this.placed && dtSec > 0) {
+            this.velX = clampSpeed((x - this.posX) / dtSec);
+            this.velY = clampSpeed((y - this.posY) / dtSec);
+            this.velZ = clampSpeed((z - this.posZ) / dtSec);
+        }
+        this.posX = x;
+        this.posY = y;
+        this.posZ = z;
+        this.placed = true;
+        const cosPitch = Math.cos(pitch);
+        const forwardX = Math.sin(yaw) * cosPitch;
+        const forwardY = Math.sin(pitch);
+        const forwardZ = -Math.cos(yaw) * cosPitch;
+        const sinPitch = Math.sin(pitch);
+        const upX = -Math.sin(yaw) * sinPitch;
+        const upY = cosPitch;
+        const upZ = Math.cos(yaw) * sinPitch;
+        this.write(x, y, z, forwardX, forwardY, forwardZ, upX, upY, upZ);
+        if (this.zones.length > 0) {
+            resolveZones(this.zones, x, y, z, this.zoneAmounts);
+            for (const [zone, amount] of this.zoneAmounts)
+                zone.from.send(zone.bus, amount);
+        }
+    }
+    /**
+     * Move the listener without it having travelled.
+     *
+     * A teleport, a respawn, a camera cut. The next frame is measured from here, not from where the
+     * listener was, so nothing derives a speed from a jump that never happened.
+     */
+    warp(x, y, z) {
+        this.posX = x;
+        this.posY = y;
+        this.posZ = z;
+        this.velX = 0;
+        this.velY = 0;
+        this.velZ = 0;
+        this.placed = true;
+    }
+    /**
+     * Write the listener, through whichever surface this browser has.
+     *
+     * `positionX` and the parameters beside it are the modern form and can be ramped; `setPosition`
+     * and `setOrientation` are deprecated and step. Both are present in Chromium here, measured
+     * 2026-08-24; **WebKit is the reason the second branch exists and it cannot be verified from this
+     * machine.** Cost: on the legacy path a fast listener steps rather than glides, which is audible
+     * as a faint zipper on a hard turn. What would make this wrong is WebKit gaining the parameters,
+     * at which point the branch is dead code and should be deleted rather than kept for symmetry.
+     *
+     * Values are assigned rather than ramped even on the modern path. A ramp per component per frame
+     * is nine scheduled events sixty times a second for a value that is already being sampled every
+     * block, and the smoothing that matters — the one a listener can hear — is the panner's own
+     * interpolation between blocks.
+     */
+    write(x, y, z, fx, fy, fz, ux, uy, uz) {
+        const listener = this.mix.context.listener;
+        if (listener === undefined || listener === null)
+            return;
+        const modern = listener;
+        if (modern.positionX !== undefined && modern.forwardX !== undefined) {
+            setValue(modern.positionX, x);
+            setValue(modern.positionY, y);
+            setValue(modern.positionZ, z);
+            setValue(modern.forwardX, fx);
+            setValue(modern.forwardY, fy);
+            setValue(modern.forwardZ, fz);
+            setValue(modern.upX, ux);
+            setValue(modern.upY, uy);
+            setValue(modern.upZ, uz);
+            return;
+        }
+        const legacy = listener;
+        legacy.setPosition?.(x, y, z);
+        legacy.setOrientation?.(fx, fy, fz, ux, uy, uz);
+    }
+}
+function setValue(param, value) {
+    if (param !== undefined)
+        param.value = value;
+}
+function clampSpeed(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.min(Math.max(value, -MAX_SPEED), MAX_SPEED);
+}
+/** The listener for a console. One per mix; everything placed in the world reads it. */
+export function createListener(mix) {
+    return new AudioListenerGraph(mix);
+}

package/dist/spatial/occlusion.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a wall does to a sound, and how often it is worth asking whether there is one.
+ *
+ * **The engine owns the curve and the consumer owns the number.** How blocked a path is depends on
+ * a world this package has never seen; what blocking *sounds* like does not. So a consumer answers
+ * "how much wall" and everything below decides what that means.
+ */
+/** Geometric, for the reason `liftFrequencyHz` gives. Open above hearing, shut at 500 Hz. */
+export declare function occlusionCutoffHz(amount: number): number;
+/** Level for a given occlusion. 1 clear, `SHUT_GAIN` solid, linear between. */
+export declare function occlusionGainFor(amount: number): number;
+/**
+ * Exponential approach, in time.
+ *
+ * `rate` is per second and means the same thing at 60 Hz, at 144 Hz and at whatever a background
+ * tab does. A per-step factor is the bug `AGENTS.md` records: the same constant meant 47 ms in one
+ * caller and 158 ms in another, and moved with the frame rate in the second.
+ */
+export declare function smoothToward(current: number, target: number, rate: number, dtSec: number): number;
+/**
+ * When a source is allowed to ask the world whether something is in the way.
+ *
+ * A segment test per source per frame is the most expensive thing occlusion can do, and it is paid
+ * by the consumer's own collision code — which is exactly why the throttling lives here rather
+ * than being left for them to discover. Each source is probed once per period, and the phase is
+ * spread across its index, so twenty sources are twenty single tests rather than one spike.
+ *
+ * Cost: a wall that appears between a source and the listener takes up to one period to be heard,
+ * and the smoothing above adds its own approach on top of that. At the default that is well under
+ * the time a player takes to walk through a doorway. What would make this wrong is a source moving
+ * faster than the period — a projectile — which should be probed every frame and say so.
+ */
+export declare class ProbeScheduler {
+    private readonly periodSec;
+    private lastAt;
+    constructor(periodSec?: number);
+    due(index: number, count: number, nowSec: number): boolean;
+    forget(index: number): void;
+}

package/dist/spatial/occlusion.js

@@ -0,0 +1,92 @@
+/**
+ * What a wall does to a sound, and how often it is worth asking whether there is one.
+ *
+ * **The engine owns the curve and the consumer owns the number.** How blocked a path is depends on
+ * a world this package has never seen; what blocking *sounds* like does not. So a consumer answers
+ * "how much wall" and everything below decides what that means.
+ */
+/** Wide open: above hearing, so an unoccluded source is not filtered at all. */
+const OPEN_HZ = 20000;
+/**
+ * Shut: 500 Hz.
+ *
+ * Low enough that consonants and the top of anything percussive are gone, which is what makes a
+ * sound read as being *through* something. Not lower: below about 300 Hz a voice stops sounding
+ * muffled and starts sounding like a different sound in a different place.
+ */
+const SHUT_HZ = 500;
+/**
+ * How far a fully blocked source drops, as a gain.
+ *
+ * About twelve decibels. **Not zero, and that is the decision here.** A source that goes silent
+ * behind a wall pops out of existence, and a player learns that walls delete sounds rather than
+ * muffle them — which is worse than no occlusion at all, because it removes the information that
+ * the thing is still there. Cost: a source behind a wall is never *gone*, so a consumer wanting
+ * something genuinely inaudible has to stop it rather than occlude it. What would make this wrong
+ * is a game where hearing through a wall is a mechanic to be denied, which is a design decision
+ * rather than an acoustic one.
+ */
+const SHUT_GAIN = 0.25;
+/** Geometric, for the reason `liftFrequencyHz` gives. Open above hearing, shut at 500 Hz. */
+export function occlusionCutoffHz(amount) {
+    const t = clamp01(amount);
+    return OPEN_HZ * (SHUT_HZ / OPEN_HZ) ** t;
+}
+/** Level for a given occlusion. 1 clear, `SHUT_GAIN` solid, linear between. */
+export function occlusionGainFor(amount) {
+    return 1 - (1 - SHUT_GAIN) * clamp01(amount);
+}
+/**
+ * Exponential approach, in time.
+ *
+ * `rate` is per second and means the same thing at 60 Hz, at 144 Hz and at whatever a background
+ * tab does. A per-step factor is the bug `AGENTS.md` records: the same constant meant 47 ms in one
+ * caller and 158 ms in another, and moved with the frame rate in the second.
+ */
+export function smoothToward(current, target, rate, dtSec) {
+    if (!(dtSec > 0))
+        return current;
+    return current + (target - current) * (1 - Math.exp(-rate * dtSec));
+}
+/**
+ * When a source is allowed to ask the world whether something is in the way.
+ *
+ * A segment test per source per frame is the most expensive thing occlusion can do, and it is paid
+ * by the consumer's own collision code — which is exactly why the throttling lives here rather
+ * than being left for them to discover. Each source is probed once per period, and the phase is
+ * spread across its index, so twenty sources are twenty single tests rather than one spike.
+ *
+ * Cost: a wall that appears between a source and the listener takes up to one period to be heard,
+ * and the smoothing above adds its own approach on top of that. At the default that is well under
+ * the time a player takes to walk through a doorway. What would make this wrong is a source moving
+ * faster than the period — a projectile — which should be probed every frame and say so.
+ */
+export class ProbeScheduler {
+    periodSec;
+    lastAt = new Map();
+    constructor(periodSec = 0.2) {
+        this.periodSec = periodSec;
+    }
+    due(index, count, nowSec) {
+        const spread = count > 0 ? (index / count) * this.periodSec : 0;
+        const last = this.lastAt.get(index);
+        if (last === undefined) {
+            // The first turn is taken at this source's own phase, not immediately, or every source
+            // created in one frame probes in that frame and the stagger never starts.
+            if (nowSec < spread)
+                return false;
+            this.lastAt.set(index, nowSec);
+            return true;
+        }
+        if (nowSec - last < this.periodSec)
+            return false;
+        this.lastAt.set(index, nowSec);
+        return true;
+    }
+    forget(index) {
+        this.lastAt.delete(index);
+    }
+}
+function clamp01(value) {
+    return Number.isFinite(value) ? Math.min(Math.max(value, 0), 1) : 0;
+}

package/dist/spatial/source.d.ts

@@ -0,0 +1,185 @@
+import type { MixBus } from '../mix/bus.ts';
+import type { AudioListenerGraph } from './listener.ts';
+import { type ReverbZone } from './zones.ts';
+/**
+ * A sound placed in the world, heard from where the listener is standing.
+ *
+ * ```
+ *   buffer source ─ detune ─→ occlusion lowpass ─→ occlusion gain ─→ panner (HRTF) ─→ a bus
+ * ```
+ *
+ * **A function rather than a method on the console, and that is a size decision rather than a
+ * style one.** A method would be a static reference from the mix to the panner, which no bundler
+ * can shake out, so every consumer that imports the mix would carry the HRTF machinery whether or
+ * not it ever places a sound. `scripts/size-gate.test.mjs` publishes what each package costs and
+ * promises you pay only for what you import; this is what keeps that true.
+ *
+ * **This is the expensive path and it is meant to be.** `distanceGain` and `stereoPan` still exist
+ * and are still right for a fire, a shoreline or a storm column — diffuse things where what a
+ * player reads is "how close" and "which way". Reach for a panner when the *direction* is
+ * information: a footstep behind you, a voice through a doorway, something you are meant to turn
+ * towards.
+ */
+export interface SpatialOptions {
+    /** Where this lands in the mix. The console's `effects` bus when omitted. */
+    readonly bus?: MixBus;
+    readonly loop?: boolean;
+    /**
+     * Shift the pitch with relative motion.
+     *
+     * **Off by default, deliberately.** On a looping bed — a fire, a waterfall — a listener walking
+     * past makes the bed's pitch wander, which reads as the sound being broken rather than as motion.
+     * Turn it on for something that genuinely passes: a vehicle, a projectile, a siren.
+     */
+    readonly doppler?: boolean;
+    /** Metres per second. 343 in air; a game whose world is not in metres will want its own. */
+    readonly speedOfSound?: number;
+    /** How far the pitch is allowed to move, in cents. A whole tone each way by default. */
+    readonly maxDopplerCents?: number;
+    /** Distance-model parameters, passed to the panner unchanged. */
+    readonly refDistance?: number;
+    readonly maxDistance?: number;
+    readonly rolloff?: number;
+    /**
+     * How fast occlusion follows the world, per second.
+     *
+     * Slow enough that a probe landing on a different answer does not click, fast enough that walking
+     * through a doorway is heard as walking through a doorway.
+     */
+    readonly occlusionRate?: number;
+}
+export declare class SpatialSource {
+    private readonly listener;
+    private readonly options;
+    private readonly node;
+    private readonly filter;
+    private readonly gain;
+    private readonly panner;
+    private readonly probes;
+    private readonly slot;
+    private posX;
+    private posY;
+    private posZ;
+    private velX;
+    private velY;
+    private velZ;
+    private placed;
+    private occlusionTarget;
+    private occlusionNow;
+    private cents;
+    private started;
+    private stopped;
+    /**
+     * The zones this source carries the tail of, from its own position.
+     *
+     * An array rather than a map, because it is walked every frame and never looked up by key — the
+     * budget below caps it at a handful, and `resolveZones`'s own reason for a two-slot scan over a
+     * sort applies here one level down.
+     */
+    private readonly zoneSends;
+    constructor(listener: AudioListenerGraph, buffer: AudioBuffer, options?: SpatialOptions);
+    /** Where this source's dry signal lands, which is what decides whether a zone would double. */
+    private readonly bus;
+    /**
+     * Carry the tail of a space this **source** is in, rather than one the listener is in.
+     *
+     * The case `zones.ts` names as the one its own model cannot serve: a sound inside a cave heard
+     * from outside carries whatever space the *listener* stands in, which is wrong exactly when
+     * somebody is listening *into* a space. A source-attached zone is a second **routing** into a
+     * return that already carries a convolver, so it costs one `GainNode` rather than one convolution.
+     *
+     * **`MAX_OPEN_ZONES` still binds, and it binds per source.** The budget is not about the sends,
+     * which are nearly free; it is about how many convolvers are audible at once, and a source driving
+     * four returns makes four of them audible. Two is the space being left and the space being
+     * entered, here as for the listener.
+     *
+     * The send is taken from the **occluded, unpanned** signal: a reverb send comes off the channel on
+     * any console, and the return is itself a stereo space, so a point-panned tail would arrive from
+     * the source's direction rather than from the room. Occlusion is upstream because a sound behind a
+     * wall has a muffled tail too.
+     */
+    attachZone(zone: ReverbZone): void;
+    /** What this source is currently sending into that zone's return. */
+    zoneSend(zone: ReverbZone): number;
+    /** The pitch shift currently applied, in cents. Zero with doppler off. */
+    get detuneCents(): number;
+    /** How blocked this source is right now, after smoothing. */
+    get occlusion(): number;
+    /**
+     * Where this source is, this frame.
+     *
+     * Velocity is derived here exactly as the listener derives its own, and for the same reason. A
+     * source that teleports should be moved with `warp`.
+     */
+    place(x: number, y: number, z: number, dtSec: number): void;
+    /** Move without having travelled: a respawn, a cut, an object put back at the start. */
+    warp(x: number, y: number, z: number): void;
+    /**
+     * Say how blocked this source is, 0 clear to 1 solid.
+     *
+     * For a consumer that already knows — a door with a state, a sound that is definitionally
+     * indoors — and for anyone who would rather not hand the listener a probe. Overrides whatever the
+     * probe last answered until the probe answers again.
+     */
+    setOcclusion(amount: number): void;
+    start(when?: number): void;
+    stop(): void;
+    /**
+     * Which of this source's zones sound, from where the source is standing.
+     *
+     * The same two-slot scan `resolveZones` makes for the listener, written out here rather than
+     * shared because the listener's version fills a `Map` keyed by zone and this one walks an array
+     * of sends — the ranking is six lines and a shared version taking both shapes would be longer
+     * than either. What would make that wrong is a third caller.
+     *
+     * **Two slots is `MAX_OPEN_ZONES`**, written out rather than looped because two is what a
+     * crossfade needs. `sourceZone.test.ts` asserts the constant is still two, so raising it fails
+     * there and sends whoever raised it to read this.
+     */
+    private updateZones;
+    dispose(): void;
+    /**
+     * Where the panner thinks this source is, through whichever surface the browser has.
+     *
+     * The same pair as the listener's, for the same reason and with the same cost: the deprecated
+     * setter steps where the parameters can glide. Assigned rather than ramped on both paths, because
+     * this is written every frame and the interpolation that matters is the panner's own, between
+     * render blocks.
+     */
+    private writePosition;
+    /**
+     * The doppler ratio, and why it is ours to compute.
+     *
+     * `PannerNode` carried `dopplerFactor` and `speedOfSound` and the specification removed both, so
+     * there is nothing to configure and nothing to fall back to: the shift is arithmetic on two
+     * velocities projected onto the line between the two objects.
+     *
+     * With `d` the unit vector from listener to source, the ratio is
+     * `(c + vListener·d) / (c + vSource·d)` — a listener closing on a source raises the numerator, a
+     * source closing on the listener lowers the denominator, and both raise the pitch.
+     *
+     * Clamped in cents rather than in ratio, because cents are what a listener hears: a whole tone
+     * each way is a strong, obviously-moving effect and anything past it stops reading as motion.
+     * Cost: a deliberately supersonic source stops shifting at the clamp instead of doing something
+     * dramatic. What would make this wrong is a game whose subject *is* the sonic boom, which wants a
+     * different model rather than a wider clamp.
+     */
+    private updateDoppler;
+    /**
+     * Apply the shift, through `detune` where the browser has it and `playbackRate` where it does not.
+     *
+     * `detune` is in cents, which is the unit the arithmetic above produces and the unit a musician
+     * would state it in. `playbackRate` is the ratio, and it is the older surface: converting back is
+     * exact, so the fallback is a different spelling rather than a different effect.
+     */
+    private writeDetune;
+    /**
+     * Ask the world whether something is in the way, at most once per period, then approach it.
+     *
+     * The probe is the consumer's own collision code and is the expensive part; the smoothing is what
+     * keeps a probe that lands on a different answer from clicking.
+     */
+    private updateOcclusion;
+}
+/** Place a sound in the world. See `SpatialSource` for when this is the right tool and when it is not. */
+export declare function createSpatialSource(listener: AudioListenerGraph, buffer: AudioBuffer, options?: SpatialOptions): SpatialSource;