@aura3d/audio 1.0.6 → 1.1.0

package/dist/index.js

@@ -1,11 +1,14 @@
 export { AudioBus } from "./AudioBus.js";
 export { AudioClip } from "./AudioClip.js";
+export { AudioFileManager, validateEpisodeAudioAssets } from "./AudioFileManager.js";
+export { createAudioTimelineMixSnapshot, defaultAudioTimelineBusForRole, validateAudioCaptionSync, AudioTimelineTrack } from "./AudioTimelineTrack.js";
+export { audioWaveformPeakRange, createAudioWaveform, createAudioWaveformPath, createAudioWaveformReviewData, sampleAudioWaveformAtTime } from "./AudioWaveform.js";
 export { sampleAudioEffectsAnalysisFixture } from "./AudioEffectsAnalysisFixtures.js";
 export { sampleAdaptiveMusicFixture } from "./AdaptiveMusicFixtures.js";
 export { sampleAudioEnvironmentFixture } from "./SpatialAudioFixtures.js";
 export { AudioContextManager } from "./AudioContextManager.js";
 export { AudioListener } from "./AudioListener.js";
-export { AudioMixer } from "./AudioMixer.js";
+export { AudioMixer, createAudioMixerEvidence, createCartoonAudioMixer } from "./AudioMixer.js";
 export { AudioSource } from "./AudioSource.js";
 export { AudioSystem } from "./AudioSystem.js";
 export { SceneAudioBridge } from "./SceneAudioBridge.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/audio/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AAWnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/audio/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAalF,OAAO,EAAE,8BAA8B,EAAE,8BAA8B,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAepJ,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAYjK,OAAO,EAAE,iCAAiC,EAAE,MAAM,gCAAgC,CAAC;AAWnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAErE,OAAO,EAAE,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAAE,UAAU,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAE7F,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aura3d/audio",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,6 +11,6 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@aura3d/scene": "1.0.6"
+    "@aura3d/scene": "1.1.0"
   }
 }

package/src/AudioBus.ts

@@ -17,6 +17,14 @@ export class AudioBus {
     this.output.connect(destination ?? context.destination);
   }
 
+  get volume(): number {
+    return this.storedVolume;
+  }
+
+  get isMuted(): boolean {
+    return this.muted;
+  }
+
   setVolume(value: number): void {
     if (!Number.isFinite(value) || value < 0) {
       throw new Error("Audio bus volume must be a non-negative finite number");

package/src/AudioFileManager.ts

@@ -0,0 +1,252 @@
+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/AudioMixer.ts

@@ -27,6 +27,18 @@ export class AudioMixer {
     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();
@@ -34,3 +46,78 @@ export class AudioMixer {
     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 CartoonAudioMixer {
+  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 CartoonAudioMixerOptions {
+  readonly voiceVolume?: number;
+  readonly musicVolume?: number;
+  readonly sfxVolume?: number;
+  readonly ambientVolume?: number;
+  readonly muted?: boolean;
+}
+
+export function createCartoonAudioMixer(
+  context: AudioContextLike,
+  options: CartoonAudioMixerOptions = {}
+): CartoonAudioMixer {
+  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 ?? [])]
+  };
+}