@aura3d/audio 3.0.1 → 4.0.0

package/dist/game-sound/ReverbSend.js

@@ -0,0 +1,69 @@
+/**
+ * game-sound/ReverbSend.ts — §6.8 reverb send.
+ *
+ * One convolver send off the bus mix, tier-gated (off on `low`; IR length ≤
+ * the §17 budget: medium 0.8 s, high 1.5 s, ultra 2.5 s). Presets pick a
+ * bundled mono 24 kHz IR via the format probe. `underwater` adds a 1.8 kHz
+ * lowpass on the send path.
+ */
+export const IR_BUDGET_SECONDS = {
+    low: 0,
+    medium: 0.8,
+    high: 1.5,
+    ultra: 2.5
+};
+/** IR lengths shipped per preset (seconds, mono 24 kHz — from the pack manifest). */
+export const PRESET_IR_SECONDS = {
+    "small-room": 0.6,
+    hall: 1.8,
+    street: 1.2,
+    hangar: 2.2,
+    underwater: 1.4
+};
+export const presetIrUrl = (preset, extension) => preset === "none" ? undefined : `assets/ir/${preset}.${extension}`;
+export function createReverbSend(options) {
+    const { ctx, preset, tier } = options;
+    const budget = IR_BUDGET_SECONDS[tier];
+    if (preset === "none" || budget <= 0 || typeof ctx.createConvolver !== "function") {
+        return { enabled: false, irSeconds: 0, dispose() { } };
+    }
+    const irSeconds = Math.min(PRESET_IR_SECONDS[preset], budget);
+    const convolver = ctx.createConvolver();
+    const sendGain = ctx.createGain();
+    sendGain.gain.value = 0.25;
+    // Send input → convolver → (lowpass if underwater) → sendGain → caller's bus input.
+    let tail = convolver;
+    if (preset === "underwater" && typeof ctx.createBiquadFilter === "function") {
+        const lp = ctx.createBiquadFilter();
+        lp.type = "lowpass";
+        if (lp.frequency)
+            lp.frequency.value = 1800;
+        convolver.connect(lp);
+        lp.connect(sendGain);
+        tail = lp;
+    }
+    else {
+        convolver.connect(sendGain);
+    }
+    return {
+        enabled: true,
+        sendInput: convolver,
+        irSeconds,
+        /** The send tail connects to the master/bus input — set by the engine. */
+        ...{ sendTail: sendGain },
+        setIrBuffer(buffer) {
+            convolver.buffer = buffer;
+        },
+        dispose() {
+            for (const n of [convolver, tail, sendGain]) {
+                try {
+                    n.disconnect();
+                }
+                catch {
+                    /* noop */
+                }
+            }
+        }
+    };
+}
+//# sourceMappingURL=ReverbSend.js.map

package/dist/game-sound/ReverbSend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReverbSend.js","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/ReverbSend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,MAAM,CAAC,MAAM,iBAAiB,GAAgC;IAC5D,GAAG,EAAE,CAAC;IACN,MAAM,EAAE,GAAG;IACX,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;CACX,CAAC;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,iBAAiB,GAAkD;IAC9E,YAAY,EAAE,GAAG;IACjB,IAAI,EAAE,GAAG;IACT,MAAM,EAAE,GAAG;IACX,MAAM,EAAE,GAAG;IACX,UAAU,EAAE,GAAG;CAChB,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,MAAoB,EAAE,SAAiB,EAAsB,EAAE,CACzF,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,MAAM,IAAI,SAAS,EAAE,CAAC;AAiBrE,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,MAAM,IAAI,MAAM,IAAI,CAAC,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QAClF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,KAAI,CAAC,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAE9D,MAAM,SAAS,GAAG,GAAG,CAAC,eAAe,EAAgE,CAAC;IACtG,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,EAA8B,CAAC;IAC7D,QAAmD,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IAEvE,oFAAoF;IACpF,IAAI,IAAI,GAAkB,SAAS,CAAC;IACpC,IAAI,MAAM,KAAK,YAAY,IAAI,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU,EAAE,CAAC;QAC5E,MAAM,EAAE,GAAG,GAAG,CAAC,kBAAkB,EAAgC,CAAC;QAClE,EAAE,CAAC,IAAI,GAAG,SAAS,CAAC;QACpB,IAAI,EAAE,CAAC,SAAS;YAAE,EAAE,CAAC,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC;QAC3C,SAAoD,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjE,EAA6C,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACjE,IAAI,GAAG,EAAE,CAAC;IACZ,CAAC;SAAM,CAAC;QACL,SAAoD,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,SAAS;QACpB,SAAS;QACT,0EAA0E;QAC1E,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE;QACzB,WAAW,CAAC,MAAmB;YAC7B,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC;QAC5B,CAAC;QACD,OAAO;YACL,KAAK,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAC5C,IAAI,CAAC;oBACF,CAAmB,CAAC,UAAU,EAAE,CAAC;gBACpC,CAAC;gBAAC,MAAM,CAAC;oBACP,UAAU;gBACZ,CAAC;YACH,CAAC;QACH,CAAC;KAC6E,CAAC;AACnF,CAAC"}

package/dist/game-sound/SpatialVoice.d.ts

@@ -0,0 +1,30 @@
+/**
+ * game-sound/SpatialVoice.ts — §6.8 spatial voice node.
+ *
+ * Voice → PannerNode (HRTF on high/ultra, equalpower otherwise; inverse
+ * distance, refDistance 1, maxDistance 60, rolloff 1) → occlusion lowpass
+ * (BiquadFilterNode, 20 kHz open → 900 Hz occluded, exponential map) → cue
+ * gain → bus.
+ */
+import type { SoundBiquadLike, SoundGraphContext, SoundNodeLike, SoundPannerLike, Vec3 } from "./types.js";
+export interface SpatialNodeOptions {
+    readonly ctx: SoundGraphContext;
+    /** "hrtf" resolved by tier: high/ultra → "HRTF", else "equalpower". */
+    readonly panningModel: PanningModelType;
+    readonly refDistance?: number;
+    readonly maxDistance?: number;
+    readonly rolloff?: number;
+}
+export interface SpatialNode {
+    readonly input: SoundNodeLike;
+    readonly panner?: SoundPannerLike;
+    readonly occlusionFilter: SoundBiquadLike;
+    setPosition(p: Vec3): void;
+    setVelocity(v: Vec3): void;
+    /** 0 = open (20 kHz), 1 = fully occluded (900 Hz). */
+    setOcclusion(amount01: number): void;
+    dispose(): void;
+}
+export declare const occlusionHz: (amount01: number) => number;
+export declare function createSpatialNode(options: SpatialNodeOptions): SpatialNode;
+//# sourceMappingURL=SpatialVoice.d.ts.map

package/dist/game-sound/SpatialVoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpatialVoice.d.ts","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/SpatialVoice.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,IAAI,EACL,MAAM,SAAS,CAAC;AAGjB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,WAAW,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,KAAG,MACmC,CAAC;AAEnF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAuF1E"}

package/dist/game-sound/SpatialVoice.js

@@ -0,0 +1,115 @@
+/**
+ * game-sound/SpatialVoice.ts — §6.8 spatial voice node.
+ *
+ * Voice → PannerNode (HRTF on high/ultra, equalpower otherwise; inverse
+ * distance, refDistance 1, maxDistance 60, rolloff 1) → occlusion lowpass
+ * (BiquadFilterNode, 20 kHz open → 900 Hz occluded, exponential map) → cue
+ * gain → bus.
+ */
+import { clamp, vec3 } from "./types.js";
+// C-25 (#208): 20000·(1-occ)² + 400 Hz — fully occluded rolls off at 400 Hz.
+const OCCLUSION_OPEN_HZ = 20_000;
+const OCCLUSION_CLOSED_HZ = 400;
+export const occlusionHz = (amount01) => OCCLUSION_OPEN_HZ * Math.pow(1 - clamp(amount01, 0, 1), 2) + OCCLUSION_CLOSED_HZ;
+export function createSpatialNode(options) {
+    const { ctx } = options;
+    let panner;
+    if (typeof ctx.createPanner === "function") {
+        panner = ctx.createPanner();
+        if (panner) {
+            if ("panningModel" in panner)
+                panner.panningModel = options.panningModel;
+            if ("distanceModel" in panner)
+                panner.distanceModel = "inverse";
+            if ("refDistance" in panner)
+                panner.refDistance = options.refDistance ?? 1;
+            if ("maxDistance" in panner)
+                panner.maxDistance = options.maxDistance ?? 60;
+            if ("rolloffFactor" in panner)
+                panner.rolloffFactor = options.rolloff ?? 1;
+        }
+    }
+    // Fake/headless contexts may lack createBiquadFilter — the occlusion filter
+    // degrades to a passthrough gain (still positionable, just no lowpass).
+    const filter = (typeof ctx.createBiquadFilter === "function"
+        ? ctx.createBiquadFilter()
+        : ctx.createGain());
+    filter.type = "lowpass";
+    if (filter.frequency)
+        filter.frequency.value = OCCLUSION_OPEN_HZ;
+    if (filter.Q)
+        filter.Q.value = 0.707;
+    const input = panner ?? filter;
+    let occlusionSet = false;
+    if (panner) {
+        panner.connect(filter);
+    }
+    return {
+        input,
+        panner,
+        occlusionFilter: filter,
+        setPosition(p) {
+            if (!panner)
+                return;
+            const { x, y, z } = vec3(p);
+            const now = ctx.currentTime;
+            const px = panner.positionX;
+            const py = panner.positionY;
+            const pz = panner.positionZ;
+            if (px?.setTargetAtTime && py?.setTargetAtTime && pz?.setTargetAtTime) {
+                px.setTargetAtTime(x, now, 0.02);
+                py.setTargetAtTime(y, now, 0.02);
+                pz.setTargetAtTime(z, now, 0.02);
+            }
+            else if (panner.setPosition) {
+                panner.setPosition(x, y, z);
+            }
+            else {
+                if (panner.positionX)
+                    panner.positionX.value = x;
+                if (panner.positionY)
+                    panner.positionY.value = y;
+                if (panner.positionZ)
+                    panner.positionZ.value = z;
+            }
+        },
+        setVelocity(v) {
+            if (!panner?.setVelocity)
+                return;
+            const { x, y, z } = vec3(v);
+            panner.setVelocity(x, y, z);
+        },
+        setOcclusion(amount01) {
+            const hz = occlusionHz(amount01);
+            const f = filter.frequency;
+            if (!f)
+                return;
+            // The first call sets the voice's starting occlusion: apply it at once.
+            // Gliding from the open 20 kHz default let a voice spawned behind a wall
+            // play its first ~90 ms unfiltered (only 15 dB high-band cut measured
+            // instead of ≥ 18 dB). Later calls glide (τ 30 ms) to avoid zipper noise.
+            if (!occlusionSet) {
+                occlusionSet = true;
+                if (f.setValueAtTime)
+                    f.setValueAtTime(hz, ctx.currentTime);
+                f.value = hz;
+                return;
+            }
+            if (f.setTargetAtTime)
+                f.setTargetAtTime(hz, ctx.currentTime, 0.03);
+            else
+                f.value = hz;
+        },
+        dispose() {
+            for (const n of [panner, filter]) {
+                try {
+                    n?.disconnect();
+                }
+                catch {
+                    /* noop */
+                }
+            }
+        }
+    };
+}
+//# sourceMappingURL=SpatialVoice.js.map

package/dist/game-sound/SpatialVoice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpatialVoice.js","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/SpatialVoice.ts"],"names":[],"mappings":"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"}

package/dist/game-sound/Voice.d.ts

@@ -0,0 +1,139 @@
+/**
+ * game-sound/Voice.ts — voice pool per §6.8/§17.
+ *
+ * - Variant picks are round-robin-without-immediate-repeat (VariantPicker),
+ *   seeded from the session seed → deterministic captures.
+ * - Pitch jitter ±`pitchJitterSemitones` (default 0.6), gain jitter
+ *   ±`gainJitterDb` (default 1.5).
+ * - Per-cue `maxVoices` (default 4): oldest-playing voice of the same cue is
+ *   stolen. Per-cue `cooldownMs` (default 30): plays inside the window are
+ *   dropped and counted.
+ * - Global tier voice cap: when full, the lowest-priority oldest voice is
+ *   evicted — `ambient` first, then `normal`, never `critical`.
+ */
+import { type Rng } from "./rng.js";
+import type { SoundGraphContext, SoundNodeLike, SoundSourceLike } from "./types.js";
+export type VoicePriority = "critical" | "normal" | "ambient";
+export declare const PRIORITY_RANK: Record<VoicePriority, number>;
+export declare const priorityOf: (p: VoicePriority | number | undefined) => number;
+export interface VoiceCueSpec {
+    readonly asset?: {
+        readonly url: string;
+    } | readonly {
+        readonly url: string;
+    }[];
+    readonly bus: string;
+    readonly volumeDb?: number;
+    readonly pitchJitterSemitones?: number;
+    readonly gainJitterDb?: number;
+    readonly maxVoices?: number;
+    readonly cooldownMs?: number;
+    readonly loop?: boolean;
+    readonly priority?: VoicePriority | number;
+}
+export interface VoiceRecord {
+    readonly id: number;
+    readonly cueId: string;
+    readonly priority: number;
+    readonly startedAt: number;
+    readonly source: SoundSourceLike;
+    readonly gain: SoundNodeLike;
+    /** Linear voice gain after volume + jitter (the attack ramp's target). */
+    readonly targetGain: number;
+    loop: boolean;
+    ended: boolean;
+}
+export interface VoicePoolOptions {
+    readonly ctx: SoundGraphContext;
+    readonly rng: Rng;
+    /** Resolve an asset url to a decoded buffer (async load handled upstream). */
+    readonly bufferFor: (url: string) => AudioBuffer | undefined;
+    /** Now in ms — injected for tests. */
+    readonly now?: () => number;
+    /** Global cap per §17 tier. */
+    readonly voiceCap: number;
+}
+export interface VoiceAllocation {
+    readonly dropped: boolean;
+    readonly record?: VoiceRecord;
+    readonly stolen?: VoiceRecord;
+    readonly evicted?: VoiceRecord;
+}
+export declare class VoicePool {
+    private readonly o;
+    private readonly now;
+    private readonly live;
+    private readonly perCue;
+    private readonly pickers;
+    private readonly lastPlayAt;
+    private nextId;
+    private droppedByCooldown;
+    private stolenCount;
+    private evictedCount;
+    private playedCount;
+    constructor(o: VoicePoolOptions);
+    get liveCount(): number;
+    get stats(): {
+        played: number;
+        cooldownDrops: number;
+        stolen: number;
+        evicted: number;
+    };
+    /**
+     * Allocate a voice for `cueId`. Returns the record plus any steal/eviction
+     * performed; `dropped` means the cooldown rejected the play.
+     */
+    allocate(cueId: string, spec: VoiceCueSpec, destination: SoundNodeLike, opts?: {
+        volumeDb?: number;
+        rate?: number;
+        loop?: boolean;
+    }): VoiceAllocation;
+    /**
+     * Stop a voice. The gain ramps to 0 over RELEASE_S before the source stops
+     * (a hard stop mid-waveform clicks); nodes disconnect once it has ended.
+     */
+    release(record: VoiceRecord): void;
+    releaseAll(): void;
+    private pickerFor;
+}
+/** Voice attack (s): long enough to kill the onset click, short enough to keep transients. */
+export declare const ATTACK_S = 0.004;
+/** Voice release (s) on stop / steal / eviction. */
+export declare const RELEASE_S = 0.015;
+/** Low-pass corner for bright (noise/hiss) buffers. */
+export declare const HARSH_LOWPASS_HZ = 6500;
+export interface GainParamOwner {
+    readonly gain: {
+        value: number;
+        cancelScheduledValues?(t: number): void;
+        setValueAtTime?(v: number, t: number): void;
+        linearRampToValueAtTime?(v: number, t: number): void;
+    };
+}
+/** Ramp a fresh voice gain 0 → target over ATTACK_S (falls back to a direct set). */
+export declare function rampIn(node: GainParamOwner, target: number, now: number): void;
+/** Ramp a voice gain to 0 over RELEASE_S; returns the context time to stop the source at. */
+export declare function rampOut(node: GainParamOwner, now: number): number;
+type BufferLike = Pick<AudioBuffer, "length" | "sampleRate" | "numberOfChannels"> & {
+    getChannelData?(channel: number): Float32Array;
+};
+/**
+ * Brightness test on channel 0: the energy of the first difference relative to
+ * the signal energy. A sine at f gives (2·sin(πf/sr))²: ≈0.03 at 1 kHz, ≈0.32
+ * at 4 kHz, 2 for white noise. Above 0.6 most of the energy sits above ~5 kHz.
+ */
+export declare function brightnessRatio(buffer: BufferLike): number;
+export declare const HARSH_BRIGHTNESS = 0.6;
+export declare function isHarsh(buffer: AudioBuffer): boolean;
+/**
+ * Loop-seam repair. When |last − first| sample is far above the local step
+ * size the loop clicks every cycle. The repaired copy is N samples shorter:
+ * its first N samples crossfade (equal power) from the original tail into the
+ * original head, so the wrap from sample L−N−1 → 0 is continuous.
+ * Buffers that already loop cleanly are returned unchanged.
+ */
+export declare function seamlessLoopBuffer(ctx: {
+    createBuffer?(channels: number, length: number, sampleRate: number): AudioBuffer;
+}, buffer: AudioBuffer): AudioBuffer;
+export {};
+//# sourceMappingURL=Voice.d.ts.map

package/dist/game-sound/Voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Voice.d.ts","sourceRoot":"","sources":["../../../../../packages/audio/src/game-sound/Voice.ts"],"names":[],"mappings":"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"}