@aethervtt/shard-platform-web 0.1.0 → 0.2.1

package/dist/audio.js

@@ -1,275 +1,862 @@
 import { ShardError } from "@aethervtt/shard-core";
-const GESTURES = ["pointerdown", "keydown", "touchend"];
-const SMOOTH = 0.015;
-const MIN_FADE = 8e-3;
-const MIME = {
-  wav: "audio/wav",
-  vorbis: 'audio/ogg; codecs="vorbis"',
-  opus: 'audio/ogg; codecs="opus"',
-  mp3: "audio/mpeg",
-  flac: "audio/flac"
-};
-function createWebAudioBackend(options = {}) {
-  const ctx = options.context ?? new AudioContext({ latencyHint: "interactive" });
-  const output = ctx.createGain();
-  output.connect(ctx.destination);
-  const buses = /* @__PURE__ */ new Map();
-  const busGains = /* @__PURE__ */ new Map();
-  const voices = /* @__PURE__ */ new Map();
-  const decoded = /* @__PURE__ */ new WeakMap();
-  const urls = /* @__PURE__ */ new WeakMap();
-  let next = 1;
-  const report = (err) => {
-    if (backend.onError) backend.onError(err);
-    else console.error(err);
+import { validateAudioAutomation } from "@aethervtt/shard-platform";
+import { AudioCache } from "./audio-cache.js";
+import { holdAudioParam, setListenerPose } from "./audio-compat.js";
+import { WebAudioGraph } from "./audio-graph.js";
+function automatedValue(track, at) {
+  if (at < track.command.at)
+    return track.previous ? automatedValue(track.previous, at) : track.start;
+  const command = track.command, start = track.start;
+  const t = command.duration > 0 ? Math.max(0, Math.min(1, (at - command.at) / command.duration)) : 1;
+  if (command.curve === "equal-power-in")
+    return start + (command.value - start) * Math.sin(t * Math.PI / 2);
+  if (command.curve === "equal-power-out")
+    return command.value + (start - command.value) * Math.cos(t * Math.PI / 2);
+  if (command.curve === "exponential" && start > 0 && command.value > 0)
+    return start * (command.value / start) ** t;
+  return start + (command.value - start) * t;
+}
+const gestures = ["pointerdown", "keydown", "touchend"];
+const identity = new Float64Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0]);
+class WebSession {
+  kind = "web";
+  runtime = this;
+  context;
+  output;
+  clock;
+  capabilities;
+  host;
+  root;
+  onError;
+  disposed = false;
+  nextId = 1;
+  voices = /* @__PURE__ */ new Map();
+  statuses = /* @__PURE__ */ new Map();
+  buses = /* @__PURE__ */ new Map();
+  busGains = /* @__PURE__ */ new Map();
+  leases = /* @__PURE__ */ new Set();
+  wakes = /* @__PURE__ */ new Set();
+  retired = /* @__PURE__ */ new Map();
+  timers = /* @__PURE__ */ new Set();
+  listener = identity.slice();
+  meters = /* @__PURE__ */ new Map();
+  graph = null;
+  graphRevision = 0;
+  reserved = 0;
+  group = 0;
+  ordinal;
+  priority;
+  maxVoices;
+  budgetBytes;
+  pendingStarts = /* @__PURE__ */ new Set();
+  ownPreparedBytes = 0;
+  preparationPins = /* @__PURE__ */ new Map();
+  constructor(host, root, options = {}) {
+    this.host = host;
+    this.ordinal = host.nextSession++;
+    this.priority = options.priority ?? 0;
+    if (!Number.isFinite(this.priority))
+      throw new ShardError("audio/invalid-range", "Session priority must be finite");
+    this.root = root;
+    this.context = host.context;
+    this.output = host.context.createGain();
+    this.output.connect(host.output);
+    this.maxVoices = options.maxVoices ?? 64;
+    this.budgetBytes = options.decodedBudgetBytes ?? host.cache.budgetBytes;
+    this.capabilities = {
+      scheduled: true,
+      automation: true,
+      mixer: true,
+      media: !host.offline,
+      meters: !host.offline,
+      offline: host.offline,
+      sessions: root && host.fixedListener
+    };
+    this.clock = {
+      now: () => this.context.currentTime,
+      wallNow: () => performance.now() / 1e3,
+      wake: (callback, seconds) => {
+        if (host.offline || this.disposed) return () => {
+        };
+        const handle = setInterval(callback, Math.max(1, seconds * 1e3));
+        this.wakes.add(handle);
+        return () => {
+          clearInterval(handle);
+          this.wakes.delete(handle);
+        };
+      }
+    };
+    if (!host.offline) this.wakes.add(setInterval(this.maintainGraphs, 20));
+    host.sessions.add(this);
+    this.context.addEventListener("statechange", this.stateChanged);
+    if (!host.offline)
+      for (const gesture of gestures)
+        window.addEventListener(gesture, this.unlock, { capture: true });
+  }
+  get activeVoices() {
+    return this.voices.size;
+  }
+  get state() {
+    if (this.disposed || this.context.state === "closed") return "closed";
+    return this.host.offline || this.context.state === "running" ? "running" : "suspended";
+  }
+  createSession(options) {
+    if (!this.root || !this.host.fixedListener || this.disposed)
+      throw new ShardError(
+        "audio/unsupported-capability",
+        "Independent sessions require a managed fixed listener",
+        { hint: "Use a Shard-owned context or grant fixedListener ownership." }
+      );
+    return new WebSession(this.host, false, options);
+  }
+  unlock = () => {
+    void this.resume().catch(this.report);
   };
-  const resume = async () => {
-    if (ctx.state !== "running" && ctx.state !== "closed") await ctx.resume().catch(() => {
-    });
+  report = (error) => {
+    this.onError?.(
+      error instanceof ShardError ? error : new ShardError("audio/prepare-failed", "Audio operation failed", { cause: error })
+    );
   };
-  const onGesture = () => void resume();
-  for (const g of GESTURES) window.addEventListener(g, onGesture, { capture: true });
-  ctx.addEventListener("statechange", () => {
-    if (ctx.state === "running") {
-      for (const g of GESTURES) window.removeEventListener(g, onGesture, { capture: true });
-      for (const voice of voices.values()) if (!voice.started) start(voice);
-    }
-  });
-  function bus(name) {
-    let node = buses.get(name);
+  stateChanged = () => {
+    this.maintainGraphs();
+    if (this.state === "running")
+      for (const voice of this.voices.values()) {
+        if (!voice.started && !voice.loading) this.start(voice);
+        else if (voice.started && voice.presentation.state === "blocked")
+          voice.presentation.state = voice.presentation.scheduledAt > this.context.currentTime ? "scheduled" : "rendering";
+      }
+    else
+      for (const voice of this.voices.values())
+        if (voice.presentation.state === "rendering" || voice.presentation.state === "scheduled")
+          voice.presentation.state = "blocked";
+  };
+  async resume() {
+    if (this.host.offline || this.state === "running") return;
+    if (this.state === "closed") throw new ShardError("audio/prepare-failed", "Audio is closed");
+    await this.context.resume();
+  }
+  busNode(name) {
+    const output = this.graph?.outputs.get(name);
+    if (output) return output;
+    let node = this.buses.get(name);
     if (!node) {
-      node = ctx.createGain();
-      node.gain.value = busGains.get(name) ?? 1;
-      node.connect(output);
-      buses.set(name, node);
+      node = this.context.createGain();
+      node.gain.value = this.busGains.get(name) ?? 1;
+      node.connect(this.output);
+      this.buses.set(name, node);
     }
     return node;
   }
-  function decode(clip) {
-    let p = decoded.get(clip.bytes);
-    if (!p) {
-      const copy = clip.bytes.slice().buffer;
-      p = ctx.decodeAudioData(copy).then(
-        (buffer) => ({ buffer, norm: clip.normalize ? normalization(buffer) : 1 }),
-        (cause) => {
-          throw new ShardError("audio/decode-failed", `Can't decode ${clip.id} (${clip.codec})`, {
-            hint: clip.codec === "opus" ? "This browser can't decode Opus (Safari before 18.4). Use Ogg Vorbis or MP3." : "The file may be damaged, or this browser lacks the codec. Re-export it as Ogg Vorbis or MP3.",
-            cause
-          });
-        }
+  input(name) {
+    if (!this.graph) return this.busNode(name);
+    const input = this.graph.inputs.get(name);
+    if (!input) throw new ShardError("audio/unknown-bus", `No ordinary mixer input ${name}`);
+    return input;
+  }
+  place(voice) {
+    const panner = voice.panner;
+    if (!panner) return;
+    let x = voice.params.x, y = voice.params.y, z = voice.params.z;
+    if (this.host.fixedListener) {
+      const m = this.listener;
+      const dx = x - m[3], dy = y - m[7], dz = z - m[11];
+      const sx = Math.sqrt(m[0] ** 2 + m[4] ** 2 + m[8] ** 2) || 1;
+      const sy = Math.sqrt(m[1] ** 2 + m[5] ** 2 + m[9] ** 2) || 1;
+      const sz = Math.sqrt(m[2] ** 2 + m[6] ** 2 + m[10] ** 2) || 1;
+      x = (dx * m[0] + dy * m[4] + dz * m[8]) / sx;
+      y = (dx * m[1] + dy * m[5] + dz * m[9]) / sy;
+      z = (dx * m[2] + dy * m[6] + dz * m[10]) / sz;
+    }
+    const at = this.context.currentTime;
+    if (panner.positionX) {
+      panner.positionX.setValueAtTime(x, at);
+      panner.positionY.setValueAtTime(y, at);
+      panner.positionZ.setValueAtTime(z, at);
+    } else panner.setPosition(x, y, z);
+  }
+  validateRoutes(desc) {
+    if ((desc.sends?.length ?? 0) > 8 || new Set(desc.sends?.map((send) => send.target)).size !== (desc.sends?.length ?? 0))
+      throw new ShardError("audio/capacity", "At most eight voice sends");
+    for (const send of desc.sends ?? []) {
+      if (!Number.isFinite(send.gain) || send.gain < 0 || send.gain > 16 || !this.graph?.sendInputs.get(desc.bus)?.has(send.target))
+        throw new ShardError("audio/unknown-bus", `Invalid voice send ${desc.bus}/${send.target}`);
+    }
+  }
+  route(voice) {
+    voice.highpass.disconnect();
+    voice.panner?.disconnect();
+    for (const [target, node] of voice.sends)
+      if (!voice.desc.sends?.some((send) => send.target === target)) {
+        node.disconnect();
+        voice.sends.delete(target);
+      }
+    const spatial = voice.desc.spatial;
+    if (spatial) {
+      const node = voice.panner ?? this.context.createPanner();
+      voice.panner = node;
+      node.panningModel = spatial.panning === "hrtf" ? "HRTF" : "equalpower";
+      node.distanceModel = spatial.distanceModel;
+      node.refDistance = Math.max(1e-5, spatial.refDistance);
+      node.maxDistance = Math.max(spatial.maxDistance, node.refDistance + 1e-5);
+      node.rolloffFactor = spatial.rolloffFactor;
+      this.place(voice);
+      voice.highpass.connect(node).connect(this.input(voice.desc.bus));
+    } else {
+      voice.panner = null;
+      voice.highpass.connect(this.input(voice.desc.bus));
+    }
+    for (const send of voice.desc.sends ?? []) {
+      let node = voice.sends.get(send.target);
+      if (!node) {
+        node = this.context.createGain();
+        node.gain.value = send.gain;
+        voice.sends.set(send.target, node);
+      } else {
+        node.disconnect();
+        holdAudioParam(node.gain, this.context.currentTime);
+        node.gain.setValueAtTime(send.gain, this.context.currentTime);
+      }
+      const input = this.graph?.sendInputs.get(voice.desc.bus)?.get(send.target);
+      if (!input) throw new ShardError("audio/unknown-bus", `Missing voice send ${send.target}`);
+      (voice.panner ?? voice.highpass).connect(node).connect(input);
+    }
+  }
+  setVoiceSend(id, target, gain, seconds) {
+    if (!Number.isFinite(gain) || gain < 0 || gain > 16 || !Number.isFinite(seconds) || seconds < 0)
+      throw new ShardError("audio/invalid-range", "Invalid voice send automation");
+    const node = this.voices.get(id)?.sends.get(target);
+    if (!node) throw new ShardError("audio/unknown-bus", `Missing voice send ${target}`);
+    const at = this.context.currentTime;
+    holdAudioParam(node.gain, at);
+    if (seconds) node.gain.linearRampToValueAtTime(gain, at + seconds);
+    else node.gain.setValueAtTime(gain, at);
+  }
+  setDecodedBudget(bytes) {
+    if (!Number.isFinite(bytes) || bytes < this.ownPreparedBytes)
+      throw new ShardError("audio/memory-budget", "Budget is invalid or below pinned PCM");
+    this.budgetBytes = bytes;
+  }
+  reserveVoices(count) {
+    if (!Number.isInteger(count) || count < 1 || this.voices.size + this.reserved + count > this.maxVoices)
+      throw new ShardError("audio/capacity", "Physical voice reservation cannot fit");
+    const needed = Math.max(0, this.host.voices + this.host.reserved + count - this.host.maxVoices);
+    if (needed) {
+      const candidates = [];
+      for (const session of this.host.sessions) {
+        if (session === this || session.priority > this.priority || session.priority === this.priority && session.ordinal < this.ordinal)
+          continue;
+        for (const voice of session.voices.values()) candidates.push({ session, voice });
+      }
+      candidates.sort(
+        (a, b) => a.session.priority - b.session.priority || b.session.ordinal - a.session.ordinal || b.voice.id - a.voice.id
       );
-      decoded.set(clip.bytes, p);
+      if (candidates.length < needed)
+        throw new ShardError("audio/capacity", "Higher-ranked sessions own the host voice budget");
+      let freed = 0;
+      for (let i = 0; i < candidates.length && freed < needed; i++) {
+        const victim = candidates[i];
+        if (victim.voice.finished) continue;
+        for (const voice of victim.session.voices.values())
+          if (voice.group === victim.voice.group) {
+            voice.presentation.error = "audio/host-stolen";
+            victim.session.finish(voice);
+            freed++;
+          }
+      }
+    }
+    const previous = this.reserved;
+    this.group++;
+    this.reserved += count;
+    this.host.reserved += count;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      const unused = Math.max(0, this.reserved - previous);
+      this.reserved -= unused;
+      this.host.reserved -= unused;
+    };
+  }
+  play(desc) {
+    if (this.disposed) throw new ShardError("audio/prepare-failed", "Audio session is disposed");
+    if (this.voices.size >= this.maxVoices)
+      throw new ShardError("audio/capacity", "Physical audio voice budget is exhausted", {
+        hint: "Release a voice or increase the session/host voice budget."
+      });
+    if (this.host.offline && desc.clip.stream)
+      throw new ShardError("audio/unsupported-capability", "Offline rendering needs decoded clips");
+    this.input(desc.bus);
+    this.validateRoutes(desc);
+    if (!this.reserved) this.reserveVoices(1);
+    this.reserved--;
+    this.host.reserved--;
+    const id = this.nextId++;
+    const gain = this.context.createGain();
+    gain.gain.value = desc.gain;
+    const lowpass = this.context.createBiquadFilter();
+    lowpass.type = "lowpass";
+    lowpass.frequency.value = desc.lowpass ?? this.context.sampleRate / 2;
+    const highpass = this.context.createBiquadFilter();
+    highpass.type = "highpass";
+    highpass.frequency.value = desc.highpass ?? 0;
+    const envelope = this.context.createGain();
+    gain.connect(envelope).connect(lowpass).connect(highpass);
+    const presentation = {
+      state: "preparing",
+      scheduledAt: desc.when ?? this.context.currentTime,
+      endedAt: -1,
+      error: null
+    };
+    const voice = {
+      group: this.group,
+      id,
+      desc: { ...desc },
+      params: { gain: desc.gain, pitch: desc.pitch, x: desc.x, y: desc.y, z: desc.z },
+      gain,
+      envelope,
+      lowpass,
+      highpass,
+      sends: /* @__PURE__ */ new Map(),
+      panner: null,
+      source: null,
+      media: null,
+      mediaNode: null,
+      lease: null,
+      presentation,
+      loading: false,
+      started: false,
+      finished: false,
+      norm: 1,
+      requestedAt: performance.now(),
+      timer: null,
+      automation: [],
+      tracks: /* @__PURE__ */ new Map()
+    };
+    this.voices.set(id, voice);
+    this.statuses.set(id, presentation);
+    this.host.voices++;
+    try {
+      this.route(voice);
+      this.start(voice);
+    } catch (error) {
+      this.finish(voice);
+      throw error;
+    }
+    return id;
+  }
+  start(voice) {
+    if (voice.finished || voice.started || voice.loading) return;
+    if (this.state !== "running") {
+      voice.presentation.state = "blocked";
+      return;
+    }
+    const ready = this.host.cache.acquireReady(voice.desc.clip);
+    if (ready) {
+      this.startPrepared(voice, this.ownLease(ready));
+      return;
+    }
+    voice.loading = true;
+    const pending = this.acquireOwned(voice.desc.clip).then((lease) => this.startPrepared(voice, lease)).catch((error) => this.fail(voice, error)).finally(() => this.pendingStarts.delete(pending));
+    this.pendingStarts.add(pending);
+  }
+  startPrepared(voice, lease) {
+    voice.loading = false;
+    if (voice.finished || this.disposed) {
+      lease.release();
+      return;
+    }
+    voice.lease = lease;
+    const desc = voice.desc, now = this.context.currentTime;
+    let offset = desc.offset;
+    if (desc.when === void 0 && !this.host.offline)
+      offset += (performance.now() - voice.requestedAt) / 1e3 * voice.params.pitch;
+    const end = desc.clip.loopEnd || desc.clip.duration, start = desc.clip.loopStart;
+    if (desc.loop && offset >= end) offset = start + (offset - start) % (end - start);
+    if (!desc.loop && offset >= desc.clip.duration) {
+      this.finish(voice);
+      return;
     }
-    return p;
-  }
-  function mediaUrl(clip) {
-    let url = urls.get(clip.bytes);
-    if (!url) {
-      const blob = new Blob([clip.bytes.slice().buffer], { type: MIME[clip.codec] ?? "audio/*" });
-      url = URL.createObjectURL(blob);
-      urls.set(clip.bytes, url);
+    if (this.state !== "running") {
+      voice.lease.release();
+      voice.lease = null;
+      voice.presentation.state = "blocked";
+      return;
     }
-    return url;
-  }
-  function offsetNow(voice, duration) {
-    const d = voice.desc;
-    let t = d.offset + (performance.now() - voice.requestedAt) / 1e3 * voice.params.pitch;
-    if (!d.loop) return t;
-    const end = d.clip.loopEnd > 0 ? Math.min(d.clip.loopEnd, duration) : duration;
-    const begin = d.clip.loopEnd > 0 && d.clip.loopStart < end ? d.clip.loopStart : 0;
-    if (t >= end && end > begin) t = begin + (t - end) % (end - begin);
-    return t;
-  }
-  function start(voice) {
-    if (voice.stopped || voice.started || ctx.state !== "running") return;
-    const d = voice.desc;
-    if (d.clip.stream) {
+    if (desc.clip.stream) {
+      const media = new Audio(lease.value.url);
+      voice.media = media;
+      media.loop = desc.loop;
+      media.preservesPitch = false;
+      media.playbackRate = voice.params.pitch;
+      media.currentTime = offset;
+      voice.mediaNode = this.context.createMediaElementSource(media);
+      voice.mediaNode.connect(voice.gain);
+      media.onended = () => this.finish(voice);
+      media.onerror = () => this.fail(voice, new ShardError("audio/decode-failed", `Cannot play ${desc.clip.id}`));
       voice.started = true;
-      const el = new Audio(mediaUrl(d.clip));
-      el.loop = d.loop;
-      el.preservesPitch = false;
-      el.playbackRate = voice.params.pitch;
-      el.currentTime = offsetNow(voice, d.clip.duration) % Math.max(d.clip.duration, 1e-3);
-      ctx.createMediaElementSource(el).connect(voice.gain);
-      voice.element = el;
-      el.play().catch(
-        (cause) => report(
-          new ShardError("audio/decode-failed", `Can't stream ${d.clip.id} (${d.clip.codec})`, {
-            cause
-          })
-        )
+      void media.play().then(
+        () => {
+          if (!voice.finished) voice.presentation.state = "rendering";
+        },
+        (error) => this.fail(voice, error)
       );
+    } else {
+      const source = this.context.createBufferSource();
+      voice.source = source;
+      source.buffer = lease.value.buffer;
+      source.loop = desc.loop;
+      source.loopStart = start;
+      source.loopEnd = end;
+      source.playbackRate.value = voice.params.pitch;
+      voice.norm = desc.clip.normalize && lease.value.peak > 0 ? 1 / lease.value.peak : 1;
+      voice.gain.gain.value = voice.params.gain * voice.norm;
+      source.connect(voice.gain);
+      source.onended = () => this.finish(voice);
+      if (desc.when !== void 0 && desc.when < now)
+        throw new ShardError("audio/music-late", "Prepared source missed its scheduled start");
+      const when = desc.when ?? now;
+      voice.presentation.scheduledAt = when;
+      voice.presentation.state = when > now ? "scheduled" : "rendering";
+      voice.started = true;
+      for (const command of voice.automation) this.automate(voice.id, command);
+      voice.automation.length = 0;
+      source.start(when, offset);
+      if (desc.duration !== void 0) source.stop(when + desc.duration);
+    }
+  }
+  fail(voice, error) {
+    if (voice.finished) return;
+    voice.presentation.error = error instanceof ShardError ? error.code : "audio/decode-failed";
+    this.finish(voice, true);
+    this.report(error);
+  }
+  finish(voice, failed = false) {
+    if (voice.finished) return;
+    voice.finished = true;
+    if (voice.timer !== null) clearTimeout(voice.timer);
+    if (voice.source) {
+      voice.source.onended = null;
+      try {
+        voice.source.stop();
+      } catch {
+      }
+      voice.source.disconnect();
+    }
+    if (voice.media) {
+      voice.media.onended = null;
+      voice.media.onerror = null;
+      voice.media.pause();
+      voice.media.removeAttribute("src");
+      voice.media.load();
+    }
+    voice.mediaNode?.disconnect();
+    voice.gain.disconnect();
+    voice.envelope.disconnect();
+    voice.lowpass.disconnect();
+    voice.highpass.disconnect();
+    voice.panner?.disconnect();
+    for (const node of voice.sends.values()) node.disconnect();
+    voice.sends.clear();
+    voice.lease?.release();
+    voice.lease = null;
+    this.voices.delete(voice.id);
+    this.host.voices--;
+    voice.presentation.state = failed ? "failed" : "ended";
+    voice.presentation.endedAt = this.context.currentTime;
+    if (this.statuses.size > 4096)
+      for (const [id, status] of this.statuses) {
+        if (status.state === "ended" || status.state === "failed") this.statuses.delete(id);
+        if (this.statuses.size <= 4096) break;
+      }
+  }
+  stop(id, fade = 0) {
+    const voice = this.voices.get(id);
+    if (!voice || voice.finished) return;
+    if (fade <= 0 || !voice.started || this.state !== "running") {
+      this.finish(voice);
       return;
     }
-    decode(d.clip).then(
-      ({ buffer, norm }) => {
-        if (voice.stopped || voice.started || ctx.state !== "running") return;
-        const offset = offsetNow(voice, buffer.duration);
-        if (!d.loop && offset >= buffer.duration) return;
-        voice.started = true;
-        voice.norm = norm;
-        voice.gain.gain.value = voice.params.gain * norm;
-        const src = ctx.createBufferSource();
-        src.buffer = buffer;
-        src.loop = d.loop;
-        if (d.loop && d.clip.loopEnd > 0) {
-          src.loopStart = d.clip.loopStart;
-          src.loopEnd = d.clip.loopEnd;
-        }
-        src.playbackRate.value = voice.params.pitch;
-        src.connect(voice.gain);
-        src.start(0, offset);
-        voice.source = src;
+    voice.presentation.state = "stopping";
+    const at = this.context.currentTime;
+    holdAudioParam(voice.gain.gain, at);
+    voice.gain.gain.linearRampToValueAtTime(0, at + fade);
+    if (voice.source) voice.source.stop(at + fade);
+    if (voice.media && !this.host.offline) {
+      if (voice.timer !== null) clearTimeout(voice.timer);
+      const finishAt = at + fade;
+      const poll = () => {
+        if (this.context.currentTime >= finishAt) this.finish(voice);
+        else voice.timer = setTimeout(poll, 25);
+      };
+      voice.timer = setTimeout(poll, 25);
+    }
+  }
+  cancel(id) {
+    const voice = this.voices.get(id);
+    if (!voice) return "ended";
+    const started = voice.started && this.context.currentTime >= voice.presentation.scheduledAt;
+    this.stop(id, started ? 0.01 : 0);
+    return started ? "already-started" : "cancelled";
+  }
+  async flush() {
+    await Promise.all(this.pendingStarts);
+    for (const status of this.statuses.values())
+      if (status.state === "failed")
+        throw new ShardError(
+          status.error ?? "audio/prepare-failed",
+          "Audio source preparation failed"
+        );
+  }
+  presentation(id) {
+    const status = this.statuses.get(id);
+    if (status && this.state !== "running" && this.voices.has(id)) {
+      if (status.state === "rendering" || status.state === "scheduled") status.state = "blocked";
+    } else if (status?.state === "scheduled" && this.context.currentTime >= status.scheduledAt)
+      status.state = "rendering";
+    return status;
+  }
+  update(id, params) {
+    const voice = this.voices.get(id);
+    if (!voice) return;
+    const at = this.context.currentTime;
+    if (voice.params.gain !== params.gain)
+      voice.gain.gain.setTargetAtTime(params.gain * voice.norm, at, 0.015);
+    if (voice.params.pitch !== params.pitch) {
+      voice.source?.playbackRate.setValueAtTime(params.pitch, at);
+      if (voice.media) voice.media.playbackRate = params.pitch;
+    }
+    voice.params.gain = params.gain;
+    voice.params.pitch = params.pitch;
+    voice.params.x = params.x;
+    voice.params.y = params.y;
+    voice.params.z = params.z;
+    this.place(voice);
+  }
+  reconfigure(id, desc) {
+    const voice = this.voices.get(id);
+    if (!voice || voice.desc.clip.bytes !== desc.clip.bytes) return false;
+    this.input(desc.bus);
+    this.validateRoutes(desc);
+    voice.desc = { ...voice.desc, ...desc };
+    if (voice.source) {
+      voice.source.loop = desc.loop;
+      voice.source.loopStart = desc.clip.loopStart;
+      voice.source.loopEnd = desc.clip.loopEnd || desc.clip.duration;
+    }
+    if (voice.media) voice.media.loop = desc.loop;
+    this.route(voice);
+    this.update(id, desc);
+    return true;
+  }
+  automate(id, command) {
+    validateAudioAutomation(command);
+    const voice = this.voices.get(id);
+    if (!voice) return;
+    if (!voice.source && !voice.media) {
+      if (voice.automation.length >= 128)
+        throw new ShardError("audio/capacity", "Voice automation queue is full");
+      voice.automation.push({ ...command });
+      return;
+    }
+    const param = command.property === "envelope" ? voice.envelope.gain : command.property === "gain" ? voice.gain.gain : command.property === "pitch" ? voice.source?.playbackRate : command.property === "lowpass" ? voice.lowpass.frequency : voice.highpass.frequency;
+    if (!param)
+      throw new ShardError(
+        "audio/unsupported-capability",
+        "Pitch automation needs a prepared decoded source"
+      );
+    const value = command.value * (command.property === "gain" ? voice.norm : 1);
+    const previous = voice.tracks.get(command.property);
+    if (previous && this.context.currentTime >= previous.command.at) {
+      previous.previous = null;
+      previous.depth = 1;
+    }
+    const depth = command.at > this.context.currentTime ? (previous?.depth ?? 0) + 1 : 1;
+    if (depth > 128)
+      throw new ShardError("audio/capacity", "Voice future automation capacity reached");
+    const initial = command.property === "envelope" ? 1 : command.property === "gain" ? voice.params.gain * voice.norm : command.property === "pitch" ? voice.params.pitch : command.property === "lowpass" ? voice.desc.lowpass ?? this.context.sampleRate / 2 : voice.desc.highpass ?? 0;
+    const start = previous ? automatedValue(previous, command.at) : initial;
+    voice.tracks.set(command.property, {
+      depth,
+      command: { ...command, value },
+      start,
+      previous: command.at > this.context.currentTime ? previous ?? null : null
+    });
+    holdAudioParam(param, command.at, start);
+    param.setValueAtTime(start, command.at);
+    if (command.duration <= 0) param.setValueAtTime(value, command.at);
+    else if (command.curve === "exponential")
+      param.exponentialRampToValueAtTime(Math.max(value, 1e-6), command.at + command.duration);
+    else if (command.curve === "equal-power-in" || command.curve === "equal-power-out") {
+      const samples = new Float32Array(129);
+      for (let i = 0; i < samples.length; i++) {
+        const phase = i / (samples.length - 1) * Math.PI / 2;
+        samples[i] = command.curve === "equal-power-in" ? start + (value - start) * Math.sin(phase) : value + (start - value) * Math.cos(phase);
+      }
+      param.setValueCurveAtTime(samples, command.at, command.duration);
+    } else param.linearRampToValueAtTime(value, command.at + command.duration);
+  }
+  setListener(matrix) {
+    for (let i = 0; i < 12; i++) this.listener[i] = matrix[i];
+    if (this.host.fixedListener) for (const voice of this.voices.values()) this.place(voice);
+    else setListenerPose(this.context.listener, matrix);
+  }
+  setBus(name, gain) {
+    this.busGains.set(name, gain);
+    if (!this.graph) this.busNode(name).gain.setTargetAtTime(gain, this.context.currentTime, 0.015);
+  }
+  preload(clip) {
+    void this.prepare(clip).then((lease) => lease.release()).catch(this.report);
+  }
+  async prepare(clip) {
+    return this.acquireOwned(clip);
+  }
+  async acquireOwned(clip) {
+    if (this.disposed) throw new ShardError("audio/prepare-failed", "Session is disposed");
+    return this.ownLease(await this.host.cache.acquire(clip));
+  }
+  ownLease(lease) {
+    const clip = lease.clip;
+    const pinned = this.preparationPins.get(lease.value);
+    if (this.disposed || this.ownPreparedBytes + (pinned ? 0 : lease.decodedBytes) > this.budgetBytes) {
+      lease.release();
+      throw new ShardError(
+        this.disposed ? "audio/prepare-failed" : "audio/memory-budget",
+        "Session cannot retain preparation"
+      );
+    }
+    const pin = pinned ?? { count: 0, bytes: lease.decodedBytes };
+    if (!pinned) {
+      this.preparationPins.set(lease.value, pin);
+      this.ownPreparedBytes += pin.bytes;
+    }
+    pin.count++;
+    let released = false;
+    const owned = {
+      clip,
+      value: lease.value,
+      decodedBytes: lease.decodedBytes,
+      encodedBytes: lease.encodedBytes,
+      sampleRate: lease.sampleRate,
+      samples: lease.samples,
+      channels: lease.channels,
+      get released() {
+        return released;
       },
-      (err) => report(err)
-    );
+      release: () => {
+        if (released) return;
+        released = true;
+        if (--pin.count === 0) {
+          this.preparationPins.delete(lease.value);
+          this.ownPreparedBytes -= pin.bytes;
+        }
+        this.leases.delete(owned);
+        lease.release();
+      }
+    };
+    this.leases.add(owned);
+    return owned;
   }
-  function place(panner, x, y, z, at) {
-    if (panner.positionX) {
-      panner.positionX.setTargetAtTime(x, at, SMOOTH);
-      panner.positionY.setTargetAtTime(y, at, SMOOTH);
-      panner.positionZ.setTargetAtTime(z, at, SMOOTH);
-    } else panner.setPosition(x, y, z);
+  collect() {
+    this.maintainGraphs();
+    this.host.cache.collect();
   }
-  const backend = {
-    kind: "web",
-    context: ctx,
-    output,
-    get state() {
-      const s = ctx.state;
-      return s === "running" ? "running" : s === "closed" ? "closed" : "suspended";
-    },
-    resume,
-    busNode: bus,
-    play(desc) {
-      const id = next++;
-      const gain = ctx.createGain();
-      gain.gain.value = desc.gain;
-      let panner = null;
-      const s = desc.spatial;
-      if (s) {
-        panner = ctx.createPanner();
-        panner.panningModel = s.panning === "hrtf" ? "HRTF" : "equalpower";
-        panner.distanceModel = s.distanceModel;
-        panner.refDistance = s.refDistance;
-        panner.maxDistance = Math.max(s.maxDistance, s.refDistance + 1e-3);
-        panner.rolloffFactor = s.rolloffFactor;
-        if (panner.positionX) {
-          panner.positionX.value = desc.x;
-          panner.positionY.value = desc.y;
-          panner.positionZ.value = desc.z;
-        } else panner.setPosition(desc.x, desc.y, desc.z);
-        gain.connect(panner).connect(bus(desc.bus));
-      } else gain.connect(bus(desc.bus));
-      const voice = {
-        desc,
-        params: { gain: desc.gain, pitch: desc.pitch, x: desc.x, y: desc.y, z: desc.z },
-        gain,
-        panner,
-        source: null,
-        element: null,
-        norm: 1,
-        requestedAt: performance.now(),
-        started: false,
-        stopped: false
-      };
-      voices.set(id, voice);
-      start(voice);
-      return id;
-    },
-    preload(clip) {
-      if (!clip.stream) decode(clip).catch((err) => backend.onError?.(err));
-    },
-    update(id, params) {
-      const v = voices.get(id);
-      if (!v) return;
-      const now = ctx.currentTime;
-      const p = v.params;
-      if (p.gain !== params.gain) v.gain.gain.setTargetAtTime(params.gain * v.norm, now, SMOOTH);
-      if (p.pitch !== params.pitch) {
-        if (v.source) v.source.playbackRate.setTargetAtTime(params.pitch, now, SMOOTH);
-        if (v.element) v.element.playbackRate = params.pitch;
+  memory() {
+    let nodes = 1 + this.buses.size + this.meters.size;
+    for (const voice of this.voices.values())
+      nodes += 4 + voice.sends.size + Number(!!voice.panner) + Number(!!voice.source || !!voice.mediaNode);
+    nodes += this.graph ? this.graph.nodes.length + 1 : 0;
+    for (const graph of this.retired.keys()) nodes += graph.nodes.length + 1;
+    let effectBytes = this.graph?.generatedBytes ?? 0;
+    for (const graph of this.retired.keys()) effectBytes += graph.generatedBytes;
+    return { ...this.host.cache.memory(), effectBytes, voices: this.voices.size, nodes };
+  }
+  async configureMixer(graph) {
+    const revision = ++this.graphRevision, output = this.context.createGain();
+    output.gain.value = 0;
+    output.connect(this.output);
+    let next;
+    try {
+      next = await WebAudioGraph.build(this.context, graph, output, {
+        acquire: (clip) => this.acquireOwned(clip)
+      });
+    } catch (error) {
+      output.disconnect();
+      throw error;
+    }
+    if (this.disposed || revision !== this.graphRevision || next.nodes.length + (this.graph?.nodes.length ?? 0) + [...this.retired.keys()].reduce((sum, graph2) => sum + graph2.nodes.length, 0) > graph.maxNodes || next.generatedBytes + (this.graph?.generatedBytes ?? 0) + [...this.retired.keys()].reduce((sum, old2) => sum + old2.generatedBytes, 0) > 64 * 1024 * 1024) {
+      next.dispose();
+      output.disconnect();
+      throw new ShardError(
+        "audio/mixer-capacity",
+        "Graph replacement cancelled or exceeds overlap budget"
+      );
+    }
+    for (const voice of this.voices.values())
+      if (!next.inputs.has(voice.desc.bus) || [...voice.sends.keys()].some((target) => !next.sendInputs.get(voice.desc.bus)?.has(target))) {
+        next.dispose();
+        output.disconnect();
+        throw new ShardError("audio/unknown-bus", `Graph removes active route ${voice.desc.bus}`);
       }
-      if (v.panner && (p.x !== params.x || p.y !== params.y || p.z !== params.z)) {
-        place(v.panner, params.x, params.y, params.z, now);
+    const old = this.graph;
+    this.graph = next;
+    for (const voice of this.voices.values()) {
+      const input = next.inputs.get(voice.desc.bus);
+      if (input) (voice.panner ?? voice.highpass).connect(input);
+      for (const [target, node] of voice.sends)
+        node.connect(next.sendInputs.get(voice.desc.bus).get(target));
+    }
+    const at = this.context.currentTime, fade = old ? 0.02 : 0;
+    output.gain.setValueAtTime(fade ? 0 : 1, at);
+    if (fade) output.gain.linearRampToValueAtTime(1, at + fade);
+    for (const node of this.buses.values()) node.disconnect();
+    this.buses.clear();
+    for (const meter of this.meters.values()) meter.node.disconnect();
+    this.meters.clear();
+    if (old) {
+      const tailEnd = at + fade + old.tailSeconds;
+      this.retired.set(old, tailEnd + 0.02);
+      for (const input of old.inputs.values()) {
+        holdAudioParam(input.gain, at);
+        input.gain.linearRampToValueAtTime(0, at + fade);
       }
-      p.gain = params.gain;
-      p.pitch = params.pitch;
-      p.x = params.x;
-      p.y = params.y;
-      p.z = params.z;
-    },
-    stop(id, fade = 0) {
-      const v = voices.get(id);
-      if (!v) return;
-      voices.delete(id);
-      v.stopped = true;
-      const now = ctx.currentTime;
-      const f = Math.max(fade, MIN_FADE);
-      v.gain.gain.cancelScheduledValues(now);
-      v.gain.gain.setValueAtTime(v.gain.gain.value, now);
-      v.gain.gain.linearRampToValueAtTime(0, now + f);
-      const release = () => {
-        v.gain.disconnect();
-        v.panner?.disconnect();
-        if (v.element) {
-          v.element.pause();
-          v.element.removeAttribute("src");
+      for (const routes of old.sendInputs.values())
+        for (const input of routes.values()) {
+          holdAudioParam(input.gain, at);
+          input.gain.linearRampToValueAtTime(0, at + fade);
         }
-      };
-      if (v.source) {
-        v.source.onended = release;
-        v.source.stop(now + f);
-      } else setTimeout(release, f * 1e3 + 50);
-    },
-    setListener(m) {
-      const l = ctx.listener;
-      const fl = Math.sqrt(m[2] * m[2] + m[6] * m[6] + m[10] * m[10]) || 1;
-      const ul = Math.sqrt(m[1] * m[1] + m[5] * m[5] + m[9] * m[9]) || 1;
-      const fx = -m[2] / fl;
-      const fy = -m[6] / fl;
-      const fz = -m[10] / fl;
-      const ux = m[1] / ul;
-      const uy = m[5] / ul;
-      const uz = m[9] / ul;
-      if (l.positionX) {
-        const now = ctx.currentTime;
-        l.positionX.setTargetAtTime(m[3], now, SMOOTH);
-        l.positionY.setTargetAtTime(m[7], now, SMOOTH);
-        l.positionZ.setTargetAtTime(m[11], now, SMOOTH);
-        l.forwardX.setTargetAtTime(fx, now, SMOOTH);
-        l.forwardY.setTargetAtTime(fy, now, SMOOTH);
-        l.forwardZ.setTargetAtTime(fz, now, SMOOTH);
-        l.upX.setTargetAtTime(ux, now, SMOOTH);
-        l.upY.setTargetAtTime(uy, now, SMOOTH);
-        l.upZ.setTargetAtTime(uz, now, SMOOTH);
-      } else {
-        l.setPosition(m[3], m[7], m[11]);
-        l.setOrientation(fx, fy, fz, ux, uy, uz);
-      }
-    },
-    setBus(name, gain) {
-      busGains.set(name, gain);
-      bus(name).gain.setTargetAtTime(gain, ctx.currentTime, SMOOTH);
-    },
-    dispose() {
-      for (const g of GESTURES) window.removeEventListener(g, onGesture, { capture: true });
-      for (const id of [...voices.keys()]) backend.stop(id);
-      void ctx.close();
+      old.output.gain.setValueAtTime(1, tailEnd);
+      old.output.gain.linearRampToValueAtTime(0, tailEnd + 0.02);
     }
+  }
+  maintainGraphs = () => {
+    this.graph?.tick();
+    this.retired.forEach(this.maintainRetired);
   };
-  return backend;
-}
-function normalization(buffer) {
-  let peak = 0;
-  for (let c = 0; c < buffer.numberOfChannels; c++) {
-    const data = buffer.getChannelData(c);
-    for (let i = 0; i < data.length; i++) {
-      const a = Math.abs(data[i]);
-      if (a > peak) peak = a;
+  maintainRetired = (deadline, old) => {
+    if (this.context.currentTime < deadline) return;
+    for (const voice of this.voices.values())
+      for (const input of old.inputs.values()) {
+        try {
+          ;
+          (voice.panner ?? voice.highpass).disconnect(input);
+        } catch {
+        }
+      }
+    for (const voice of this.voices.values())
+      for (const [target, node] of voice.sends) {
+        const input = old.sendInputs.get(voice.desc.bus)?.get(target);
+        if (input)
+          try {
+            node.disconnect(input);
+          } catch {
+          }
+      }
+    old.dispose();
+    old.output.disconnect();
+    this.retired.delete(old);
+  };
+  setMixerValue(bus, field, value, rampSeconds = 0.01) {
+    if (!this.graph) throw new ShardError("audio/unsupported-capability", "No mixer is installed");
+    this.graph.set(bus, field, value, rampSeconds);
+    if (field === "userGain") {
+      for (const old of this.retired.keys())
+        if (old.hasBus(bus)) old.set(bus, field, value, rampSeconds);
+    }
+  }
+  emptyMeter() {
+    return {
+      available: !this.host.offline,
+      peak: 0,
+      rms: 0,
+      samples: 0,
+      sampleRate: this.context.sampleRate,
+      at: -1
+    };
+  }
+  meter(bus) {
+    if (this.host.offline) return this.emptyMeter();
+    let meter = this.meters.get(bus);
+    if (!meter) {
+      const node = this.context.createAnalyser();
+      node.fftSize = 2048;
+      this.busNode(bus).connect(node);
+      meter = { node, data: new Float32Array(2048), value: this.emptyMeter() };
+      this.meters.set(bus, meter);
     }
+    if (this.context.currentTime - meter.value.at < 0.05) return meter.value;
+    meter.node.getFloatTimeDomainData(meter.data);
+    let peak = 0, sum = 0;
+    for (let i = 0; i < meter.data.length; i++) {
+      const v = meter.data[i];
+      peak = Math.max(peak, Math.abs(v));
+      sum += v * v;
+    }
+    meter.value.peak = peak;
+    meter.value.rms = Math.sqrt(sum / meter.data.length);
+    meter.value.samples = meter.data.length;
+    meter.value.at = this.context.currentTime;
+    return meter.value;
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.graphRevision++;
+    for (const handle of this.wakes) clearInterval(handle);
+    for (const handle of this.timers) clearTimeout(handle);
+    this.wakes.clear();
+    this.timers.clear();
+    this.context.removeEventListener("statechange", this.stateChanged);
+    if (!this.host.offline)
+      for (const gesture of gestures)
+        window.removeEventListener(gesture, this.unlock, { capture: true });
+    for (const voice of this.voices.values()) this.finish(voice);
+    for (const lease of this.leases) lease.release();
+    for (const node of this.buses.values()) node.disconnect();
+    for (const meter of this.meters.values()) meter.node.disconnect();
+    this.buses.clear();
+    this.meters.clear();
+    this.statuses.clear();
+    this.graph?.dispose();
+    this.graph?.output.disconnect();
+    this.graph = null;
+    for (const graph of this.retired.keys()) {
+      graph.dispose();
+      graph.output.disconnect();
+    }
+    this.retired.clear();
+    this.output.disconnect();
+    this.host.reserved -= this.reserved;
+    this.reserved = 0;
+    this.host.sessions.delete(this);
+    if (this.root) {
+      for (const session of this.host.sessions) session.dispose();
+      this.host.cache.dispose();
+      this.host.output.disconnect();
+      if (this.host.ownsContext && !this.host.offline) void this.context.close();
+    } else this.host.cache.collect();
   }
-  return peak > 0 ? 1 / peak : 1;
+}
+function createWebAudioBackend(options = {}) {
+  const context = options.context ?? new AudioContext({ latencyHint: "interactive" });
+  const offline = typeof OfflineAudioContext !== "undefined" && context instanceof OfflineAudioContext;
+  const output = context.createGain();
+  output.connect(context.destination);
+  const fixedListener = options.context ? options.fixedListener === true : true;
+  if (fixedListener) setListenerPose(context.listener, identity);
+  const host = {
+    context,
+    output,
+    offline,
+    fixedListener,
+    ownsContext: !options.context,
+    cache: new AudioCache(context, options.decodedBudgetBytes, options.maxDecodes),
+    sessions: /* @__PURE__ */ new Set(),
+    maxVoices: options.maxHostVoices ?? 256,
+    voices: 0,
+    reserved: 0,
+    nextSession: 0
+  };
+  return new WebSession(host, true, options);
 }
 export {
   createWebAudioBackend