@aethervtt/shard-audio-editor 0.0.0-stage → 0.2.1

package/dist/preview-runtime.js

@@ -0,0 +1,414 @@
+import {
+  AudioClips,
+  AudioCollection,
+  AudioEvent,
+  AudioListener,
+  AudioMixer,
+  AudioSnapshot,
+  acquireAudioSnapshot,
+  audioClip,
+  audioEventsPlugin,
+  audioMixerPlugin,
+  audioMusicPlugin,
+  audioPlugin,
+  audioState,
+  configureAudioMixer,
+  describeAudio,
+  MusicProgram,
+  playAudioEvent,
+  prepareAudio,
+  prepareMusic,
+  releaseAudioSnapshot,
+  setAudioUserBus,
+  startMusic,
+  stopAudioEvent,
+  stopMusic
+} from "@aethervtt/shard-audio";
+import {
+  ShardError
+} from "@aethervtt/shard-core";
+import { App } from "@aethervtt/shard-runtime";
+import { Transform, TransformPlugin } from "@aethervtt/shard-transform";
+import { getAudioEditorSchema, materializeAudioDocument, validateAudioDocument } from "./schema.js";
+async function createPreviewRuntime(options) {
+  const supplied = options.backend;
+  if (supplied && (!supplied.runtime?.capabilities.sessions || !supplied.createSession))
+    throw new ShardError(
+      "audio-editor/unsupported-capability",
+      "The supplied backend cannot isolate an editor session",
+      {
+        hint: "Supply a backend with createSession capability, or let the editor own a browser backend."
+      }
+    );
+  const backend = supplied ?? options.createBackend?.() ?? (await import("@aethervtt/shard-platform-web")).createWebAudioBackend();
+  let auditionError;
+  const unlock = () => {
+    const failed = (cause) => {
+      auditionError = new ShardError(
+        "audio-editor/playback-blocked",
+        "Audio output could not resume",
+        {
+          cause,
+          hint: "Check the host audio device and browser permission, then press Play again."
+        }
+      );
+    };
+    try {
+      const pending = backend.resume?.();
+      void pending?.then(() => {
+        auditionError = void 0;
+      }, failed);
+    } catch (cause) {
+      failed(cause);
+    }
+  };
+  unlock();
+  const app = new App().addPlugin(
+    TransformPlugin,
+    audioPlugin({ backend }),
+    audioEventsPlugin(),
+    audioMixerPlugin(),
+    audioMusicPlugin()
+  );
+  try {
+    await app.init();
+  } catch (error) {
+    await app.dispose();
+    if (!supplied) backend.dispose?.();
+    throw error;
+  }
+  const owned = audioState(app.world).backend;
+  if (supplied && owned === supplied) {
+    await app.dispose();
+    throw new ShardError(
+      "audio-editor/unsupported-capability",
+      "The supplied backend cannot isolate an editor session",
+      {
+        hint: "Supply a backend with createSession capability, or let the editor own a browser backend."
+      }
+    );
+  }
+  const events = /* @__PURE__ */ new Set();
+  const emitters = /* @__PURE__ */ new Map();
+  const listener = app.world.spawn(Transform, AudioListener);
+  const music = /* @__PURE__ */ new Set();
+  const snapshots = /* @__PURE__ */ new Set();
+  const requests = /* @__PURE__ */ new Set();
+  const releases = [];
+  const removals = [];
+  const definitions = /* @__PURE__ */ new Map();
+  let disposed = false;
+  let serial = 0;
+  let last = owned.runtime.clock.now();
+  const tick = () => {
+    if (disposed) return;
+    const now = owned.runtime.clock.now();
+    app.update(Math.max(0, Math.min(0.1, now - last)));
+    last = now;
+  };
+  const wake = owned.runtime.clock.wake(tick, 1 / 60);
+  const assertLive = (signal) => {
+    if (disposed || signal?.aborted)
+      throw new ShardError("audio-editor/disposed", "Audio preview was cancelled");
+  };
+  const stop = () => {
+    for (const id of events) stopAudioEvent(app.world, id, { release: 0 });
+    for (const id of music) stopMusic(app.world, id);
+    for (const id of snapshots) releaseAudioSnapshot(app.world, id);
+    events.clear();
+    for (const entity of emitters.values()) app.world.despawn(entity);
+    emitters.clear();
+    music.clear();
+    snapshots.clear();
+    while (releases.length) releases.pop()();
+    while (removals.length) removals.pop()();
+    definitions.clear();
+    requests.clear();
+    owned.runtime.collect();
+  };
+  async function install(document, signal) {
+    const resolved = /* @__PURE__ */ new Map();
+    const pending = /* @__PURE__ */ new Set();
+    const scope = options.assets.scope;
+    const docsScope = options.documents.scope;
+    const check = () => {
+      assertLive(signal);
+      if (scope !== options.assets.scope || docsScope !== options.documents.scope)
+        throw new ShardError(
+          "audio-editor/asset-unavailable",
+          "Host scope changed during preparation"
+        );
+    };
+    async function reference(id, type) {
+      check();
+      const key = `${type}:${id}`;
+      const existing = resolved.get(key);
+      if (existing) return existing;
+      if (pending.has(key))
+        throw new ShardError("audio-editor/invalid-document", "Cyclic audio document references", {
+          path: id
+        });
+      if (type !== "AudioClip") {
+        const dependency = id === document.id ? document : await options.documents.read(id, signal);
+        if (dependency.type !== type)
+          throw new ShardError(
+            "audio-editor/invalid-document",
+            `Expected ${type}, received ${dependency.type}`,
+            { path: id }
+          );
+        return installDocument(dependency);
+      }
+      const metadata = await options.assets.get(id, signal);
+      check();
+      const guid = JSON.stringify([scope, id, metadata.revision]);
+      const store = app.world.resource(AudioClips);
+      const result = { type, guid, path: void 0 };
+      if (store.has(guid)) {
+        resolved.set(key, result);
+        return result;
+      }
+      const content = await options.assets.resolve(id, signal);
+      try {
+        check();
+        if (!content.bytes)
+          throw new ShardError(
+            "audio-editor/unsupported-capability",
+            "Audition requires authorized audio bytes",
+            {
+              path: id,
+              hint: "Have the host resolver return encoded bytes for decoded preview playback."
+            }
+          );
+        store.set(
+          guid,
+          audioClip(Uint8Array.from(content.bytes), { ...content.settings, id: guid })
+        );
+        removals.push(() => {
+          store.delete(guid);
+        });
+        resolved.set(key, result);
+        return result;
+      } finally {
+        content.release?.();
+      }
+    }
+    async function field(field2, value) {
+      if (field2.kind === "handle" && value) {
+        const ref = value;
+        const id = ref.guid ?? ref.path;
+        if (!id)
+          throw new ShardError("audio-editor/asset-unavailable", "Audio reference has no host ID");
+        return reference(id, field2.assetType);
+      }
+      if (field2.kind === "list" && Array.isArray(value)) {
+        const items = [];
+        for (const item of value) items.push(await fieldValue(field2.item, item));
+        return items;
+      }
+      if (field2.kind === "struct") {
+        const result = { ...value };
+        for (const [name, child] of Object.entries(field2.fields))
+          result[name] = await fieldValue(child, result[name]);
+        return result;
+      }
+      return value;
+    }
+    const fieldValue = field;
+    async function installDocument(source) {
+      const key = `${source.type}:${source.id}`;
+      pending.add(key);
+      const schema = getAudioEditorSchema(source.type);
+      if (!schema)
+        throw new ShardError("audio-editor/unsupported-schema", `Cannot audition ${source.type}`);
+      source = await materializeAudioDocument(source, options.documents, signal);
+      const { errors } = await validateAudioDocument(
+        source,
+        options.documents,
+        options.assets,
+        signal
+      );
+      if (errors.length) throw errors[0];
+      const value = schema.deserialize(source.value);
+      for (const [name, definition] of Object.entries(schema.fields))
+        value[name] = await fieldValue(definition, value[name]);
+      check();
+      const signature = JSON.stringify([docsScope, source.id, source.revision, value]);
+      const previous = definitions.get(signature);
+      if (previous) {
+        resolved.set(key, previous);
+        pending.delete(key);
+        return previous;
+      }
+      if (definitions.size >= 256)
+        throw new ShardError("audio/capacity", "Preview retains at most 256 document revisions", {
+          hint: "Stop audition to release pinned preview revisions before preparing more."
+        });
+      const guid = JSON.stringify([docsScope, source.id, source.revision, ++serial]);
+      const store = app.world.initResource(schema.store);
+      store.set(guid, value);
+      removals.push(() => {
+        store.delete(guid);
+      });
+      const ref = { type: source.type, guid, path: void 0 };
+      definitions.set(signature, ref);
+      resolved.set(key, ref);
+      pending.delete(key);
+      return ref;
+    }
+    return installDocument(document);
+  }
+  async function playDocument(document, signal) {
+    assertLive(signal);
+    unlock();
+    const ref = await install(document, signal);
+    assertLive(signal);
+    const world = app.world;
+    if (document.type === AudioEvent.name || document.type === AudioCollection.name) {
+      const lease = await prepareAudio(world, ref);
+      if (disposed || signal?.aborted) {
+        lease.release();
+        assertLive(signal);
+      }
+      if (document.type === AudioCollection.name) {
+        releases.push(() => lease.release());
+        return { lease: lease.id, prepared: true };
+      }
+      let entity;
+      let instance;
+      try {
+        entity = world.spawn(Transform);
+        instance = playAudioEvent(world, ref, { entity });
+        emitters.set(instance, entity);
+        events.add(instance);
+        await Promise.resolve();
+        await Promise.resolve();
+        assertLive(signal);
+        tick();
+        releases.push(() => lease.release());
+        return { instance };
+      } catch (error) {
+        if (instance !== void 0) {
+          stopAudioEvent(world, instance, { release: 0 });
+          events.delete(instance);
+          emitters.delete(instance);
+        }
+        if (entity !== void 0 && world.isAlive(entity)) world.despawn(entity);
+        lease.release();
+        throw error;
+      }
+    }
+    if (document.type === MusicProgram.name) {
+      const program = await prepareMusic(world, ref);
+      try {
+        assertLive(signal);
+        const transport = startMusic(world, program);
+        music.add(transport);
+        return { transport };
+      } finally {
+        program.release();
+      }
+    }
+    if (document.type === AudioMixer.name) {
+      await configureAudioMixer(world, ref);
+      assertLive(signal);
+      return { configured: true };
+    }
+    if (document.type === AudioSnapshot.name) {
+      const snapshot = await acquireAudioSnapshot(world, ref);
+      if (disposed || signal?.aborted) {
+        releaseAudioSnapshot(world, snapshot);
+        assertLive(signal);
+      }
+      snapshots.add(snapshot);
+      return { snapshot };
+    }
+    return { prepared: true };
+  }
+  return {
+    unlock,
+    async play(document, signal) {
+      assertLive(signal);
+      if (requests.size >= 256)
+        throw new ShardError("audio/capacity", "Preview retains at most 256 audition requests", {
+          hint: "Press Stop to release audition voices, preparations and pinned revisions before playing more."
+        });
+      const request = /* @__PURE__ */ Symbol();
+      requests.add(request);
+      try {
+        return await playDocument(document, signal);
+      } catch (error) {
+        requests.delete(request);
+        throw error;
+      }
+    },
+    command(name, params) {
+      assertLive();
+      if (name === "audio.user.set") {
+        if (typeof params.bus !== "string")
+          throw new ShardError("audio-editor/invalid-document", "User category requires a bus name");
+        setAudioUserBus(app.world, params.bus, params);
+        return { updated: true };
+      }
+      if (name === "audio.listener.set" || name === "audio.emitter.set") {
+        const position = params.position;
+        if (!Array.isArray(position) || position.length !== 3 || position.some((value) => typeof value !== "number" || !Number.isFinite(value)))
+          throw new ShardError(
+            "audio-editor/invalid-document",
+            "Position requires three finite coordinates",
+            { path: "/position" }
+          );
+        const entity = name === "audio.listener.set" ? listener : emitters.get(Number(params.instance));
+        if (entity === void 0)
+          throw new ShardError(
+            "audio-editor/invalid-document",
+            "This preview does not own the emitter"
+          );
+        app.world.set(entity, Transform, { translation: position });
+        tick();
+        return { updated: true };
+      }
+      const method = app.methods.find((item) => item.name === name);
+      if (!method || !name.startsWith("audio."))
+        throw new ShardError("audio-editor/unsupported-capability", `Unknown audio command ${name}`);
+      if ([
+        "audio.play",
+        "audio.prepare",
+        "audio.music.start",
+        "audio.snapshot.acquire",
+        "audio.preview"
+      ].includes(name))
+        throw new ShardError(
+          "audio-editor/unsupported-capability",
+          "Use editor audition to resolve host assets"
+        );
+      const errors = method.params.validate(params);
+      if (errors.length) throw errors[0];
+      return method.handler(
+        { app, world: app.world },
+        method.params.deserialize(params)
+      );
+    },
+    inspect() {
+      assertLive();
+      tick();
+      return {
+        ...structuredClone(describeAudio(app.world)),
+        ...auditionError ? { auditionError: auditionError.toJSON() } : {}
+      };
+    },
+    stop,
+    dispose() {
+      if (disposed) return;
+      stop();
+      disposed = true;
+      wake();
+      owned.dispose?.();
+      const closing = app.dispose();
+      if (!supplied) backend.dispose?.();
+      return closing;
+    }
+  };
+}
+export {
+  createPreviewRuntime
+};

package/dist/preview.d.ts

@@ -0,0 +1,25 @@
+import { type JsonObject } from '@aethervtt/shard-core';
+import type { AudioBackend } from '@aethervtt/shard-platform';
+import type { AudioAssetCatalog, AudioDocument, AudioDocumentStore, AudioPreviewAdapter } from './types.js';
+import { type AudioWaveformDecoder } from './waveform.js';
+export interface IsolatedAudioPreviewOptions {
+    assets: AudioAssetCatalog;
+    documents: AudioDocumentStore;
+    /** Borrowed host root. It must support isolated sessions; the root is never closed. */
+    backend?: AudioBackend;
+    waveformDecoder?: AudioWaveformDecoder;
+    waveformBytes?: number;
+    /** The host implements the existing audio preview render-plan/export capability. */
+    export?(document: AudioDocument, plan: JsonObject, signal?: AbortSignal): Promise<unknown>;
+}
+/** Silent construction. Engine/platform implementation loads only on explicit Play. */
+export declare function createIsolatedAudioPreview(options: IsolatedAudioPreviewOptions): AudioPreviewAdapter;
+export interface AttachedAudioPreviewOptions {
+    target: string;
+    call(name: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+    liveControl?: boolean;
+    /** Explicit host capability; absence never causes an implicit save. */
+    applyDraft?(document: AudioDocument, signal?: AbortSignal): Promise<string>;
+}
+/** Protocol bridge has no privilege to close the target or stop its unrelated instances. */
+export declare function createAttachedAudioPreview(options: AttachedAudioPreviewOptions): AudioPreviewAdapter;