@forgeax/engine-audio-webaudio 0.0.0-dev.8d955ade1c79

package/src/audio-importer.ts

@@ -0,0 +1,149 @@
+// audio-importer.ts - the build-time audioImporter (feat-20260603-asset-import-loader-injection M3 / w25).
+//
+// The `{ key: 'audio', import }` Importer the @forgeax/engine-import runner
+// dispatches a `*.meta.json` with `importer: 'audio'` to.
+//
+// SEMANTIC HETEROGENEITY (plan-strategy D-3 / requirements AC-18 callout):
+// audio is NOT like image / gltf. There is no JS decoder to strip out of the
+// runtime bundle -- the runtime decodes audio with the native Web Audio
+// `AudioContext.decodeAudioData` (clip-loader.ts), and the browser owns codec
+// selection (wav / mp3 / ogg / flac). So this importer is NOT a bundle
+// optimization: AC-16's bundle-delta evidence is image-only and does NOT
+// apply to audio. The audioImporter's value is the UNIFIED IMPORT ENTRY -- it
+// lets an audio source flow through the same declare -> import -> load
+// pipeline (meta.importer='audio') as every other asset family, so an AI user
+// reads one consistent import surface instead of an audio special case.
+//
+// The importer body MUST NOT call `AudioContext` / `decodeAudioData`: decode is
+// the runtime loader's job (clip-loader.ts, which fetches the source URL and
+// decodes in the browser). A decoded `AudioClipAsset` carries an `AudioBuffer`,
+// a runtime-only Web Audio object that cannot be produced at build time. The
+// importer therefore emits a thin pass-through descriptor (`kind: 'audio'` +
+// the source path) under the meta-declared GUID; the runtime resolves it to a
+// decoded clip at load time.
+//
+// GUID import-stable iron law: every produced GUID comes from `ctx.subAssets[]`.
+
+import {
+  IMPORT_ERROR_HINTS,
+  type ImportContext,
+  ImportError,
+  type ImportedAsset,
+  type Importer,
+  type ImportResult,
+} from '@forgeax/engine-types';
+
+/** Audio output identity is semantic and independent of source path/index. */
+export function sourceKeyForAudioOutput(kind = 'audio'): string | undefined {
+  const normalizedKind = kind.trim();
+  return normalizedKind.length === 0 ? undefined : `audio:${normalizedKind}`;
+}
+
+function audioMediaType(source: string): string {
+  const lower = source.toLowerCase();
+  if (lower.endsWith('.wav')) return 'audio/wav';
+  if (lower.endsWith('.mp3')) return 'audio/mpeg';
+  if (lower.endsWith('.ogg')) return 'audio/ogg';
+  if (lower.endsWith('.flac')) return 'audio/flac';
+  return 'application/octet-stream';
+}
+
+function validateAudioOutputTopology(ctx: ImportContext): ImportError | undefined {
+  if (ctx.subAssets.length === 1 && ctx.subAssets[0]?.kind === 'audio') return undefined;
+
+  const actual =
+    ctx.subAssets.length === 0
+      ? 'subAssets[] is empty'
+      : ctx.subAssets.map((sub, index) => `subAssets[${index}]=${sub.kind}:${sub.guid}`).join(', ');
+
+  return new ImportError({
+    code: 'source-validation-failed',
+    expected: 'exactly one subAssets[] entry with kind "audio"',
+    actual,
+    hint: IMPORT_ERROR_HINTS['source-validation-failed'],
+    detail: {
+      diagnostics: [
+        {
+          code: 'audio-subasset-topology',
+          severity: 'error',
+          sourcePath: `${ctx.source}#subAssets`,
+          sourceRange: { start: 0, end: 0, line: 1, column: 1 },
+          rule: 'audio-required-single-output',
+          expected: 'exactly one subAssets[] entry with kind "audio"',
+          actual,
+          hint: 'declare exactly one audio sub-asset and remove foreign or duplicate entries',
+        },
+      ],
+    },
+  });
+}
+
+async function importAudio(ctx: ImportContext): Promise<ImportResult> {
+  const topologyError = validateAudioOutputTopology(ctx);
+  if (topologyError !== undefined) return { ok: false, error: topologyError };
+
+  // Probe the source is readable so a missing file fails the build (the runner
+  // already probes, but this keeps the importer self-validating, P3). No decode
+  // happens here -- decodeAudioData is the runtime loader's job.
+  const read = await ctx.readSource();
+  if (!read.ok) {
+    return {
+      ok: false,
+      error: new ImportError({
+        code: 'source-read-failed',
+        expected: `readable source file at meta.source "${ctx.source}"`,
+        hint: IMPORT_ERROR_HINTS['source-read-failed'],
+        detail: {
+          source: ctx.source,
+          reason: read.error instanceof Error ? read.error.message : String(read.error),
+        },
+      }),
+    };
+  }
+
+  const out: ImportedAsset[] = [];
+  for (const sub of ctx.subAssets) {
+    if (sub.kind !== 'audio') continue;
+    // Thin pass-through descriptor: the runtime audio loader fetches the source
+    // URL and decodes via the browser, so the build-time payload carries only
+    // the source reference (no AudioBuffer; cast through the Asset slot like the
+    // other importers' build-time POD-vs-runtime-handle bridges).
+    const payload = {
+      kind: 'audio',
+      mediaType: audioMediaType(ctx.source),
+      source: ctx.source,
+      bytes: read.value,
+    } as unknown as ImportedAsset['payload'];
+    out.push({
+      guid: sub.guid,
+      kind: 'audio',
+      payload,
+      refs: [],
+      artifacts: {
+        source: {
+          mediaType: audioMediaType(ctx.source),
+          assetCodec: { name: 'browser-audio' },
+          bytes: read.value,
+        },
+      },
+    });
+  }
+  return { ok: true, value: { assets: out, sourceDependencies: [ctx.source] } };
+}
+
+/**
+ * The audio {@link Importer}. Register it into an `ImporterRegistry` so the
+ * import runner dispatches `meta.importer === 'audio'` sidecars here.
+ *
+ * @example
+ * ```ts
+ * import { ImporterRegistry } from '@forgeax/engine-import';
+ * import { audioImporter } from '@forgeax/engine-audio-webaudio/audio-importer';
+ * const importers = new ImporterRegistry();
+ * importers.register(audioImporter);
+ * ```
+ */
+export const audioImporter: Importer = {
+  key: 'audio',
+  import: importAudio,
+};

package/src/audio-listener-sync-system.ts

@@ -0,0 +1,98 @@
+// audio-listener-sync-system.ts -- AudioListener world-matrix sync.
+//
+// Syncs the first AudioListener entity's resolved world transform to the Web
+// Audio listener (position + forward/up orientation).
+//
+// feat-20260601 D-6: the sync consumes the single `Transform.world` mat4 (16
+// column-major floats, written by propagateTransforms) instead of a decomposed
+// GlobalTransform TRS. forward / up / position are extracted via the
+// `@forgeax/engine-math` mat4 helpers (getForward = -col2 normalized; getUp =
+// col1 normalized; getTranslation = col3, NOT normalized) -- direction
+// normalization eliminates non-uniform-scale pollution that a bare-column read
+// would leak. The old quaternion-rotate-vector formula is gone.
+//
+// Decision anchors:
+// - plan-strategy D-6 (rename + world-mat4 reshape + mat4 helper reuse)
+// - requirements AC-08 (AudioListener world-matrix sync; quadrant 3 falsify)
+// - requirements E-3 (multiple AudioListeners -> first only)
+//
+// Architecture note: the audio-webaudio package has no dependency on
+// engine-runtime (where Transform lives). The sync function is a pure helper
+// exported for host assembly. The host (engine-runtime or app layer) queries
+// the first AudioListener entity, reads its `Transform.world` mat4 (a 16-float
+// Float32Array), obtains the AudioContext listener from the AudioBackend, and
+// calls `syncListenerFromWorldMatrix(listener, worldMatrix)`.
+//
+// charter awareness:
+// - P3 explicit failure: no-op contracts, no throw for missing listener
+// - P4 consistent abstraction: reuse the math mat4 extract helpers (no
+//   hand-rolled quaternion rotation); pure function exports for unit testing
+// - P5 producer/consumer: sync function is the producer; host is the consumer
+
+import { mat4, vec3 } from '@forgeax/engine-math';
+
+/**
+ * Resolved world transform shape (feat-20260601 D-6): a single column-major
+ * mat4 carried as 16 contiguous floats -- the `Transform.world` column array
+ * view written by propagateTransforms.
+ */
+export interface WorldMatrixData {
+  readonly worldMatrix: Float32Array;
+}
+
+/**
+ * Pure function: write a world mat4's position/orientation to the Web Audio
+ * listener's AudioParams.
+ *
+ * Exported for unit testing (listener-sync.test.ts) and for host assembly (the
+ * host reads `Transform.world` + AudioListener from the World and calls this
+ * each frame).
+ *
+ * - position = `mat4.getTranslation(world)` (col3, copied directly, not normalized)
+ * - forward  = `mat4.getForward(world)` (-col2, normalized -- removes scale)
+ * - up       = `mat4.getUp(world)` (col1, normalized -- removes scale)
+ *
+ * @param listener The Web Audio API AudioListener (from AudioContext.listener)
+ * @param worldMatrix The resolved world mat4 (16 column-major floats) of the
+ *   entity carrying AudioListener.
+ */
+export function syncListenerFromWorldMatrix(
+  listener: AudioListener,
+  worldMatrix: Float32Array,
+): void {
+  const m = worldMatrix as unknown as mat4.Mat4Like;
+
+  const position = mat4.getTranslation(vec3.create(), m);
+  listener.positionX.value = position[0] as number;
+  listener.positionY.value = position[1] as number;
+  listener.positionZ.value = position[2] as number;
+
+  const forward = mat4.getForward(vec3.create(), m);
+  listener.forwardX.value = forward[0] as number;
+  listener.forwardY.value = forward[1] as number;
+  listener.forwardZ.value = forward[2] as number;
+
+  const up = mat4.getUp(vec3.create(), m);
+  listener.upX.value = up[0] as number;
+  listener.upY.value = up[1] as number;
+  listener.upZ.value = up[2] as number;
+}
+
+/**
+ * Run the audio listener sync system for a host-owned audio context.
+ *
+ * The host is responsible for:
+ * 1. Querying the World for entities with AudioListener
+ * 2. Taking the first AudioListener entity (E-3)
+ * 3. Reading its `Transform.world` mat4 (16-float Float32Array)
+ * 4. Calling this function with the AudioContext's listener
+ *
+ * This function is a convenience wrapper that calls
+ * `syncListenerFromWorldMatrix(ctx.listener, worldMatrix)`.
+ *
+ * @param ctx The Web Audio AudioContext (whose .listener receives position/orientation)
+ * @param worldMatrix The `Transform.world` mat4 from the AudioListener entity
+ */
+export function audioListenerSyncSystem(ctx: AudioContext, worldMatrix: Float32Array): void {
+  syncListenerFromWorldMatrix(ctx.listener, worldMatrix);
+}

package/src/audio-loader.ts

@@ -0,0 +1,55 @@
+import { AssetError, type Loader, type LoaderAsyncResult } from '@forgeax/engine-types';
+import { decodeAudioClipBytes } from './clip-loader';
+
+/** Loads an audio catalog row through the browser's native decoder. */
+export const audioLoader: Loader = {
+  kind: 'audio',
+  loadPack(input): Promise<LoaderAsyncResult> {
+    if (input.kind !== 'audio') {
+      return Promise.resolve({
+        ok: false,
+        error: new AssetError({
+          code: 'asset-parse-failed',
+          expected: "Pack v2 loader input with kind 'audio'",
+          hint: 'pass the asset-local audio envelope to the audio loader',
+          detail: { sourcePath: input.guid },
+        }),
+      });
+    }
+    const source = input.artifacts.source;
+    const payloadMediaType =
+      typeof input.payload.mediaType === 'string' ? input.payload.mediaType : undefined;
+    if (
+      source === undefined ||
+      !source.descriptor.mediaType.startsWith('audio/') ||
+      payloadMediaType !== source.descriptor.mediaType
+    ) {
+      return Promise.resolve({
+        ok: false,
+        error: {
+          code: 'asset-artifact-media-unsupported',
+          expected: 'an asset-local source artifact with an audio/* mediaType',
+          hint: 'declare the audio source artifact with a supported mediaType and re-cook',
+          detail: {
+            guid: input.guid,
+            artifactKey: 'source',
+            observed: payloadMediaType ?? source?.descriptor.mediaType ?? 'missing',
+            expected: 'payload.mediaType matching the audio/* source artifact',
+          },
+        },
+      });
+    }
+    return decodeAudioClipBytes(input.guid, source.bytes, payloadMediaType as `audio/${string}`);
+  },
+  async load(): Promise<LoaderAsyncResult> {
+    return {
+      ok: false,
+      error: new AssetError({
+        code: 'asset-parse-failed',
+        expected: 'Pack v2 audio input with an asset-local source artifact',
+        hint: 're-cook the audio source into the Pack v2 asset envelope',
+        detail: { sourcePath: 'audio-loader-input' },
+      }),
+    };
+  },
+};

package/src/clip-loader.ts

@@ -0,0 +1,53 @@
+// clip-loader.ts -- M3 (w27) AudioClipAsset register/load path
+//
+// Load AudioClipAsset from pack-index catalog via fetch + decodeAudioData.
+//
+// Decision anchors:
+// - plan-strategy D-6 (load path: fetch ArrayBuffer -> decodeAudioData -> register)
+// - requirements AC-03 (AudioClipAsset via asset system loadByGuid)
+// - requirements constraint 5 (format decided by browser decodeAudioData)
+// - requirements E-2 (decodeAudioData failure returns Err with code: 'decode-failed')
+// - requirements E-9 (nonexistent GUID returns Err with code 'asset-not-found')
+// - research Finding 'decodeAudioData error semantics'
+//
+// charter awareness:
+// - P3 explicit failure: returns Result<AudioClipAsset, AudioError> with structured errors
+// - P4 consistent abstraction: parallel to image/gltf loader patterns
+
+import { AudioError } from '@forgeax/engine-audio';
+import { type AudioClipAsset, err, ok, type Result } from '@forgeax/engine-types';
+
+export async function decodeAudioClipBytes(
+  guid: string,
+  bytes: Uint8Array,
+  mediaType: `audio/${string}`,
+): Promise<Result<AudioClipAsset, AudioError>> {
+  if (mediaType.length <= 'audio/'.length || bytes.byteLength === 0) {
+    return err(
+      new AudioError({
+        code: 'decode-failed',
+        expected: `non-empty audio mediaType and source bytes for GUID ${guid}`,
+        hint: 'verify the audio artifact mediaType and recook the source bytes',
+        detail: {
+          code: 'decode-failed' as const,
+          reason: 'audio mediaType or source bytes are empty',
+        },
+      }),
+    );
+  }
+  try {
+    return ok({ kind: 'audio', sourceKey: guid, mediaType, bytes: bytes.slice() });
+  } catch (e) {
+    return err(
+      new AudioError({
+        code: 'decode-failed',
+        expected: `decodable audio artifact bytes for GUID ${guid}`,
+        hint: 'verify the audio artifact mediaType and browser-supported codec',
+        detail: {
+          code: 'decode-failed' as const,
+          reason: e instanceof Error ? e.message : 'audio artifact decode failed',
+        },
+      }),
+    );
+  }
+}

package/src/host-audio-consumer.ts

@@ -0,0 +1,168 @@
+import {
+  type AudioBackend,
+  type AudioIntent,
+  type AudioPlayOptions,
+  type AudioState,
+  createAudioIntentBackend,
+} from '@forgeax/engine-audio';
+import { AudioError } from '@forgeax/engine-types';
+import { WebAudioEngine } from './web-audio-engine';
+
+interface ActiveSource {
+  readonly entityId: number;
+  readonly sourceKey: string;
+  readonly bytes?: Uint8Array;
+  readonly options: AudioPlayOptions;
+}
+
+export interface HostAudioConsumer {
+  consume(intent: AudioIntent): void;
+  state(): AudioState;
+  dispose(): void;
+  readonly engine: WebAudioEngine;
+}
+
+function decodeError(sourceKey: string, cause: unknown): AudioError {
+  return new AudioError({
+    code: 'decode-failed',
+    expected: `browser-decodable audio bytes for sourceKey ${sourceKey}`,
+    hint: 'verify the audio media type and source bytes',
+    detail: {
+      code: 'decode-failed',
+      reason: cause instanceof Error ? cause.message : String(cause),
+    },
+  });
+}
+
+function sameBytes(left: Uint8Array, right: Uint8Array): boolean {
+  if (left.byteLength !== right.byteLength) return false;
+  for (let index = 0; index < left.byteLength; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+
+interface DecodeEntry {
+  readonly promise: Promise<AudioBuffer>;
+}
+
+export function createHostAudioConsumer(engine = new WebAudioEngine()): HostAudioConsumer {
+  const sources = new Map<string, DecodeEntry>();
+  const sourceBytes = new Map<string, Uint8Array>();
+  const activeSources = new Map<number, ActiveSource>();
+  const entityEpoch = new Map<number, number>();
+  const bus = {
+    sfx: { volume: 1, muted: false },
+    music: { volume: 1, muted: false },
+  };
+  const cleanup: number[] = [];
+  let lastError: AudioError | null = null;
+  let disposed = false;
+  const nextEpoch = (entityId: number): number => {
+    const epoch = (entityEpoch.get(entityId) ?? 0) + 1;
+    entityEpoch.set(entityId, epoch);
+    return epoch;
+  };
+  const consumer: HostAudioConsumer = {
+    engine,
+    consume(intent): void {
+      if (disposed && intent.kind !== 'destroy') return;
+      if (intent.kind === 'play') {
+        const epoch = nextEpoch(intent.entityId);
+        if (intent.bytes !== undefined) {
+          const incomingBytes = intent.bytes.slice();
+          const publishedBytes = sourceBytes.get(intent.sourceKey);
+          if (publishedBytes === undefined || !sameBytes(publishedBytes, incomingBytes)) {
+            sourceBytes.set(intent.sourceKey, incomingBytes);
+            sources.delete(intent.sourceKey);
+          }
+        }
+        const bytes = sourceBytes.get(intent.sourceKey);
+        activeSources.set(intent.entityId, {
+          entityId: intent.entityId,
+          sourceKey: intent.sourceKey,
+          ...(bytes === undefined ? {} : { bytes: bytes.slice() }),
+          options: intent.options,
+        });
+        let decoded = sources.get(intent.sourceKey);
+        if (decoded === undefined && bytes !== undefined) {
+          const entry: DecodeEntry = {
+            promise: engine.decode(bytes),
+          };
+          decoded = entry;
+          sources.set(intent.sourceKey, entry);
+          void entry.promise.then(
+            () => {
+              if (sources.get(intent.sourceKey) === entry && lastError?.code === 'decode-failed') {
+                lastError = null;
+              }
+            },
+            (cause) => {
+              if (sources.get(intent.sourceKey) !== entry) return;
+              sources.delete(intent.sourceKey);
+              lastError = decodeError(intent.sourceKey, cause);
+            },
+          );
+        }
+        if (decoded === undefined) {
+          lastError = decodeError(intent.sourceKey, new Error('sourceKey was not published'));
+          return;
+        }
+        const currentDecode = decoded;
+        void currentDecode.promise
+          .then((buffer) => {
+            if (
+              !disposed &&
+              sources.get(intent.sourceKey) === currentDecode &&
+              entityEpoch.get(intent.entityId) === epoch
+            ) {
+              engine.play(intent.entityId, buffer, intent.options);
+            }
+          })
+          .catch(() => {});
+      } else if (intent.kind === 'stop') {
+        nextEpoch(intent.entityId);
+        if (activeSources.delete(intent.entityId)) {
+          cleanup.push(intent.entityId);
+          engine.stop(intent.entityId);
+        }
+      } else if (intent.kind === 'set-volume') {
+        engine.setVolume(intent.entityId, intent.volume);
+      } else if (intent.kind === 'set-bus-volume') {
+        bus[intent.bus].volume = intent.volume;
+        bus[intent.bus].muted = false;
+        engine.setBusVolume(intent.bus, intent.volume);
+      } else if (intent.kind === 'set-bus-mute') {
+        bus[intent.bus].muted = intent.muted;
+        engine.setBusMute(intent.bus, intent.muted);
+      } else if (intent.kind === 'set-listener-pose') {
+        engine.setListenerPose(intent.pose);
+      } else {
+        consumer.dispose();
+      }
+    },
+    state(): AudioState {
+      return { ...engine.getState(), lastError };
+    },
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      activeSources.clear();
+      entityEpoch.clear();
+      sources.clear();
+      sourceBytes.clear();
+      cleanup.length = 0;
+      engine.destroy();
+    },
+  };
+  return consumer;
+}
+
+export function createWebAudioBackend(): AudioBackend {
+  const consumer = createHostAudioConsumer();
+  const backend = createAudioIntentBackend({
+    emit: (intent) => consumer.consume(intent),
+    state: () => consumer.state(),
+  });
+  return backend;
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// @forgeax/engine-audio-webaudio -- public barrel (feat-20260527-audio-system M2 / w17+w19)
+//
+// Single-entry surface: AI users import `@forgeax/engine-audio-webaudio` for
+// the Web Audio API backend (charter P1 progressive disclosure).
+//
+// Exports:
+//   - createWebAudioBackend() factory (w17)
+//   - WebAudioEngine class (w16)
+//
+// Placeholder exports (M3 impl):
+//   - audioTickSystem (M3)
+//   - audioListenerSyncSystem (M3)
+//
+// Re-exports from @forgeax/engine-audio:
+//   - AudioBackend, AUDIO_ENGINE_RESOURCE_KEY
+
+// Re-exports from engine-audio for convenience
+export { AUDIO_ENGINE_RESOURCE_KEY, type AudioBackend } from '@forgeax/engine-audio';
+// audio listener sync system (Transform.world mat4 -> Web Audio listener)
+export {
+  audioListenerSyncSystem,
+  syncListenerFromWorldMatrix,
+} from './audio-listener-sync-system';
+export { audioLoader } from './audio-loader';
+export {
+  createHostAudioConsumer,
+  createWebAudioBackend,
+  type HostAudioConsumer,
+} from './host-audio-consumer';
+export { webAudioPlugin } from './plugin';
+export { WebAudioEngine } from './web-audio-engine';

package/src/plugin.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from '@forgeax/engine-plugin';
+
+import { createWebAudioBackend } from './host-audio-consumer';
+
+export function webAudioPlugin(): Plugin {
+  return {
+    name: 'web-audio',
+    provide: 'audio',
+    apply(ctx) {
+      const backend = createWebAudioBackend();
+      ctx.effect(() => () => backend.destroy(), 'audio/destroy-webaudio');
+      ctx.provide('audio', backend);
+    },
+  };
+}