@aura3d/audio 1.4.0 → 1.4.2

package/src/AudioFileManager.ts

@@ -1,252 +0,0 @@
-import { AudioClip } from "./AudioClip";
-import type { AudioContextLike } from "./AudioContextManager";
-
-export interface AudioDecodeContextLike extends AudioContextLike {
-  decodeAudioData(data: ArrayBuffer): Promise<AudioBuffer> | AudioBuffer;
-}
-
-export interface AudioFileAssetLike {
-  readonly kind?: string;
-  readonly id?: string;
-  readonly type?: string;
-  readonly format?: string;
-  readonly url: string;
-  readonly hash?: string;
-  readonly sizeBytes?: number;
-  readonly license?: string;
-}
-
-export type AudioFileInput = string | URL | AudioFileAssetLike | AudioClip;
-
-export interface AudioFileRequest {
-  readonly input: AudioFileInput;
-  readonly signal?: AbortSignal;
-  readonly cacheKey?: string;
-  readonly name?: string;
-}
-
-export interface AudioFileManagerOptions {
-  readonly context: AudioDecodeContextLike;
-  readonly fetch?: (url: string, init?: { readonly signal?: AbortSignal }) => Promise<AudioFileFetchResponseLike>;
-  readonly cache?: Map<string, AudioClip>;
-  readonly validateTypedAudioAssets?: boolean;
-}
-
-export interface AudioFileFetchResponseLike {
-  readonly ok: boolean;
-  readonly status: number;
-  arrayBuffer(): Promise<ArrayBuffer>;
-}
-
-export interface ResolvedAudioFileRequest {
-  readonly url: string;
-  readonly cacheKey: string;
-  readonly name?: string;
-  readonly asset?: AudioFileAssetLike;
-}
-
-export interface EpisodeAudioAssetRequirement {
-  readonly id: string;
-  readonly role?: "dialogue" | "music" | "sfx" | "ambient";
-  readonly required?: boolean;
-  readonly requireLicense?: boolean;
-}
-
-export interface EpisodeAudioAssetDiagnostic {
-  readonly severity: "error" | "warning";
-  readonly code: string;
-  readonly message: string;
-  readonly assetId: string;
-}
-
-export interface EpisodeAudioAssetReadiness {
-  readonly ok: boolean;
-  readonly requiredCount: number;
-  readonly readyCount: number;
-  readonly missingAssetIds: readonly string[];
-  readonly diagnostics: readonly EpisodeAudioAssetDiagnostic[];
-}
-
-export class AudioFileManager {
-  private readonly cache: Map<string, AudioClip>;
-  private readonly inflight = new Map<string, Promise<AudioClip>>();
-
-  constructor(private readonly options: AudioFileManagerOptions) {
-    this.cache = options.cache ?? new Map();
-  }
-
-  resolve(input: AudioFileInput, request: Omit<AudioFileRequest, "input"> = {}): ResolvedAudioFileRequest {
-    if (input instanceof AudioClip) {
-      const name = request.name ?? input.name;
-      return {
-        url: name ? `clip:${name}` : "clip:anonymous",
-        cacheKey: request.cacheKey ?? (name ? `clip:${name}` : "clip:anonymous"),
-        ...(name ? { name } : {})
-      };
-    }
-
-    if (input instanceof URL) {
-      const url = input.toString();
-      return { url, cacheKey: request.cacheKey ?? url, ...(request.name ? { name: request.name } : {}) };
-    }
-
-    if (typeof input === "string") {
-      const url = input.trim();
-      if (!url) {
-        throw new Error("Audio file URL must be a non-empty string");
-      }
-      return { url, cacheKey: request.cacheKey ?? url, ...(request.name ? { name: request.name } : {}) };
-    }
-
-    if (this.options.validateTypedAudioAssets !== false && input.kind === "aura-asset-ref" && input.type !== "audio") {
-      throw new Error(`Typed asset "${input.id ?? input.url}" is not an audio asset`);
-    }
-    const url = input.url.trim();
-    if (!url) {
-      throw new Error(`Audio asset "${input.id ?? "unknown"}" is missing a URL`);
-    }
-    const cacheKey = request.cacheKey ?? input.id ?? url;
-    return {
-      url,
-      cacheKey,
-      name: request.name ?? input.id,
-      asset: input
-    };
-  }
-
-  has(input: AudioFileInput, request: Omit<AudioFileRequest, "input"> = {}): boolean {
-    return this.cache.has(this.resolve(input, request).cacheKey);
-  }
-
-  getCached(input: AudioFileInput, request: Omit<AudioFileRequest, "input"> = {}): AudioClip | undefined {
-    return this.cache.get(this.resolve(input, request).cacheKey);
-  }
-
-  async load(input: AudioFileInput, request: Omit<AudioFileRequest, "input"> = {}): Promise<AudioClip> {
-    if (input instanceof AudioClip) {
-      const resolved = this.resolve(input, request);
-      this.cache.set(resolved.cacheKey, input);
-      return input;
-    }
-
-    const resolved = this.resolve(input, request);
-    const cached = this.cache.get(resolved.cacheKey);
-    if (cached) return cached;
-
-    const pending = this.inflight.get(resolved.cacheKey);
-    if (pending) return pending;
-
-    const promise = this.loadResolved(resolved, request.signal);
-    this.inflight.set(resolved.cacheKey, promise);
-    try {
-      const clip = await promise;
-      this.cache.set(resolved.cacheKey, clip);
-      return clip;
-    } finally {
-      this.inflight.delete(resolved.cacheKey);
-    }
-  }
-
-  async loadMany(inputs: readonly AudioFileInput[], request: Omit<AudioFileRequest, "input"> = {}): Promise<readonly AudioClip[]> {
-    return Promise.all(inputs.map((input) => this.load(input, request)));
-  }
-
-  clear(input?: AudioFileInput): void {
-    if (input === undefined) {
-      this.cache.clear();
-      this.inflight.clear();
-      return;
-    }
-    const { cacheKey } = this.resolve(input);
-    this.cache.delete(cacheKey);
-    this.inflight.delete(cacheKey);
-  }
-
-  private async loadResolved(resolved: ResolvedAudioFileRequest, signal?: AbortSignal): Promise<AudioClip> {
-    const fetchAudio = this.options.fetch ?? defaultFetchAudio;
-    const response = await fetchAudio(resolved.url, { signal });
-    if (!response.ok) {
-      throw new Error(`Audio request failed with ${response.status}: ${resolved.url}`);
-    }
-
-    const encoded = await response.arrayBuffer();
-    const decoded = await this.options.context.decodeAudioData(encoded.slice(0));
-    return new AudioClip({
-      name: resolved.name ?? resolved.cacheKey,
-      buffer: decoded
-    });
-  }
-}
-
-export function validateEpisodeAudioAssets(
-  assets: readonly AudioFileAssetLike[],
-  requirements: readonly EpisodeAudioAssetRequirement[],
-  options: { readonly requireLicense?: boolean } = {}
-): EpisodeAudioAssetReadiness {
-  const byId = new Map(assets.filter((asset) => asset.id).map((asset) => [asset.id!, asset]));
-  const diagnostics: EpisodeAudioAssetDiagnostic[] = [];
-  const missingAssetIds: string[] = [];
-  let requiredCount = 0;
-  let readyCount = 0;
-
-  for (const requirement of requirements) {
-    const required = requirement.required ?? true;
-    if (required) requiredCount++;
-    const asset = byId.get(requirement.id);
-    if (!asset) {
-      if (required) {
-        missingAssetIds.push(requirement.id);
-        diagnostics.push({
-          severity: "error",
-          code: "audio-asset-missing",
-          assetId: requirement.id,
-          message: `Required ${requirement.role ?? "audio"} asset "${requirement.id}" is missing.`
-        });
-      }
-      continue;
-    }
-    if (asset.kind === "aura-asset-ref" && asset.type !== "audio") {
-      diagnostics.push({
-        severity: "error",
-        code: "audio-asset-wrong-type",
-        assetId: requirement.id,
-        message: `Typed asset "${requirement.id}" is "${asset.type ?? "unknown"}", not audio.`
-      });
-      continue;
-    }
-    if (!asset.url.trim()) {
-      diagnostics.push({
-        severity: "error",
-        code: "audio-asset-missing-url",
-        assetId: requirement.id,
-        message: `Audio asset "${requirement.id}" is missing a URL.`
-      });
-      continue;
-    }
-    if ((options.requireLicense || requirement.requireLicense) && !asset.license) {
-      diagnostics.push({
-        severity: "error",
-        code: "audio-asset-missing-license",
-        assetId: requirement.id,
-        message: `Audio asset "${requirement.id}" is missing license metadata.`
-      });
-      continue;
-    }
-    readyCount++;
-  }
-
-  return {
-    ok: diagnostics.every((diagnostic) => diagnostic.severity !== "error"),
-    requiredCount,
-    readyCount,
-    missingAssetIds,
-    diagnostics
-  };
-}
-
-async function defaultFetchAudio(url: string, init?: { readonly signal?: AbortSignal }): Promise<AudioFileFetchResponseLike> {
-  if (typeof fetch !== "function") {
-    throw new Error("AudioFileManager requires fetch or a custom fetch implementation");
-  }
-  return fetch(url, init);
-}

package/src/AudioListener.ts

@@ -1,17 +0,0 @@
-export interface Vec3Like {
-  readonly x: number;
-  readonly y: number;
-  readonly z: number;
-}
-
-export class AudioListener {
-  position: Vec3Like = { x: 0, y: 0, z: 0 };
-  forward: Vec3Like = { x: 0, y: 0, z: -1 };
-  up: Vec3Like = { x: 0, y: 1, z: 0 };
-
-  setTransform(position: Vec3Like, forward: Vec3Like = this.forward, up: Vec3Like = this.up): void {
-    this.position = { ...position };
-    this.forward = { ...forward };
-    this.up = { ...up };
-  }
-}

package/src/AudioMixer.ts

@@ -1,123 +0,0 @@
-import { AudioBus } from "./AudioBus";
-import type { AudioContextLike } from "./AudioContextManager";
-
-export class AudioMixer {
-  readonly master: AudioBus;
-  private readonly buses = new Map<string, AudioBus>();
-
-  constructor(private readonly context: AudioContextLike) {
-    this.master = new AudioBus("master", context);
-    this.buses.set(this.master.name, this.master);
-  }
-
-  createBus(name: string, destination: AudioNode = this.master.input): AudioBus {
-    if (this.buses.has(name)) {
-      throw new Error(`Audio bus already exists: ${name}`);
-    }
-    const bus = new AudioBus(name, this.context, destination);
-    this.buses.set(name, bus);
-    return bus;
-  }
-
-  getBus(name: string): AudioBus {
-    const bus = this.buses.get(name);
-    if (!bus) {
-      throw new Error(`Unknown audio bus: ${name}`);
-    }
-    return bus;
-  }
-
-  hasBus(name: string): boolean {
-    return this.buses.has(name);
-  }
-
-  listBuses(): readonly AudioBus[] {
-    return [...this.buses.values()];
-  }
-
-  evidence(options: { readonly unlocked?: boolean; readonly errors?: readonly string[] } = {}): AudioMixerEvidence {
-    return createAudioMixerEvidence(this, options);
-  }
-
-  dispose(): void {
-    for (const bus of [...this.buses.values()].reverse()) {
-      bus.dispose();
-    }
-    this.buses.clear();
-  }
-}
-
-export interface AudioMixerBusEvidence {
-  readonly name: string;
-  readonly volume: number;
-  readonly muted: boolean;
-}
-
-export interface AudioMixerEvidence {
-  readonly kind: "audio-mixer-evidence";
-  readonly unlocked: boolean;
-  readonly busCount: number;
-  readonly buses: readonly AudioMixerBusEvidence[];
-  readonly errors: readonly string[];
-}
-
-export interface AnimationAudioMixer {
-  readonly mixer: AudioMixer;
-  readonly buses: {
-    readonly voice: AudioBus;
-    readonly music: AudioBus;
-    readonly sfx: AudioBus;
-    readonly ambient: AudioBus;
-  };
-  evidence(options?: { readonly unlocked?: boolean; readonly errors?: readonly string[] }): AudioMixerEvidence;
-}
-
-export interface AnimationAudioMixerOptions {
-  readonly voiceVolume?: number;
-  readonly musicVolume?: number;
-  readonly sfxVolume?: number;
-  readonly ambientVolume?: number;
-  readonly muted?: boolean;
-}
-
-export function createAnimationAudioMixer(
-  context: AudioContextLike,
-  options: AnimationAudioMixerOptions = {}
-): AnimationAudioMixer {
-  const mixer = new AudioMixer(context);
-  const voice = mixer.createBus("voice");
-  const music = mixer.createBus("music");
-  const sfx = mixer.createBus("sfx");
-  const ambient = mixer.createBus("ambient");
-  voice.setVolume(options.voiceVolume ?? 1);
-  music.setVolume(options.musicVolume ?? 0.55);
-  sfx.setVolume(options.sfxVolume ?? 0.9);
-  ambient.setVolume(options.ambientVolume ?? 0.45);
-  if (options.muted) {
-    for (const bus of [mixer.master, voice, music, sfx, ambient]) {
-      bus.mute(true);
-    }
-  }
-  return {
-    mixer,
-    buses: { voice, music, sfx, ambient },
-    evidence: (evidenceOptions = {}) => mixer.evidence(evidenceOptions)
-  };
-}
-
-export function createAudioMixerEvidence(
-  mixer: AudioMixer,
-  options: { readonly unlocked?: boolean; readonly errors?: readonly string[] } = {}
-): AudioMixerEvidence {
-  return {
-    kind: "audio-mixer-evidence",
-    unlocked: options.unlocked ?? false,
-    busCount: mixer.listBuses().length,
-    buses: mixer.listBuses().map((bus) => ({
-      name: bus.name,
-      volume: bus.volume,
-      muted: bus.isMuted
-    })),
-    errors: [...(options.errors ?? [])]
-  };
-}

package/src/AudioSource.ts

@@ -1,75 +0,0 @@
-import type { AudioClip } from "./AudioClip";
-import type { AudioContextLike } from "./AudioContextManager";
-
-export type AudioSourceState = "idle" | "playing" | "paused" | "stopped";
-
-export interface AudioSourceOptions {
-  readonly context: AudioContextLike;
-  readonly destination?: AudioNode;
-  readonly clip?: AudioClip;
-  readonly loop?: boolean;
-  readonly volume?: number;
-}
-
-export class AudioSource {
-  clip?: AudioClip;
-  loop: boolean;
-  readonly gain: GainNode;
-
-  private stateRef: AudioSourceState = "idle";
-  private node?: AudioBufferSourceNode;
-
-  constructor(private readonly options: AudioSourceOptions) {
-    this.clip = options.clip;
-    this.loop = options.loop ?? false;
-    this.gain = options.context.createGain();
-    this.gain.gain.value = options.volume ?? 1;
-    this.gain.connect(options.destination ?? options.context.destination);
-  }
-
-  get state(): AudioSourceState {
-    return this.stateRef;
-  }
-
-  play(when = 0): void {
-    if (!this.clip) {
-      throw new Error("Cannot play an AudioSource without an AudioClip");
-    }
-    this.stop();
-    const source = this.options.context.createBufferSource();
-    source.buffer = this.clip.buffer;
-    source.loop = this.loop;
-    source.connect(this.gain);
-    source.start(when);
-    source.onended = () => {
-      if (this.node === source && this.stateRef === "playing") {
-        this.stateRef = "stopped";
-      }
-    };
-    this.node = source;
-    this.stateRef = "playing";
-  }
-
-  stop(when = 0): void {
-    if (this.node) {
-      this.node.stop(when);
-      this.node.disconnect();
-      this.node = undefined;
-    }
-    if (this.stateRef !== "idle") {
-      this.stateRef = "stopped";
-    }
-  }
-
-  setVolume(value: number): void {
-    if (!Number.isFinite(value) || value < 0) {
-      throw new Error("Audio source volume must be a non-negative finite number");
-    }
-    this.gain.gain.value = value;
-  }
-
-  dispose(): void {
-    this.stop();
-    this.gain.disconnect();
-  }
-}

package/src/AudioSystem.ts

@@ -1,34 +0,0 @@
-import { AudioContextManager, type AudioContextManagerOptions } from "./AudioContextManager";
-import { AudioMixer } from "./AudioMixer";
-
-export class AudioSystem {
-  readonly contextManager: AudioContextManager;
-  private mixerRef?: AudioMixer;
-
-  constructor(options: AudioContextManagerOptions = {}) {
-    this.contextManager = new AudioContextManager(options);
-  }
-
-  get mixer(): AudioMixer {
-    this.mixerRef ??= new AudioMixer(this.contextManager.context);
-    return this.mixerRef;
-  }
-
-  async unlock(): Promise<void> {
-    await this.contextManager.unlock();
-  }
-
-  async suspend(): Promise<void> {
-    await this.contextManager.suspend();
-  }
-
-  async resume(): Promise<void> {
-    await this.contextManager.resume();
-  }
-
-  async dispose(): Promise<void> {
-    this.mixerRef?.dispose();
-    this.mixerRef = undefined;
-    await this.contextManager.dispose();
-  }
-}