@aethervtt/shard-audio-preview 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-audio-preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { type JsonObject } from '@aethervtt/shard-core';
+export interface AudioRenderBundle {
+    /** Serialized AudioPreviewPlan; runtime handles must pass through its serializer first. */
+    plan: JsonObject;
+    assets: {
+        guid: string;
+        path: string;
+        type: string;
+        value: unknown;
+    }[];
+}
+export declare function renderAudioBundle(bundle: AudioRenderBundle, options?: {
+    signal?: AbortSignal;
+    progress?: (value: Record<string, unknown>) => void;
+}): Promise<{
+    wav: Uint8Array<ArrayBufferLike>;
+    measured: {
+        peak: number;
+        rms: number;
+        clipped: number;
+        nonfinite: number;
+        sampleRate: number;
+        channels: number;
+        frames: number;
+        duration: number;
+    };
+    trace: {
+        zones: {
+            at: number;
+            buses: string[];
+        }[];
+        events: {
+            entries: import("@aethervtt/shard-audio").AudioEventTraceEntry[];
+            oldestCursor: number;
+            nextCursor: number;
+            truncated: boolean;
+        };
+        music: {
+            entries: import("@aethervtt/shard-audio").AudioEventTraceEntry[];
+            oldestCursor: number;
+            nextCursor: number;
+            truncated: boolean;
+        };
+        controls: {
+            index: number;
+            requestedAt: number;
+            appliedAt: number;
+        }[];
+        sources: {
+            id: number;
+            presentation: Readonly<import("@aethervtt/shard-platform").AudioPresentation> | undefined;
+        }[];
+        controlRate: number;
+        quantumFrames: number;
+    };
+    capabilities: Readonly<import("@aethervtt/shard-platform").AudioCapabilities>;
+    backend: {
+        kind: string;
+        userAgent: string;
+        sampleRate: number;
+    };
+}>;

package/dist/index.js

@@ -0,0 +1,317 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  AudioAcoustics,
+  AudioClips,
+  AudioListener,
+  AudioPreviewPlan,
+  AudioTransport,
+  acquireAudioSnapshot,
+  audioAcousticsPlugin,
+  audioEvents,
+  audioEventsPlugin,
+  audioMixerPlugin,
+  audioMusicPlugin,
+  audioPlugin,
+  audioState,
+  configureAudioMixer,
+  describeAudioEvents,
+  describeMusic,
+  pauseMusic,
+  playAudioEvent,
+  playMusicStinger,
+  prepareAudio,
+  prepareMusic,
+  prepareMusicSection,
+  ReverbZone,
+  releaseAudioSnapshot,
+  requestMusicSection,
+  resumeMusic,
+  seekMusic,
+  setAudioParameter,
+  setAudioSnapshotWeight,
+  setBus,
+  setMusicParameter,
+  startMusic,
+  stopAudioEvent,
+  stopMusic,
+  updateMusic,
+  validateAudioPreview
+} from "@aethervtt/shard-audio";
+import { ShardError } from "@aethervtt/shard-core";
+import {
+  audioBufferWav,
+  createWebAudioBackend,
+  measureAudioBuffer
+} from "@aethervtt/shard-platform-web";
+import { App } from "@aethervtt/shard-runtime";
+import { Transform, TransformPlugin } from "@aethervtt/shard-transform";
+async function renderAudioBundle(bundle, options = {}) {
+  if (typeof OfflineAudioContext === "undefined" || typeof OfflineAudioContext.prototype.suspend !== "function" || typeof OfflineAudioContext.prototype.resume !== "function")
+    throw new ShardError(
+      "audio-preview/unsupported-capability",
+      "This browser lacks suspended offline rendering",
+      {
+        hint: "Use a browser with OfflineAudioContext suspend/resume, or provide a host export adapter."
+      }
+    );
+  const plan = AudioPreviewPlan.deserialize(bundle.plan);
+  validateAudioPreview(plan);
+  const frames = Math.ceil((plan.duration + plan.tailSeconds) * plan.sampleRate);
+  if (frames * plan.channels * 6 + 44 > 64 * 1024 * 1024)
+    throw new ShardError("audio/preview-unavailable", "Preview output exceeds 64 MiB");
+  const context = new OfflineAudioContext(plan.channels, frames, plan.sampleRate);
+  const backend = createWebAudioBackend({
+    context,
+    fixedListener: true,
+    maxVoices: 4096,
+    maxHostVoices: 4096
+  });
+  const app = new App({ seed: plan.seed }).addPlugin(
+    TransformPlugin,
+    audioPlugin({ backend, maxVoices: 4096 }),
+    audioEventsPlugin(),
+    audioMixerPlugin(),
+    ...plan.zones.length ? [audioAcousticsPlugin()] : [],
+    audioMusicPlugin()
+  );
+  const world = app.world;
+  try {
+    await app.init();
+    const assets = assetServer(world), runtime = audioState(world).backend.runtime;
+    for (const item of bundle.assets)
+      assets.virtual(item.guid, item.path, item.type, () => item.value, { lazy: true });
+    for (const item of bundle.assets) await assets.load(item.guid);
+    const decoded = [];
+    for (const clip of world.resource(AudioClips).values())
+      decoded.push(await runtime.prepare(clip));
+    if (plan.mixer) await configureAudioMixer(world, plan.mixer);
+    const eventLeases = [];
+    for (const event of plan.events) eventLeases.push(await prepareAudio(world, event.asset));
+    const programs = /* @__PURE__ */ new Map();
+    for (const entry of plan.music) {
+      const program = await prepareMusic(world, entry.asset);
+      for (const section of program.definition.sections)
+        await prepareMusicSection(world, program, section.id);
+      programs.set(entry.id, program);
+    }
+    const eventIds = /* @__PURE__ */ new Map(), musicIds = /* @__PURE__ */ new Map(), emitters = /* @__PURE__ */ new Map(), snapshots = /* @__PURE__ */ new Map();
+    for (const entry of plan.music)
+      musicIds.set(
+        entry.id,
+        startMusic(world, programs.get(entry.id), {
+          section: entry.section || void 0,
+          at: entry.at,
+          parameters: entry.parameters
+        })
+      );
+    for (const entry of plan.zones)
+      world.spawn([Transform, { translation: entry.position }], [ReverbZone, entry.zone]);
+    const zoneTrace = [];
+    let lastZones = "";
+    const listener = world.spawn(Transform, AudioListener);
+    const voices = plan.voices.map(
+      (voice) => runtime.play({
+        clip: world.resource(AudioClips).require(plan.clips.find((c) => c.id === voice.clip).asset),
+        bus: voice.bus,
+        when: voice.at,
+        duration: voice.duration || (voice.loop ? plan.duration - voice.at : void 0),
+        offset: voice.offset,
+        loop: voice.loop,
+        gain: 10 ** (voice.gainDb / 20),
+        pitch: voice.pitch,
+        x: voice.position[0],
+        y: voice.position[1],
+        z: voice.position[2],
+        spatial: voice.spatial ? {
+          panning: "equal-power",
+          distanceModel: "inverse",
+          refDistance: voice.minDistance,
+          maxDistance: voice.maxDistance,
+          rolloffFactor: 1
+        } : null
+      })
+    );
+    for (const command of plan.automation)
+      runtime.automate(voices[plan.voices.findIndex((v) => v.id === command.voice)], command);
+    const controls = plan.controls.map((control, index) => ({ control, index })).sort((a, b) => a.control.at - b.control.at || a.index - b.index);
+    const applied = [];
+    let nextControl = 0, last = 0, stopped = false;
+    const target = (map, name) => {
+      const id = map.get(name);
+      if (id === void 0)
+        throw new ShardError("audio/preview-unavailable", `Preview target ${name} has not started`);
+      return id;
+    };
+    async function tick() {
+      const now = context.currentTime;
+      if (options.signal?.aborted)
+        throw new ShardError("audio-preview/disposed", "Offline preview cancelled");
+      options.progress?.({ stage: "tick", time: now, nextControl });
+      for (const entry of plan.events)
+        if (!eventIds.has(entry.id) && now >= entry.at) {
+          const entity = world.spawn(Transform);
+          world.set(entity, Transform, { translation: entry.position });
+          emitters.set(entry.id, entity);
+          eventIds.set(
+            entry.id,
+            playAudioEvent(world, entry.asset, {
+              entity,
+              parameters: entry.parameters,
+              clock: entry.clock,
+              pitchLinked: entry.pitchLinked
+            })
+          );
+        }
+      while (nextControl < controls.length && controls[nextControl].control.at <= now) {
+        const { control: c, index } = controls[nextControl++], opts = c.options;
+        switch (c.kind) {
+          case "event.parameter":
+            setAudioParameter(world, target(eventIds, c.target), c.name, c.value);
+            break;
+          case "global.parameter":
+            setAudioParameter(world, null, c.name, c.value);
+            break;
+          case "event.stop":
+            stopAudioEvent(world, target(eventIds, c.target), opts);
+            break;
+          case "event.position": {
+            const entity = emitters.get(c.target);
+            if (entity === void 0)
+              throw new ShardError("audio/preview-unavailable", "Emitter has not started");
+            world.set(entity, Transform, { translation: c.position });
+            break;
+          }
+          case "listener.position":
+            world.set(listener, Transform, { translation: c.position });
+            break;
+          case "music.parameter":
+            setMusicParameter(world, target(musicIds, c.target), c.name, c.value);
+            break;
+          case "music.section":
+            requestMusicSection(world, target(musicIds, c.target), c.name, opts);
+            break;
+          case "music.stinger":
+            await playMusicStinger(world, target(musicIds, c.target), c.name, opts);
+            break;
+          case "music.pause":
+            pauseMusic(world, target(musicIds, c.target));
+            break;
+          case "music.resume":
+            resumeMusic(world, target(musicIds, c.target));
+            break;
+          case "music.seek":
+            seekMusic(world, target(musicIds, c.target), Number(c.value));
+            break;
+          case "snapshot.acquire":
+            if (snapshots.has(c.target)) releaseAudioSnapshot(world, snapshots.get(c.target));
+            snapshots.set(
+              c.target,
+              await acquireAudioSnapshot(world, c.asset, c.value == null ? 1 : Number(c.value))
+            );
+            break;
+          case "snapshot.set":
+            setAudioSnapshotWeight(world, target(snapshots, c.target), Number(c.value));
+            break;
+          case "snapshot.release":
+            releaseAudioSnapshot(world, target(snapshots, c.target));
+            break;
+          case "bus.volume":
+            setBus(world, c.target, { volume: Number(c.value) });
+            break;
+          case "transport.pause":
+            world.resource(AudioTransport).paused = Boolean(c.value);
+            break;
+        }
+        applied.push({ index, requestedAt: c.at, appliedAt: now });
+      }
+      if (!stopped && now >= plan.duration) {
+        stopped = true;
+        for (const instance of audioEvents(world).instances)
+          if (instance) stopAudioEvent(world, instance.id, { release: 0 });
+        for (const id of musicIds.values()) stopMusic(world, id);
+        for (const id of voices) runtime.cancel(id);
+      }
+      app.update(now - last);
+      const acoustics = world.tryResource(AudioAcoustics);
+      if (acoustics) {
+        const buses = acoustics.slots.filter((slot) => slot.weight > 0).map((slot) => slot.bus);
+        const key = buses.join(",");
+        if (key !== lastZones) {
+          zoneTrace.push({ at: now, buses });
+          lastZones = key;
+        }
+      }
+      updateMusic(world);
+      last = now;
+      await runtime.flush();
+    }
+    await tick();
+    const total = frames / plan.sampleRate;
+    let rendering;
+    let step = 1;
+    for (; ; ) {
+      const wanted = Math.min(
+        step / 60,
+        nextControl < controls.length ? controls[nextControl].control.at : Infinity,
+        ...plan.events.filter((e) => !eventIds.has(e.id)).map((e) => e.at),
+        ...plan.music.filter((e) => !musicIds.has(e.id)).map((e) => e.at),
+        stopped ? Infinity : plan.duration
+      );
+      const at = Math.max(
+        Math.round(last * plan.sampleRate / 128) + 1,
+        Math.ceil(wanted * plan.sampleRate / 128)
+      ) * 128 / plan.sampleRate;
+      if (at >= total) break;
+      options.progress?.({ stage: "suspend", time: context.currentTime, target: at });
+      const suspended = context.suspend(at + 0.5 / plan.sampleRate);
+      if (!rendering) rendering = context.startRendering();
+      else await context.resume();
+      await suspended;
+      await tick();
+      step = Math.floor(context.currentTime * 60) + 1;
+    }
+    if (!rendering) rendering = context.startRendering();
+    else await context.resume();
+    const buffer = await rendering, measured = measureAudioBuffer(buffer);
+    if (measured.nonfinite)
+      throw new ShardError("audio/preview-unavailable", "Rendered nonfinite samples");
+    const trace = {
+      zones: zoneTrace,
+      events: describeAudioEvents(world).trace,
+      music: describeMusic(world).trace,
+      controls: applied,
+      sources: voices.map((id) => ({ id, presentation: runtime.presentation(id) })),
+      controlRate: 60,
+      quantumFrames: 128
+    };
+    for (const lease of decoded) lease.release();
+    for (const lease of eventLeases) lease.release();
+    for (const program of programs.values()) program.release();
+    return {
+      wav: audioBufferWav(buffer),
+      measured,
+      trace,
+      capabilities: runtime.capabilities,
+      backend: {
+        kind: "web-audio-offline",
+        userAgent: navigator.userAgent,
+        sampleRate: context.sampleRate
+      }
+    };
+  } finally {
+    try {
+      await app.dispose();
+    } finally {
+      backend.dispose?.();
+      if (options.signal?.aborted && context.state === "suspended") {
+        try {
+          await context.resume();
+        } catch {
+        }
+      }
+    }
+  }
+}
+export {
+  renderAudioBundle
+};

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@aethervtt/shard-audio-preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-audio": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-platform-web": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-transform": "0.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/audio-preview"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
+  }
+}