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

package/dist/preview.js

@@ -0,0 +1,296 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { validateAudioDocument } from "./schema.js";
+import { createAudioWaveformCache } from "./waveform.js";
+function createIsolatedAudioPreview(options) {
+  let runtime;
+  let opening;
+  let disposed = false;
+  let scope = JSON.stringify([options.assets.scope, options.documents.scope]);
+  let controller = new AbortController();
+  let factory;
+  let createBackend;
+  const preload = Promise.all([
+    import("./preview-runtime.js"),
+    import("@aethervtt/shard-platform-web")
+  ]).then(([runtimeModule, platform]) => {
+    factory = runtimeModule.createPreviewRuntime;
+    createBackend = platform.createWebAudioBackend;
+  });
+  void preload.catch(() => {
+  });
+  const waveforms = createAudioWaveformCache(options.assets, {
+    decode: options.waveformDecoder,
+    maxBytes: options.waveformBytes
+  });
+  const canExport = !!options.export || typeof OfflineAudioContext !== "undefined" && typeof OfflineAudioContext.prototype.suspend === "function" && typeof OfflineAudioContext.prototype.resume === "function";
+  const assertLive = (signal) => {
+    if (disposed || signal?.aborted)
+      throw new ShardError("audio-editor/disposed", "Audio audition is closed or cancelled", {
+        hint: "Use an active editor preview session."
+      });
+  };
+  const reset = () => {
+    controller.abort();
+    controller = new AbortController();
+    runtime?.dispose();
+    runtime = void 0;
+    opening = void 0;
+    waveforms.clear();
+  };
+  const checkScope = () => {
+    const current = JSON.stringify([options.assets.scope, options.documents.scope]);
+    if (scope !== current) {
+      reset();
+      scope = current;
+    }
+  };
+  const invalidate = () => {
+    const current = JSON.stringify([options.assets.scope, options.documents.scope]);
+    if (current !== scope) {
+      reset();
+      scope = current;
+      return;
+    }
+    controller.abort();
+    controller = new AbortController();
+    opening = void 0;
+    waveforms.clear();
+  };
+  const unsubscribe = options.assets.subscribe?.(invalidate);
+  const unsubscribeDocuments = options.documents.subscribe?.(invalidate);
+  async function ensure(signal) {
+    assertLive(signal);
+    checkScope();
+    if (runtime) return runtime;
+    if (!opening) {
+      const token = controller.signal;
+      const start = async () => {
+        assertLive(token);
+        const value = await factory({ ...options, createBackend });
+        if (disposed || token.aborted) {
+          value.dispose();
+          assertLive(token);
+        }
+        runtime = value;
+        return value;
+      };
+      opening = (factory ? start() : preload.then(start)).catch((error) => {
+        if (!token.aborted) opening = void 0;
+        throw error;
+      });
+    }
+    return opening;
+  }
+  return {
+    mode: "audition",
+    capabilities: {
+      play: true,
+      control: true,
+      drafts: true,
+      waveform: true,
+      listener: true,
+      emitter: true,
+      userControls: true,
+      export: canExport
+    },
+    async play(document, signal) {
+      assertLive(signal);
+      checkScope();
+      const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+      runtime?.unlock();
+      const pending = ensure(combined);
+      void pending.catch(() => {
+      });
+      const result = await validateAudioDocument(
+        document,
+        options.documents,
+        options.assets,
+        combined
+      );
+      assertLive(combined);
+      if (result.errors.length) throw result.errors[0];
+      const active = await pending;
+      assertLive(combined);
+      return active.play(result.effective ?? document, combined);
+    },
+    stop() {
+      assertLive();
+      controller.abort();
+      controller = new AbortController();
+      opening = void 0;
+      runtime?.stop();
+    },
+    inspect() {
+      assertLive();
+      checkScope();
+      return runtime?.inspect() ?? { mode: "audition", state: "idle", owned: true };
+    },
+    async command(name, params) {
+      return (await ensure()).command(name, params);
+    },
+    waveform(id, bins, signal) {
+      assertLive(signal);
+      checkScope();
+      return waveforms.get(id, bins, signal);
+    },
+    ...canExport ? {
+      async export(document, plan, signal) {
+        assertLive(signal);
+        checkScope();
+        const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+        const result = await validateAudioDocument(
+          document,
+          options.documents,
+          options.assets,
+          combined
+        );
+        assertLive(combined);
+        if (result.errors.length) throw result.errors[0];
+        if (options.export) return options.export(result.effective ?? document, plan, combined);
+        const { exportAudioEditorPreview } = await import("./preview-export.js");
+        assertLive(combined);
+        return exportAudioEditorPreview(options, result.effective ?? document, plan, combined);
+      }
+    } : {},
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      reset();
+      unsubscribe?.();
+      unsubscribeDocuments?.();
+      waveforms.dispose();
+    }
+  };
+}
+const inspection = /* @__PURE__ */ new Set([
+  "audio.describe",
+  "audio.events.inspect",
+  "audio.mix.inspect",
+  "audio.music.inspect",
+  "audio.meters",
+  "audio.log"
+]);
+function createAttachedAudioPreview(options) {
+  const ownedEvents = /* @__PURE__ */ new Set();
+  const ownedMusic = /* @__PURE__ */ new Set();
+  const ownedSnapshots = /* @__PURE__ */ new Set();
+  let disposed = false;
+  let controller = new AbortController();
+  const assertLive = () => {
+    if (disposed) throw new ShardError("audio-editor/disposed", "Runtime attachment is closed");
+  };
+  const requireControl = () => {
+    assertLive();
+    if (!options.liveControl)
+      throw new ShardError(
+        "audio-editor/read-only",
+        `Attachment ${options.target} permits inspection only`,
+        { hint: "The host must explicitly grant live audio control." }
+      );
+  };
+  const stop = async () => {
+    controller.abort();
+    controller = new AbortController();
+    for (const instance of ownedEvents) await options.call("audio.stop", { instance, release: 0 });
+    for (const transport of ownedMusic) await options.call("audio.music.stop", { transport });
+    for (const snapshot of ownedSnapshots)
+      await options.call("audio.snapshot.release", { snapshot });
+    ownedEvents.clear();
+    ownedMusic.clear();
+    ownedSnapshots.clear();
+  };
+  return {
+    mode: "attached",
+    target: options.target,
+    capabilities: {
+      play: !!options.liveControl && !!options.applyDraft,
+      control: !!options.liveControl,
+      drafts: !!options.applyDraft,
+      waveform: false,
+      export: false
+    },
+    async play(document, signal) {
+      requireControl();
+      if (!options.applyDraft)
+        throw new ShardError(
+          "audio-editor/unsupported-capability",
+          "This attachment cannot apply unsaved drafts",
+          { hint: "Use isolated audition, or supply a host draft-apply capability." }
+        );
+      const method = document.type === "audio/AudioEvent" ? "audio.play" : document.type === "audio/MusicProgram" ? "audio.music.start" : document.type === "audio/AudioSnapshot" ? "audio.snapshot.acquire" : void 0;
+      if (!method)
+        throw new ShardError(
+          "audio-editor/unsupported-capability",
+          "This document type has no attached play command"
+        );
+      const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+      const asset = await options.applyDraft(document, combined);
+      if (combined.aborted)
+        throw new ShardError("audio-editor/disposed", "Draft attachment was cancelled");
+      assertLive();
+      const result = await options.call(
+        method,
+        method === "audio.play" ? { event: asset } : { asset },
+        combined
+      );
+      if (disposed || combined.aborted) {
+        if (typeof result.instance === "number")
+          await options.call("audio.stop", { instance: result.instance, release: 0 });
+        if (typeof result.transport === "number")
+          await options.call("audio.music.stop", { transport: result.transport });
+        if (typeof result.snapshot === "number")
+          await options.call("audio.snapshot.release", { snapshot: result.snapshot });
+        throw new ShardError("audio-editor/disposed", "Attached playback was cancelled");
+      }
+      if (typeof result.instance === "number") ownedEvents.add(result.instance);
+      if (typeof result.transport === "number") ownedMusic.add(result.transport);
+      if (typeof result.snapshot === "number") ownedSnapshots.add(result.snapshot);
+      return result;
+    },
+    stop,
+    async inspect() {
+      assertLive();
+      return {
+        target: options.target,
+        mode: "attached",
+        control: !!options.liveControl,
+        audio: await options.call("audio.describe", {}, controller.signal)
+      };
+    },
+    async command(name, params) {
+      assertLive();
+      if (!inspection.has(name)) {
+        requireControl();
+        const event = Number(params.instance);
+        const music = Number(params.transport);
+        const snapshot = Number(params.snapshot);
+        const allowed = ["audio.stop", "audio.parameter.set"].includes(name) && ownedEvents.has(event) || [
+          "audio.music.parameter",
+          "audio.music.transition",
+          "audio.music.stinger",
+          "audio.music.pause",
+          "audio.music.resume",
+          "audio.music.seek",
+          "audio.music.cancel",
+          "audio.music.stop"
+        ].includes(name) && ownedMusic.has(music) || ["audio.snapshot.set", "audio.snapshot.release"].includes(name) && ownedSnapshots.has(snapshot);
+        if (!allowed)
+          throw new ShardError(
+            "audio-editor/unsupported-capability",
+            "Command is outside this editor attachment\u2019s owned instances"
+          );
+      }
+      return options.call(name, params, controller.signal);
+    },
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      controller.abort();
+      await stop();
+    }
+  };
+}
+export {
+  createAttachedAudioPreview,
+  createIsolatedAudioPreview
+};

package/dist/project.d.ts

@@ -0,0 +1,15 @@
+import type { Platform } from '@aethervtt/shard-platform';
+import type { AudioAssetCatalog, AudioDocumentStore } from './types.js';
+/**
+ * A project-file host. It uses the project's manifest and audio import probe, never a DOM picker.
+ * Commits serialize within this adapter and preflight source revisions. PlatformFileSystem has no
+ * cross-process CAS primitive: concurrent external writers must be coordinated by the host.
+ * Multi-document atomic commits are explicitly unsupported.
+ */
+export declare function openAudioProject(platform: Platform, scope?: string): Promise<{
+    name: string;
+    documents: AudioDocumentStore;
+    assets: AudioAssetCatalog;
+    refresh: () => Promise<void>;
+    dispose(): void;
+}>;

package/dist/project.js

@@ -0,0 +1,332 @@
+import { sha256Hex } from "@aethervtt/shard-assets";
+import { AudioImportSettings, audioClip } from "@aethervtt/shard-audio";
+import { ShardError } from "@aethervtt/shard-core";
+import { loadProject } from "@aethervtt/shard-project/manifest";
+const types = {
+  "audio-event": "audio/AudioEvent",
+  "audio-mixer": "audio/AudioMixer",
+  "audio-music": "audio/MusicProgram",
+  "audio-parameters": "audio/AudioParameters",
+  "audio-snapshot": "audio/AudioSnapshot",
+  "audio-collection": "audio/AudioCollection"
+};
+function revision(text) {
+  return sha256Hex(new TextEncoder().encode(text));
+}
+async function openAudioProject(platform, scope = "project") {
+  const { manifest } = await loadProject(platform);
+  const fs = platform.fs;
+  if (!fs.list)
+    throw new ShardError(
+      "audio-editor/unsupported-capability",
+      "This host cannot list project assets"
+    );
+  const paths = /* @__PURE__ */ new Map();
+  const aliases = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let catalogError;
+  let disposed = false;
+  const check = (signal) => {
+    if (disposed) throw new ShardError("audio-editor/disposed", "The project adapter is closed");
+    signal?.throwIfAborted();
+  };
+  const scan = async (dir, index = paths, sourceAliases = aliases) => {
+    for (const entry of await fs.list(dir)) {
+      const path = `${dir}/${entry.name}`;
+      if (entry.kind === "dir") await scan(path, index, sourceAliases);
+      else {
+        const suffix = /\.([^.]+)\.json$/.exec(path)?.[1];
+        const type = suffix ? types[suffix] : /\.(wav|ogg|mp3|flac|opus)$/i.test(path) ? "AudioClip" : void 0;
+        if (!type) continue;
+        let id = path;
+        if (await fs.exists(`${path}.meta`)) {
+          const meta = JSON.parse(await fs.readText(`${path}.meta`));
+          if (typeof meta.guid !== "string" || !meta.guid)
+            throw new ShardError(
+              "audio-editor/invalid-document",
+              "Audio sidecar has no stable GUID",
+              {
+                path: `${path}.meta`,
+                hint: "Restore its GUID or re-import the source through the project host."
+              }
+            );
+          id = meta.guid;
+        }
+        if (index.has(id) && index.get(id).path !== path)
+          throw new ShardError("audio-editor/invalid-document", "Audio sources share a GUID", {
+            path: `${path}.meta`,
+            hint: "Assign a unique GUID to the copied asset before importing it."
+          });
+        index.set(id, { path, type, name: entry.name });
+        sourceAliases.set(path, id);
+      }
+    }
+  };
+  for (const root of manifest.assetRoots) await scan(root);
+  const lookup = (id) => {
+    if (catalogError) throw catalogError;
+    const item = paths.get(id) ?? paths.get(aliases.get(id) ?? "");
+    if (!item)
+      throw new ShardError("audio-editor/asset-unavailable", `Unknown project audio asset: ${id}`, {
+        path: id,
+        hint: "Import it into a project asset root first."
+      });
+    return item;
+  };
+  const read = async (id, signal) => {
+    check(signal);
+    const item = lookup(id);
+    if (item.type === "AudioClip")
+      throw new ShardError(
+        "audio-editor/invalid-document",
+        "A clip is not an authored audio document",
+        { path: id }
+      );
+    const text = await fs.readText(item.path);
+    check(signal);
+    return {
+      id,
+      name: item.name,
+      type: item.type,
+      revision: await revision(text),
+      value: JSON.parse(text),
+      sourceText: text
+    };
+  };
+  let pending = Promise.resolve();
+  const documents = {
+    scope,
+    atomic: false,
+    read,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    ...fs.writable ? {
+      commit(changes, signal) {
+        const operation = pending.then(async () => {
+          check(signal);
+          if (changes.length !== 1)
+            throw new ShardError(
+              "audio-editor/unsupported-capability",
+              "Project files do not support atomic multi-document commits"
+            );
+          const change = changes[0];
+          if (change.expectedRevision === null) {
+            if (paths.has(change.document.id) || aliases.has(change.document.id))
+              throw new ShardError("audio-editor/conflict", "This document ID already exists");
+            const extension = Object.entries(types).find(
+              ([, type]) => type === change.document.type
+            )?.[0];
+            if (!extension)
+              throw new ShardError(
+                "audio-editor/unsupported-schema",
+                "This type is not an audio source document"
+              );
+            if (!fs.remove)
+              throw new ShardError(
+                "audio-editor/unsupported-capability",
+                "Creating project sources requires rollback-capable file access"
+              );
+            let directory;
+            for (const root of manifest.assetRoots) {
+              if (await fs.exists(root)) {
+                directory = root;
+                break;
+              }
+            }
+            if (!directory)
+              throw new ShardError(
+                "audio-editor/unsupported-capability",
+                "Create a project asset root before adding audio documents"
+              );
+            const stem = change.document.name.replace(/\.(audio-[a-z]+\.)?json$/i, "").replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "audio";
+            let path = `${directory}/${stem}.${extension}.json`;
+            let suffix = 1;
+            while (await fs.exists(path) || await fs.exists(`${path}.meta`))
+              path = `${directory}/${stem}-${suffix++}.${extension}.json`;
+            const text2 = `${JSON.stringify(change.document.value, null, 2)}
+`;
+            check(signal);
+            try {
+              await fs.writeText(
+                `${path}.meta`,
+                `${JSON.stringify({ guid: change.document.id, importer: `data/${extension}`, settings: {} }, null, 2)}
+`
+              );
+              await fs.writeText(path, text2);
+            } catch (cause) {
+              await fs.remove(path);
+              await fs.remove(`${path}.meta`);
+              throw cause;
+            }
+            const name = path.slice(directory.length + 1);
+            paths.set(change.document.id, { path, type: change.document.type, name });
+            aliases.set(path, change.document.id);
+            const saved2 = {
+              ...change.document,
+              name,
+              revision: await revision(text2),
+              sourceText: text2
+            };
+            for (const listener of listeners) listener([saved2.id]);
+            return [saved2];
+          }
+          const current = await read(change.document.id, signal);
+          if (current.revision !== change.expectedRevision)
+            throw new ShardError(
+              "audio-editor/conflict",
+              "The source changed outside this editor",
+              { path: change.document.id, hint: "Reload the remote version before saving." }
+            );
+          if (JSON.stringify(current.value) === JSON.stringify(change.document.value))
+            return [current];
+          check(signal);
+          const text = `${JSON.stringify(change.document.value, null, 2)}
+`;
+          await fs.writeText(lookup(change.document.id).path, text);
+          const saved = { ...change.document, revision: await revision(text), sourceText: text };
+          for (const listener of listeners) listener([saved.id]);
+          return [saved];
+        });
+        pending = operation.then(
+          () => {
+          },
+          () => {
+          }
+        );
+        return operation;
+      }
+    } : {}
+  };
+  const assets = {
+    scope,
+    async list(query) {
+      check(query.signal);
+      if (catalogError) throw catalogError;
+      const all = [...paths].sort(([, a], [, b]) => a.name.localeCompare(b.name)).filter(
+        ([, item]) => (!query.type || item.type === query.type) && (!query.search || item.name.toLowerCase().includes(query.search.toLowerCase()))
+      );
+      const offset = Number(query.cursor ?? 0), limit = Math.min(query.limit ?? 50, 100);
+      return {
+        items: await Promise.all(
+          all.slice(offset, offset + limit).map(([id]) => assets.get(id, query.signal))
+        ),
+        total: all.length,
+        ...offset + limit < all.length ? { nextCursor: String(offset + limit) } : {}
+      };
+    },
+    async get(id, signal) {
+      check(signal);
+      const item = lookup(id);
+      const stat = await fs.stat?.(item.path);
+      return {
+        id,
+        name: item.name,
+        type: item.type,
+        revision: stat ? `${stat.mtime}:${stat.size}` : "project",
+        ...stat ? { bytes: stat.size } : {}
+      };
+    },
+    async resolve(id, signal) {
+      check(signal);
+      const item = lookup(id);
+      if (item.type !== "AudioClip")
+        throw new ShardError(
+          "audio-editor/asset-unavailable",
+          "Only audio clips can resolve playable bytes",
+          { path: id }
+        );
+      const bytes = await fs.readBytes(item.path);
+      check(signal);
+      const meta = await fs.exists(`${item.path}.meta`) ? JSON.parse(await fs.readText(`${item.path}.meta`)) : void 0;
+      const settings = AudioImportSettings.deserialize(meta?.settings ?? {});
+      audioClip(bytes, { ...settings, id });
+      check(signal);
+      return { bytes, settings };
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+  const refresh = () => {
+    const operation = pending.then(async () => {
+      check();
+      const next = /* @__PURE__ */ new Map();
+      const nextAliases = /* @__PURE__ */ new Map();
+      for (const root of manifest.assetRoots) await scan(root, next, nextAliases);
+      check();
+      const changed = [.../* @__PURE__ */ new Set([...paths.keys(), ...next.keys()])];
+      paths.clear();
+      aliases.clear();
+      for (const [id, value] of next) paths.set(id, value);
+      for (const [path, id] of nextAliases) aliases.set(path, id);
+      catalogError = void 0;
+      for (const listener of listeners) listener(changed);
+    });
+    pending = operation.then(
+      () => {
+      },
+      () => {
+      }
+    );
+    return operation;
+  };
+  let refreshing = false, refreshAgain = false;
+  const queueRefresh = () => {
+    if (disposed) return;
+    if (refreshing) {
+      refreshAgain = true;
+      return;
+    }
+    refreshing = true;
+    void refresh().catch((cause) => {
+      if (disposed) return;
+      catalogError = new ShardError(
+        "audio-editor/asset-unavailable",
+        "The project audio catalog could not refresh",
+        { cause, hint: "Check changed audio sidecars and refresh the project." }
+      );
+      for (const listener of listeners) listener([...paths.keys()]);
+    }).finally(() => {
+      refreshing = false;
+      if (refreshAgain) {
+        refreshAgain = false;
+        queueRefresh();
+      }
+    });
+  };
+  const watchers = [];
+  try {
+    if (fs.watch)
+      for (const root of manifest.assetRoots) {
+        if (!await fs.exists(root)) continue;
+        watchers.push(
+          await fs.watch(root, (event) => {
+            const id = aliases.get(event.path);
+            if (event.kind !== "modify" || event.path.endsWith(".meta") || !id) queueRefresh();
+            else for (const listener of listeners) listener([id]);
+          })
+        );
+      }
+  } catch (error) {
+    for (const unwatch of watchers) unwatch();
+    throw error;
+  }
+  return {
+    name: manifest.name,
+    documents,
+    assets,
+    refresh,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const unwatch of watchers) unwatch();
+      listeners.clear();
+    }
+  };
+}
+export {
+  openAudioProject
+};

package/dist/schema.d.ts

@@ -0,0 +1,22 @@
+import type { DataType } from '@aethervtt/shard-assets';
+import { type Fields, type JsonObject, ShardError } from '@aethervtt/shard-core';
+import type { AudioAssetCatalog, AudioDocument, AudioDocumentStore } from './types.js';
+export declare const audioEditorTypes: readonly DataType[];
+export declare function getAudioEditorSchema(type: string): DataType | undefined;
+export declare function editorError(code: string, message: string, path?: string, cause?: unknown): ShardError;
+export declare function asEditorError(error: unknown): ShardError;
+export declare function clone<T>(value: T): T;
+export declare function equal(a: unknown, b: unknown): boolean;
+export declare function merge(base: JsonObject, overrides: JsonObject): JsonObject;
+export declare function knownFields(fields: Fields, value: JsonObject): JsonObject;
+export interface AudioReference {
+    id: string;
+    type: string;
+    path: string;
+}
+export declare function audioDocumentReferences(fields: Fields, value: JsonObject, prefix?: string): AudioReference[];
+export declare function materializeAudioDocument(document: AudioDocument, documents: AudioDocumentStore, signal?: AbortSignal, chain?: string[]): Promise<AudioDocument>;
+export declare function validateAudioDocument(document: AudioDocument, documents: AudioDocumentStore, assets: AudioAssetCatalog, signal?: AbortSignal): Promise<{
+    effective?: AudioDocument;
+    errors: ShardError[];
+}>;