@aura3d/audio 1.0.6

package/src/SpatialAudioFixtures.ts

@@ -0,0 +1,137 @@
+export type AudioOcclusionLevel = "none" | "light" | "medium" | "heavy" | "complete";
+
+export interface AudioEnvironmentFixtureOptions {
+  readonly sourcePosition?: readonly [number, number, number];
+  readonly listenerPosition?: readonly [number, number, number];
+  readonly sourceVelocity?: readonly [number, number, number];
+  readonly listenerVelocity?: readonly [number, number, number];
+  readonly obstacleCount?: number;
+  readonly reverbZoneRadius?: number;
+  readonly reverbZoneDistance?: number;
+  readonly baseFrequencyHz?: number;
+}
+
+export interface AudioEnvironmentFixture {
+  readonly source: "origin-master-spatial-audio-environment-adapted";
+  readonly distance: number;
+  readonly occlusion: {
+    readonly level: AudioOcclusionLevel;
+    readonly obstacleCount: number;
+    readonly lowpassHz: number;
+    readonly volume: number;
+  };
+  readonly doppler: {
+    readonly relativeVelocity: number;
+    readonly approaching: boolean;
+    readonly pitchFactor: number;
+    readonly frequencyShiftHz: number;
+  };
+  readonly reverb: {
+    readonly zoneRadius: number;
+    readonly zoneDistance: number;
+    readonly blend: number;
+    readonly wetLevel: number;
+    readonly dryLevel: number;
+  };
+  readonly hash: string;
+  readonly claimBoundary: string;
+}
+
+const OCCLUSION: Record<AudioOcclusionLevel, { readonly lowpassHz: number; readonly volume: number }> = {
+  none: { lowpassHz: 20_000, volume: 1 },
+  light: { lowpassHz: 8_000, volume: 0.9 },
+  medium: { lowpassHz: 3_000, volume: 0.7 },
+  heavy: { lowpassHz: 800, volume: 0.4 },
+  complete: { lowpassHz: 200, volume: 0.1 }
+};
+
+export function sampleAudioEnvironmentFixture(options: AudioEnvironmentFixtureOptions = {}): AudioEnvironmentFixture {
+  const sourcePosition = options.sourcePosition ?? [0.85, 0.15, 0] as const;
+  const listenerPosition = options.listenerPosition ?? [0, 0, 3] as const;
+  const sourceVelocity = options.sourceVelocity ?? [-2.5, 0.2, 0] as const;
+  const listenerVelocity = options.listenerVelocity ?? [0.7, 0, 0] as const;
+  const obstacleCount = Math.max(0, Math.floor(options.obstacleCount ?? 2));
+  const distance = vectorLength(sub(sourcePosition, listenerPosition));
+  const direction = normalize(sub(listenerPosition, sourcePosition));
+  const relativeVelocity = dot(sub(sourceVelocity, listenerVelocity), direction);
+  const approaching = relativeVelocity > 0;
+  const speedOfSound = 343;
+  const pitchFactor = clamp(speedOfSound / Math.max(1, speedOfSound - relativeVelocity), 0.5, 2);
+  const baseFrequencyHz = options.baseFrequencyHz ?? 440;
+  const level = occlusionLevel(obstacleCount);
+  const occlusion = OCCLUSION[level];
+  const zoneRadius = Math.max(0.001, options.reverbZoneRadius ?? 8);
+  const zoneDistance = Math.max(0, options.reverbZoneDistance ?? distance);
+  const blend = clamp(1 - zoneDistance / zoneRadius, 0, 1);
+  const fixture = {
+    source: "origin-master-spatial-audio-environment-adapted" as const,
+    distance: round(distance),
+    occlusion: {
+      level,
+      obstacleCount,
+      lowpassHz: occlusion.lowpassHz,
+      volume: occlusion.volume
+    },
+    doppler: {
+      relativeVelocity: round(relativeVelocity),
+      approaching,
+      pitchFactor: round(pitchFactor),
+      frequencyShiftHz: round(baseFrequencyHz * (pitchFactor - 1))
+    },
+    reverb: {
+      zoneRadius: round(zoneRadius),
+      zoneDistance: round(zoneDistance),
+      blend: round(blend),
+      wetLevel: round(0.55 * blend),
+      dryLevel: round(0.85 * (1 - blend * 0.5))
+    },
+    hash: "",
+    claimBoundary: "Spatial audio environment fixture adapts old occlusion, doppler, and reverb-zone math for deterministic telemetry; it does not implement authored audio middleware or Unity/Unreal acoustic parity."
+  };
+  return {
+    ...fixture,
+    hash: stableHash(`${fixture.distance}|${fixture.occlusion.level}|${fixture.occlusion.obstacleCount}|${fixture.doppler.pitchFactor}|${fixture.reverb.blend}`)
+  };
+}
+
+function occlusionLevel(obstacleCount: number): AudioOcclusionLevel {
+  if (obstacleCount <= 0) return "none";
+  if (obstacleCount === 1) return "light";
+  if (obstacleCount === 2) return "medium";
+  if (obstacleCount === 3) return "heavy";
+  return "complete";
+}
+
+function sub(left: readonly [number, number, number], right: readonly [number, number, number]): [number, number, number] {
+  return [left[0] - right[0], left[1] - right[1], left[2] - right[2]];
+}
+
+function dot(left: readonly [number, number, number], right: readonly [number, number, number]): number {
+  return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
+}
+
+function normalize(value: readonly [number, number, number]): [number, number, number] {
+  const length = vectorLength(value);
+  return length > 0 ? [value[0] / length, value[1] / length, value[2] / length] : [0, 0, 0];
+}
+
+function vectorLength(value: readonly [number, number, number]): number {
+  return Math.hypot(value[0], value[1], value[2]);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, Number.isFinite(value) ? value : min));
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(4));
+}
+
+function stableHash(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}

package/src/effects/Filter.ts

@@ -0,0 +1,39 @@
+import type { AudioContextLike } from "../AudioContextManager";
+import type { AudioEffect } from "../AudioEffect";
+
+export class FilterEffect implements AudioEffect {
+  readonly input: BiquadFilterNode;
+  readonly output: BiquadFilterNode;
+
+  constructor(context: AudioContextLike, type: BiquadFilterType = "lowpass") {
+    this.input = context.createBiquadFilter();
+    this.input.type = type;
+    this.output = this.input;
+  }
+
+  setFrequency(value: number): void {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new Error("Filter frequency must be positive");
+    }
+    this.input.frequency.value = value;
+  }
+
+  setQ(value: number): void {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new Error("Filter Q must be non-negative");
+    }
+    this.input.Q.value = value;
+  }
+
+  connect(destination: AudioNode): AudioNode {
+    return this.output.connect(destination);
+  }
+
+  disconnect(): void {
+    this.output.disconnect();
+  }
+
+  dispose(): void {
+    this.disconnect();
+  }
+}

package/src/effects/Reverb.ts

@@ -0,0 +1,30 @@
+import type { AudioContextLike } from "../AudioContextManager";
+import type { AudioEffect } from "../AudioEffect";
+
+export class ReverbEffect implements AudioEffect {
+  readonly input: ConvolverNode;
+  readonly output: ConvolverNode;
+
+  constructor(context: AudioContextLike, impulse?: AudioBuffer) {
+    this.input = context.createConvolver();
+    this.input.buffer = impulse ?? null;
+    this.output = this.input;
+  }
+
+  setImpulse(buffer: AudioBuffer): void {
+    this.input.buffer = buffer;
+  }
+
+  connect(destination: AudioNode): AudioNode {
+    return this.output.connect(destination);
+  }
+
+  disconnect(): void {
+    this.output.disconnect();
+  }
+
+  dispose(): void {
+    this.input.buffer = null;
+    this.disconnect();
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export { AudioBus } from "./AudioBus";
+export { AudioClip } from "./AudioClip";
+export type { AudioClipOptions } from "./AudioClip";
+export { sampleAudioEffectsAnalysisFixture } from "./AudioEffectsAnalysisFixtures";
+export type {
+  AudioChorusPreset,
+  AudioCompressorPreset,
+  AudioDelayPreset,
+  AudioDistortionCurve,
+  AudioEffectsAnalysisFixture,
+  AudioEffectsAnalysisFixtureOptions,
+  AudioEqBandFixture,
+  AudioSpectrumBandFixture
+} from "./AudioEffectsAnalysisFixtures";
+export { sampleAdaptiveMusicFixture } from "./AdaptiveMusicFixtures";
+export type { AdaptiveMusicCrossfadeCurve, AdaptiveMusicFixture, AdaptiveMusicFixtureOptions, AdaptiveMusicFixtureState, AdaptiveMusicLayerMix } from "./AdaptiveMusicFixtures";
+export { sampleAudioEnvironmentFixture } from "./SpatialAudioFixtures";
+export type { AudioEnvironmentFixture, AudioEnvironmentFixtureOptions, AudioOcclusionLevel } from "./SpatialAudioFixtures";
+export { AudioContextManager } from "./AudioContextManager";
+export type { AudioContextLike, AudioContextManagerOptions, AudioContextState } from "./AudioContextManager";
+export type { AudioEffect } from "./AudioEffect";
+export { AudioListener } from "./AudioListener";
+export type { Vec3Like } from "./AudioListener";
+export { AudioMixer } from "./AudioMixer";
+export { AudioSource } from "./AudioSource";
+export type { AudioSourceOptions, AudioSourceState } from "./AudioSource";
+export { AudioSystem } from "./AudioSystem";
+export { SceneAudioBridge } from "./SceneAudioBridge";
+export type { SceneAudioSourceBinding } from "./SceneAudioBridge";
+export { SpatialAudio } from "./SpatialAudio";
+export type { SpatialAudioOptions } from "./SpatialAudio";
+export { FilterEffect } from "./effects/Filter";
+export { ReverbEffect } from "./effects/Reverb";

package/tests/audio.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Scene } from "@aura3d/scene";
+import { AudioClip, AudioContextManager, AudioListener, AudioSource, SceneAudioBridge } from "../src/index";
+
+class MockParam {
+  value = 0;
+}
+
+class MockNode {
+  connections: unknown[] = [];
+  connect(destination: unknown) {
+    this.connections.push(destination);
+    return destination;
+  }
+  disconnect() {
+    this.connections = [];
+  }
+}
+
+class MockGain extends MockNode {
+  gain = new MockParam();
+}
+
+class MockSource extends MockNode {
+  buffer: AudioBuffer | null = null;
+  loop = false;
+  onended: (() => void) | null = null;
+  started = false;
+  stopped = false;
+  start() {
+    this.started = true;
+  }
+  stop() {
+    this.stopped = true;
+  }
+}
+
+test("AudioContextManager unlocks, suspends, resumes, and disposes a mock context", async () => {
+  const context = {
+    state: "suspended",
+    destination: new MockNode() as unknown as AudioNode,
+    currentTime: 0,
+    async resume() {
+      this.state = "running";
+    },
+    async suspend() {
+      this.state = "suspended";
+    },
+    async close() {
+      this.state = "closed";
+    },
+    createGain: () => new MockGain() as unknown as GainNode,
+    createBufferSource: () => new MockSource() as unknown as AudioBufferSourceNode,
+    createPanner: () => new MockNode() as unknown as PannerNode,
+    createBiquadFilter: () => new MockNode() as unknown as BiquadFilterNode,
+    createConvolver: () => new MockNode() as unknown as ConvolverNode
+  };
+  const manager = new AudioContextManager({ context });
+
+  assert.equal(manager.state, "locked");
+  await manager.unlock();
+  assert.equal(manager.state, "running");
+  await manager.suspend();
+  assert.equal(manager.state, "suspended");
+  await manager.dispose();
+  assert.equal(manager.state, "closed");
+});
+
+test("AudioSource guards missing clip and tracks play/stop state", () => {
+  const sourceNode = new MockSource();
+  const context = {
+    state: "running",
+    destination: new MockNode() as unknown as AudioNode,
+    currentTime: 0,
+    resume: async () => {},
+    suspend: async () => {},
+    close: async () => {},
+    createGain: () => new MockGain() as unknown as GainNode,
+    createBufferSource: () => sourceNode as unknown as AudioBufferSourceNode,
+    createPanner: () => new MockNode() as unknown as PannerNode,
+    createBiquadFilter: () => new MockNode() as unknown as BiquadFilterNode,
+    createConvolver: () => new MockNode() as unknown as ConvolverNode
+  };
+  const source = new AudioSource({ context });
+  assert.throws(() => source.play(), /without an AudioClip/);
+
+  source.clip = new AudioClip({
+    buffer: { duration: 1, numberOfChannels: 1, sampleRate: 44100 } as AudioBuffer
+  });
+  source.play();
+  assert.equal(source.state, "playing");
+  assert.equal(sourceNode.started, true);
+  source.stop();
+  assert.equal(source.state, "stopped");
+});
+
+test("SceneAudioBridge syncs listener and spatial source positions from scene nodes", () => {
+  const scene = new Scene();
+  const listenerNode = scene.createNode("listener");
+  const sourceNode = scene.createNode("source");
+  scene.root.addChild(listenerNode);
+  scene.root.addChild(sourceNode);
+  listenerNode.transform.setPosition(1, 2, 3);
+  sourceNode.transform.setPosition(4, 5, 6);
+
+  const listener = new AudioListener();
+  const spatial = {
+    position: { x: 0, y: 0, z: 0 },
+    setPosition(position: { readonly x: number; readonly y: number; readonly z: number }) {
+      this.position = { ...position };
+    }
+  };
+  const bridge = new SceneAudioBridge(scene);
+  bridge.bindListener(listenerNode, listener);
+  bridge.bindSource(sourceNode, spatial as never);
+  bridge.update();
+
+  assert.deepEqual(listener.position, { x: 1, y: 2, z: 3 });
+  assert.deepEqual(spatial.position, { x: 4, y: 5, z: 6 });
+});

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}