@aura3d/audio 1.4.0 → 1.4.2

package/src/AudioWaveform.ts

@@ -1,226 +0,0 @@
-import type { AudioClip } from "./AudioClip";
-
-export interface AudioWaveformOptions {
-  readonly peakCount?: number;
-  readonly samplesPerPeak?: number;
-  readonly channel?: number | "mix";
-  readonly normalize?: boolean;
-}
-
-export interface AudioWaveformPeak {
-  readonly min: number;
-  readonly max: number;
-  readonly rms: number;
-}
-
-export interface AudioWaveformData {
-  readonly duration: number;
-  readonly sampleRate: number;
-  readonly channels: number;
-  readonly peakCount: number;
-  readonly samplesPerPeak: number;
-  readonly normalized: boolean;
-  readonly peaks: readonly AudioWaveformPeak[];
-}
-
-export interface AudioWaveformPathPoint {
-  readonly x: number;
-  readonly yMin: number;
-  readonly yMax: number;
-  readonly rmsHeight: number;
-}
-
-export interface AudioWaveformPathOptions {
-  readonly width: number;
-  readonly height: number;
-  readonly padding?: number;
-}
-
-export interface AudioWaveformReviewStem {
-  readonly id: string;
-  readonly label?: string;
-  readonly startTime: number;
-  readonly waveform: AudioWaveformData;
-}
-
-export interface AudioWaveformReviewStemView {
-  readonly id: string;
-  readonly label: string;
-  readonly startTime: number;
-  readonly duration: number;
-  readonly peakCount: number;
-  readonly path: readonly AudioWaveformPathPoint[];
-}
-
-export interface AudioWaveformReviewData {
-  readonly kind: "audio-waveform-review-data";
-  readonly stemCount: number;
-  readonly width: number;
-  readonly height: number;
-  readonly stems: readonly AudioWaveformReviewStemView[];
-}
-
-export type AudioWaveformInput = AudioBuffer | AudioClip;
-
-export function createAudioWaveform(input: AudioWaveformInput, options: AudioWaveformOptions = {}): AudioWaveformData {
-  const buffer = audioBufferFromInput(input);
-  const channels = buffer.numberOfChannels;
-  const sampleRate = finitePositive(buffer.sampleRate, "sampleRate");
-  const duration = Math.max(0, buffer.duration);
-  const totalSamples = Math.max(0, Math.round(duration * sampleRate));
-  const samplesPerPeak = resolveSamplesPerPeak(totalSamples, options);
-  const peakCount = totalSamples === 0 ? 0 : Math.ceil(totalSamples / samplesPerPeak);
-  const peaks: AudioWaveformPeak[] = [];
-  const sourceChannels = collectWaveformChannels(buffer, options.channel ?? "mix");
-
-  for (let peakIndex = 0; peakIndex < peakCount; peakIndex++) {
-    const start = peakIndex * samplesPerPeak;
-    const end = Math.min(totalSamples, start + samplesPerPeak);
-    let min = 0;
-    let max = 0;
-    let sumSquares = 0;
-    let sampleCount = 0;
-
-    for (let sampleIndex = start; sampleIndex < end; sampleIndex++) {
-      let value = 0;
-      for (const channel of sourceChannels) {
-        value += channel[sampleIndex] ?? 0;
-      }
-      value /= sourceChannels.length;
-      min = Math.min(min, value);
-      max = Math.max(max, value);
-      sumSquares += value * value;
-      sampleCount++;
-    }
-
-    peaks.push({
-      min,
-      max,
-      rms: sampleCount === 0 ? 0 : Math.sqrt(sumSquares / sampleCount)
-    });
-  }
-
-  const normalize = options.normalize ?? false;
-  const outputPeaks = normalize ? normalizePeaks(peaks) : peaks;
-  return {
-    duration,
-    sampleRate,
-    channels,
-    peakCount: outputPeaks.length,
-    samplesPerPeak,
-    normalized: normalize,
-    peaks: outputPeaks
-  };
-}
-
-export function sampleAudioWaveformAtTime(waveform: AudioWaveformData, timeSeconds: number): AudioWaveformPeak {
-  if (waveform.peaks.length === 0 || waveform.duration <= 0) {
-    return { min: 0, max: 0, rms: 0 };
-  }
-  const normalizedTime = clamp(timeSeconds / waveform.duration, 0, 1);
-  const index = Math.min(waveform.peaks.length - 1, Math.floor(normalizedTime * waveform.peaks.length));
-  return waveform.peaks[index] ?? { min: 0, max: 0, rms: 0 };
-}
-
-export function createAudioWaveformPath(waveform: AudioWaveformData, options: AudioWaveformPathOptions): readonly AudioWaveformPathPoint[] {
-  const width = finitePositive(options.width, "width");
-  const height = finitePositive(options.height, "height");
-  const padding = Math.max(0, options.padding ?? 0);
-  const drawableHeight = Math.max(1, height - padding * 2);
-  const centerY = padding + drawableHeight / 2;
-  const halfHeight = drawableHeight / 2;
-  const denominator = Math.max(1, waveform.peaks.length - 1);
-
-  return waveform.peaks.map((peak, index) => ({
-    x: waveform.peaks.length === 1 ? width / 2 : index / denominator * width,
-    yMin: centerY - clamp(peak.max, -1, 1) * halfHeight,
-    yMax: centerY - clamp(peak.min, -1, 1) * halfHeight,
-    rmsHeight: clamp(peak.rms, 0, 1) * halfHeight
-  }));
-}
-
-export function createAudioWaveformReviewData(
-  stems: readonly AudioWaveformReviewStem[],
-  options: AudioWaveformPathOptions
-): AudioWaveformReviewData {
-  const width = finitePositive(options.width, "width");
-  const height = finitePositive(options.height, "height");
-  return {
-    kind: "audio-waveform-review-data",
-    stemCount: stems.length,
-    width,
-    height,
-    stems: stems.map((stem) => ({
-      id: stem.id,
-      label: stem.label ?? stem.id,
-      startTime: Math.max(0, stem.startTime),
-      duration: stem.waveform.duration,
-      peakCount: stem.waveform.peakCount,
-      path: createAudioWaveformPath(stem.waveform, { ...options, width, height })
-    }))
-  };
-}
-
-export function audioWaveformPeakRange(waveform: AudioWaveformData): { readonly min: number; readonly max: number; readonly rmsMax: number } {
-  let min = 0;
-  let max = 0;
-  let rmsMax = 0;
-  for (const peak of waveform.peaks) {
-    min = Math.min(min, peak.min);
-    max = Math.max(max, peak.max);
-    rmsMax = Math.max(rmsMax, peak.rms);
-  }
-  return { min, max, rmsMax };
-}
-
-function audioBufferFromInput(input: AudioWaveformInput): AudioBuffer {
-  return "buffer" in input ? input.buffer : input;
-}
-
-function resolveSamplesPerPeak(totalSamples: number, options: AudioWaveformOptions): number {
-  if (options.samplesPerPeak !== undefined) {
-    return Math.max(1, Math.floor(finitePositive(options.samplesPerPeak, "samplesPerPeak")));
-  }
-  if (options.peakCount !== undefined) {
-    const peakCount = Math.max(1, Math.floor(finitePositive(options.peakCount, "peakCount")));
-    return Math.max(1, Math.ceil(totalSamples / peakCount));
-  }
-  return Math.max(1, Math.ceil(totalSamples / 1024));
-}
-
-function collectWaveformChannels(buffer: AudioBuffer, channel: number | "mix"): readonly Float32Array[] {
-  if (buffer.numberOfChannels <= 0) {
-    throw new Error("Audio waveform requires at least one channel");
-  }
-  if (channel === "mix") {
-    return Array.from({ length: buffer.numberOfChannels }, (_, index) => buffer.getChannelData(index));
-  }
-  if (!Number.isInteger(channel) || channel < 0 || channel >= buffer.numberOfChannels) {
-    throw new Error(`Audio waveform channel ${channel} is outside the buffer channel range`);
-  }
-  return [buffer.getChannelData(channel)];
-}
-
-function normalizePeaks(peaks: readonly AudioWaveformPeak[]): readonly AudioWaveformPeak[] {
-  let maxAbs = 0;
-  for (const peak of peaks) {
-    maxAbs = Math.max(maxAbs, Math.abs(peak.min), Math.abs(peak.max), peak.rms);
-  }
-  if (maxAbs <= 0) return peaks;
-  return peaks.map((peak) => ({
-    min: peak.min / maxAbs,
-    max: peak.max / maxAbs,
-    rms: peak.rms / maxAbs
-  }));
-}
-
-function finitePositive(value: number, label: string): number {
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new Error(`Audio waveform ${label} must be a positive finite number`);
-  }
-  return value;
-}
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}

package/src/SceneAudioBridge.ts

@@ -1,49 +0,0 @@
-import type { Scene, SceneNode } from "@aura3d/scene";
-import type { AudioListener } from "./AudioListener";
-import type { SpatialAudio } from "./SpatialAudio";
-
-export interface SceneAudioSourceBinding {
-  readonly node: SceneNode;
-  readonly spatial: SpatialAudio;
-}
-
-export class SceneAudioBridge {
-  private listenerBinding?: { readonly node: SceneNode; readonly listener: AudioListener };
-  private readonly sources = new Set<SceneAudioSourceBinding>();
-
-  constructor(private readonly scene?: Scene) {}
-
-  bindListener(node: SceneNode, listener: AudioListener): void {
-    this.listenerBinding = { node, listener };
-  }
-
-  unbindListener(): void {
-    this.listenerBinding = undefined;
-  }
-
-  bindSource(node: SceneNode, spatial: SpatialAudio): SceneAudioSourceBinding {
-    const binding = { node, spatial };
-    this.sources.add(binding);
-    return binding;
-  }
-
-  unbindSource(binding: SceneAudioSourceBinding): void {
-    this.sources.delete(binding);
-  }
-
-  update(): void {
-    this.scene?.updateWorldTransforms();
-    if (this.listenerBinding) {
-      this.listenerBinding.listener.setTransform(worldPosition(this.listenerBinding.node));
-    }
-    for (const binding of this.sources) {
-      binding.spatial.setPosition(worldPosition(binding.node));
-    }
-  }
-}
-
-function worldPosition(node: SceneNode): { readonly x: number; readonly y: number; readonly z: number } {
-  node.updateWorldTransform();
-  const matrix = node.transform.worldMatrix as readonly number[];
-  return { x: matrix[12], y: matrix[13], z: matrix[14] };
-}

package/src/SpatialAudio.ts

@@ -1,36 +0,0 @@
-import type { AudioContextLike } from "./AudioContextManager";
-import type { Vec3Like } from "./AudioListener";
-
-export interface SpatialAudioOptions {
-  readonly context: AudioContextLike;
-  readonly destination?: AudioNode;
-  readonly position?: Vec3Like;
-  readonly maxDistance?: number;
-  readonly refDistance?: number;
-  readonly rolloffFactor?: number;
-}
-
-export class SpatialAudio {
-  readonly panner: PannerNode;
-
-  constructor(options: SpatialAudioOptions) {
-    this.panner = options.context.createPanner();
-    this.panner.panningModel = "HRTF";
-    this.panner.distanceModel = "inverse";
-    this.panner.maxDistance = options.maxDistance ?? 10_000;
-    this.panner.refDistance = options.refDistance ?? 1;
-    this.panner.rolloffFactor = options.rolloffFactor ?? 1;
-    this.panner.connect(options.destination ?? options.context.destination);
-    this.setPosition(options.position ?? { x: 0, y: 0, z: 0 });
-  }
-
-  setPosition(position: Vec3Like): void {
-    this.panner.positionX.value = position.x;
-    this.panner.positionY.value = position.y;
-    this.panner.positionZ.value = position.z;
-  }
-
-  dispose(): void {
-    this.panner.disconnect();
-  }
-}

package/src/SpatialAudioFixtures.ts

@@ -1,137 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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

@@ -1,30 +0,0 @@
-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

@@ -1,74 +0,0 @@
-export { AudioBus } from "./AudioBus";
-export { AudioClip } from "./AudioClip";
-export type { AudioClipOptions } from "./AudioClip";
-export { AudioFileManager, validateEpisodeAudioAssets } from "./AudioFileManager";
-export type {
-  AudioDecodeContextLike,
-  EpisodeAudioAssetDiagnostic,
-  EpisodeAudioAssetReadiness,
-  EpisodeAudioAssetRequirement,
-  AudioFileAssetLike,
-  AudioFileFetchResponseLike,
-  AudioFileInput,
-  AudioFileManagerOptions,
-  AudioFileRequest,
-  ResolvedAudioFileRequest
-} from "./AudioFileManager";
-export { createAudioTimelineMixSnapshot, defaultAudioTimelineBusForRole, validateAudioCaptionSync, AudioTimelineTrack } from "./AudioTimelineTrack";
-export type {
-  AudioCaptionCue,
-  AudioCaptionSyncIssue,
-  AudioCaptionSyncReport,
-  AudioTimelineBusMix,
-  AudioTimelineClip,
-  AudioTimelineClipOptions,
-  AudioTimelineEnvelopePoint,
-  AudioTimelineMixOptions,
-  AudioTimelineMixSnapshot,
-  AudioTimelineSample,
-  AudioTimelineTrackOptions,
-  AudioTimelineTrackRole
-} from "./AudioTimelineTrack";
-export { audioWaveformPeakRange, createAudioWaveform, createAudioWaveformPath, createAudioWaveformReviewData, sampleAudioWaveformAtTime } from "./AudioWaveform";
-export type {
-  AudioWaveformData,
-  AudioWaveformInput,
-  AudioWaveformOptions,
-  AudioWaveformPathOptions,
-  AudioWaveformPathPoint,
-  AudioWaveformPeak,
-  AudioWaveformReviewData,
-  AudioWaveformReviewStem,
-  AudioWaveformReviewStemView
-} from "./AudioWaveform";
-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, createAudioMixerEvidence, createAnimationAudioMixer } from "./AudioMixer";
-export type { AudioMixerBusEvidence, AudioMixerEvidence, AnimationAudioMixer, AnimationAudioMixerOptions } 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";