@babylonjs/lite 1.4.0 → 1.5.0

package/lib/audio/sound-buffer.js

@@ -0,0 +1,59 @@
+import { isAudioFormatValid } from './audio-engine.js';
+import { getFileExtension, loadAudioArrayBuffer } from './audio-fetch.js';
+
+function wrapAudioBuffer(audioBuffer) {
+  return {
+    _audioBuffer: audioBuffer,
+    get duration() {
+      return audioBuffer.duration;
+    },
+    get sampleRate() {
+      return audioBuffer.sampleRate;
+    },
+    get channelCount() {
+      return audioBuffer.numberOfChannels;
+    },
+    get length() {
+      return audioBuffer.length;
+    }
+  };
+}
+async function decodeUrl(engine, url) {
+  const data = await loadAudioArrayBuffer(url);
+  return await engine._ctx.decodeAudioData(data);
+}
+async function createSoundBufferAsync(engine, source, options = {}) {
+  if (typeof source === "object" && source !== null && "_audioBuffer" in source) {
+    return source;
+  }
+  if (typeof AudioBuffer !== "undefined" && source instanceof AudioBuffer) {
+    return wrapAudioBuffer(source);
+  }
+  if (source instanceof ArrayBuffer) {
+    return wrapAudioBuffer(await engine._ctx.decodeAudioData(source));
+  }
+  if (typeof source === "string") {
+    return wrapAudioBuffer(await decodeUrl(engine, source));
+  }
+  if (Array.isArray(source)) {
+    const skipCodecCheck = options.skipCodecCheck ?? false;
+    for (const url of source) {
+      const format = getFileExtension(url);
+      if (!skipCodecCheck && (!format || !isAudioFormatValid(engine, format))) {
+        continue;
+      }
+      try {
+        return wrapAudioBuffer(await decodeUrl(engine, url));
+      } catch {
+        if (format) {
+          engine._invalidFormats.add(format);
+        }
+      }
+    }
+    throw new Error("No decodable audio source found in URL list.");
+  }
+  return wrapAudioBuffer(source);
+}
+
+export { createSoundBufferAsync };
+//# sourceMappingURL=sound-buffer.js.map

package/lib/audio/sound-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound-buffer.js","sources":["../../../src/audio/sound-buffer.ts"],"sourcesContent":["/**\n * Decoded audio buffer.\n *\n * Faithful port of AudioV2 `_WebAudioStaticSoundBuffer` — collapsed to pure\n * state + a `createSoundBufferAsync` factory. Source may be an `AudioBuffer`, a\n * raw `ArrayBuffer`, a single URL, or an array of URLs (first decodable wins).\n */\n\nimport { type AudioEngine, isAudioFormatValid } from \"./audio-engine.js\";\nimport { getFileExtension, loadAudioArrayBuffer } from \"./audio-fetch.js\";\n\n/** A decoded audio buffer ready to be played by one or more sounds. */\nexport interface SoundBuffer {\n    /** The underlying Web Audio buffer. @internal */\n    _audioBuffer: AudioBuffer;\n    /** Duration in seconds. */\n    readonly duration: number;\n    /** Sample rate in Hz. */\n    readonly sampleRate: number;\n    /** Number of channels. */\n    readonly channelCount: number;\n    /** Length in samples. */\n    readonly length: number;\n}\n\n/** Source accepted when creating a sound or sound buffer. */\nexport type SoundSource = ArrayBuffer | AudioBuffer | SoundBuffer | string | string[];\n\n/** Options for {@link createSoundBufferAsync}. */\nexport interface SoundBufferOptions {\n    /** Skip the browser codec check when selecting among multiple URLs. */\n    skipCodecCheck?: boolean;\n}\n\nfunction wrapAudioBuffer(audioBuffer: AudioBuffer): SoundBuffer {\n    return {\n        _audioBuffer: audioBuffer,\n        get duration() {\n            return audioBuffer.duration;\n        },\n        get sampleRate() {\n            return audioBuffer.sampleRate;\n        },\n        get channelCount() {\n            return audioBuffer.numberOfChannels;\n        },\n        get length() {\n            return audioBuffer.length;\n        },\n    };\n}\n\nasync function decodeUrl(engine: AudioEngine, url: string): Promise<AudioBuffer> {\n    const data = await loadAudioArrayBuffer(url);\n    return await engine._ctx.decodeAudioData(data);\n}\n\n/**\n * Loads and decodes audio into a reusable {@link SoundBuffer}.\n * @param engine - The audio engine.\n * @param source - An `AudioBuffer`, `ArrayBuffer`, URL, or URL list.\n * @param options - Decode options.\n * @returns A promise that resolves with the decoded buffer.\n */\nexport async function createSoundBufferAsync(engine: AudioEngine, source: SoundSource, options: SoundBufferOptions = {}): Promise<SoundBuffer> {\n    // Already a decoded SoundBuffer?\n    if (typeof source === \"object\" && source !== null && \"_audioBuffer\" in source) {\n        return source;\n    }\n\n    if (typeof AudioBuffer !== \"undefined\" && source instanceof AudioBuffer) {\n        return wrapAudioBuffer(source);\n    }\n\n    if (source instanceof ArrayBuffer) {\n        return wrapAudioBuffer(await engine._ctx.decodeAudioData(source));\n    }\n\n    if (typeof source === \"string\") {\n        return wrapAudioBuffer(await decodeUrl(engine, source));\n    }\n\n    if (Array.isArray(source)) {\n        const skipCodecCheck = options.skipCodecCheck ?? false;\n        for (const url of source) {\n            const format = getFileExtension(url);\n            if (!skipCodecCheck && (!format || !isAudioFormatValid(engine, format))) {\n                continue;\n            }\n            try {\n                return wrapAudioBuffer(await decodeUrl(engine, url));\n            } catch {\n                if (format) {\n                    engine._invalidFormats.add(format);\n                }\n            }\n        }\n        throw new Error(\"No decodable audio source found in URL list.\");\n    }\n\n    // Remaining possibility: an `AudioBuffer` in an environment without the global.\n    return wrapAudioBuffer(source as AudioBuffer);\n}\n"],"names":[],"mappings":";;;AAkCA,SAAS,gBAAgB,WAAA,EAAuC;AAC5D,EAAA,OAAO;AAAA,IACH,YAAA,EAAc,WAAA;AAAA,IACd,IAAI,QAAA,GAAW;AACX,MAAA,OAAO,WAAA,CAAY,QAAA;AAAA,IACvB,CAAA;AAAA,IACA,IAAI,UAAA,GAAa;AACb,MAAA,OAAO,WAAA,CAAY,UAAA;AAAA,IACvB,CAAA;AAAA,IACA,IAAI,YAAA,GAAe;AACf,MAAA,OAAO,WAAA,CAAY,gBAAA;AAAA,IACvB,CAAA;AAAA,IACA,IAAI,MAAA,GAAS;AACT,MAAA,OAAO,WAAA,CAAY,MAAA;AAAA,IACvB;AAAA,GACJ;AACJ;AAEA,eAAe,SAAA,CAAU,QAAqB,GAAA,EAAmC;AAC7E,EAAA,MAAM,IAAA,GAAO,MAAM,oBAAA,CAAqB,GAAG,CAAA;AAC3C,EAAA,OAAO,MAAM,MAAA,CAAO,IAAA,CAAK,eAAA,CAAgB,IAAI,CAAA;AACjD;AASA,eAAsB,sBAAA,CAAuB,MAAA,EAAqB,MAAA,EAAqB,OAAA,GAA8B,EAAC,EAAyB;AAE3I,EAAA,IAAI,OAAO,MAAA,KAAW,QAAA,IAAY,MAAA,KAAW,IAAA,IAAQ,kBAAkB,MAAA,EAAQ;AAC3E,IAAA,OAAO,MAAA;AAAA,EACX;AAEA,EAAA,IAAI,OAAO,WAAA,KAAgB,WAAA,IAAe,MAAA,YAAkB,WAAA,EAAa;AACrE,IAAA,OAAO,gBAAgB,MAAM,CAAA;AAAA,EACjC;AAEA,EAAA,IAAI,kBAAkB,WAAA,EAAa;AAC/B,IAAA,OAAO,gBAAgB,MAAM,MAAA,CAAO,IAAA,CAAK,eAAA,CAAgB,MAAM,CAAC,CAAA;AAAA,EACpE;AAEA,EAAA,IAAI,OAAO,WAAW,QAAA,EAAU;AAC5B,IAAA,OAAO,eAAA,CAAgB,MAAM,SAAA,CAAU,MAAA,EAAQ,MAAM,CAAC,CAAA;AAAA,EAC1D;AAEA,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,EAAG;AACvB,IAAA,MAAM,cAAA,GAAiB,QAAQ,cAAA,IAAkB,KAAA;AACjD,IAAA,KAAA,MAAW,OAAO,MAAA,EAAQ;AACtB,MAAA,MAAM,MAAA,GAAS,iBAAiB,GAAG,CAAA;AACnC,MAAA,IAAI,CAAC,mBAAmB,CAAC,MAAA,IAAU,CAAC,kBAAA,CAAmB,MAAA,EAAQ,MAAM,CAAA,CAAA,EAAI;AACrE,QAAA;AAAA,MACJ;AACA,MAAA,IAAI;AACA,QAAA,OAAO,eAAA,CAAgB,MAAM,SAAA,CAAU,MAAA,EAAQ,GAAG,CAAC,CAAA;AAAA,MACvD,CAAA,CAAA,MAAQ;AACJ,QAAA,IAAI,MAAA,EAAQ;AACR,UAAA,MAAA,CAAO,eAAA,CAAgB,IAAI,MAAM,CAAA;AAAA,QACrC;AAAA,MACJ;AAAA,IACJ;AACA,IAAA,MAAM,IAAI,MAAM,8CAA8C,CAAA;AAAA,EAClE;AAGA,EAAA,OAAO,gBAAgB,MAAqB,CAAA;AAChD;;;;"}

package/lib/audio/sound-source.js

@@ -0,0 +1,57 @@
+import { getBusInputNode } from './audio-bus.js';
+import { createSoundSubGraph, connectSoundSubGraph, disposeSoundSubGraph, setSoundSubGraphVolume } from './sound-sub-graph.js';
+
+async function createSoundSourceAsync(engine, node, options = {}) {
+  const graph = createSoundSubGraph(engine._ctx, engine, options.volume ?? 1);
+  let outBus = null;
+  if (options.outBus) {
+    outBus = options.outBus;
+  } else if (options.outBusAutoDefault !== false) {
+    outBus = engine._mainBus;
+  }
+  if (outBus) {
+    connectSoundSubGraph(graph, getBusInputNode(outBus));
+  }
+  node.connect(graph._in);
+  const source = {
+    name: options.name ?? "",
+    _engine: engine,
+    _node: node,
+    _graph: graph,
+    _outBus: outBus,
+    _instances: /* @__PURE__ */ new Set([{ _volumeNode: node }]),
+    _dispose: () => disposeSoundSource(source)
+  };
+  engine._sounds.add(source);
+  return source;
+}
+async function createMicrophoneSoundSourceAsync(engine, options = {}) {
+  let mediaStream;
+  try {
+    mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+  } catch (e) {
+    throw new Error("Unable to access microphone: " + String(e), { cause: e });
+  }
+  const node = new MediaStreamAudioSourceNode(engine._ctx, { mediaStream });
+  return createSoundSourceAsync(engine, node, { outBusAutoDefault: false, ...options });
+}
+function setSoundSourceVolume(source, value, options) {
+  setSoundSubGraphVolume(source._graph, value, options);
+}
+function disposeSoundSource(source) {
+  const node = source._node;
+  if (node) {
+    if (typeof MediaStreamAudioSourceNode !== "undefined" && node instanceof MediaStreamAudioSourceNode) {
+      for (const track of node.mediaStream.getTracks()) {
+        track.stop();
+      }
+    }
+    node.disconnect();
+    source._node = null;
+  }
+  disposeSoundSubGraph(source._graph);
+  source._engine._sounds.delete(source);
+}
+
+export { createMicrophoneSoundSourceAsync, createSoundSourceAsync, disposeSoundSource, setSoundSourceVolume };
+//# sourceMappingURL=sound-source.js.map

package/lib/audio/sound-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound-source.js","sources":["../../../src/audio/sound-source.ts"],"sourcesContent":["/**\n * Live / external audio input sources — opt-in feature module.\n *\n * Faithful port of AudioV2 `AbstractSoundSource` / `_WebAudioSoundSource`\n * (`createMicrophoneSoundSourceAsync` + `createSoundSourceAsync`), re-architected\n * to Lite idioms (pure state + standalone functions). A source wraps an\n * arbitrary Web Audio `AudioNode` (typically a `MediaStreamAudioSourceNode` from\n * the microphone) and routes it through a {@link SoundSubGraph}, so the spatial,\n * stereo, and analyzer features apply to it exactly as they do to sounds.\n *\n * Signal flow:\n * `sourceNode` -\\> `graph._in` -\\> (spatial/stereo) -\\> `graph._volume` -\\> `outBus`\n *\n * The wrapped node is tracked as a single pseudo-instance so the shared\n * {@link rebuildSoundSubGraphHead} logic reconnects it when spatial/stereo are\n * enabled after creation.\n */\n\nimport { type AudioEngine } from \"./audio-engine.js\";\nimport { type PrimaryAudioBus, getBusInputNode } from \"./audio-bus.js\";\nimport { type RampOptions } from \"./audio-param.js\";\nimport { type SoundSubGraph, connectSoundSubGraph, createSoundSubGraph, disposeSoundSubGraph, setSoundSubGraphVolume } from \"./sound-sub-graph.js\";\n\n/** Options for {@link createSoundSourceAsync} and {@link createMicrophoneSoundSourceAsync}. */\nexport interface SoundSourceOptions {\n    /** Optional name. */\n    name?: string;\n    /** Output bus. Defaults to the engine's main bus unless {@link outBusAutoDefault} is `false`. */\n    outBus?: PrimaryAudioBus;\n    /**\n     * Whether the output bus defaults to the engine's main bus when {@link outBus}\n     * is not set. Defaults to `true` for {@link createSoundSourceAsync} and `false`\n     * for {@link createMicrophoneSoundSourceAsync} (a mic is usually analyzed, not\n     * played back, to avoid feedback).\n     */\n    outBusAutoDefault?: boolean;\n    /** Initial volume. Defaults to `1`. */\n    volume?: number;\n}\n\n/**\n * A sound fed by a live or external Web Audio input node (e.g. a microphone).\n * Accepted anywhere an {@link AudioGraphHost} is — enable spatial, stereo, or\n * analyzer features on it directly.\n */\nexport interface AudioInputSource {\n    /** The source name. */\n    readonly name: string;\n    /** @internal */ _engine: AudioEngine;\n    /** The wrapped input node; `null` after disposal. @internal */ _node: AudioNode | null;\n    /** @internal */ _graph: SoundSubGraph;\n    /** @internal */ _outBus: PrimaryAudioBus | null;\n    /** Single pseudo-instance wrapping the input node, for head reconnection. @internal */ _instances: Set<{ _volumeNode: AudioNode }>;\n    /** @internal */ _dispose(): void;\n}\n\n/**\n * Wraps an arbitrary Web Audio node as a sound source, routed to the given\n * output bus (or the engine's default main bus).\n * @param engine - The audio engine.\n * @param node - The input node to wrap (its output is routed through the graph).\n * @param options - Source options.\n * @returns A promise that resolves with the ready source.\n */\nexport async function createSoundSourceAsync(engine: AudioEngine, node: AudioNode, options: SoundSourceOptions = {}): Promise<AudioInputSource> {\n    const graph = createSoundSubGraph(engine._ctx, engine, options.volume ?? 1);\n\n    let outBus: PrimaryAudioBus | null = null;\n    if (options.outBus) {\n        outBus = options.outBus;\n    } else if (options.outBusAutoDefault !== false) {\n        outBus = engine._mainBus;\n    }\n    if (outBus) {\n        connectSoundSubGraph(graph, getBusInputNode(outBus));\n    }\n\n    node.connect(graph._in);\n\n    const source: AudioInputSource = {\n        name: options.name ?? \"\",\n        _engine: engine,\n        _node: node,\n        _graph: graph,\n        _outBus: outBus,\n        _instances: new Set([{ _volumeNode: node }]),\n        _dispose: () => disposeSoundSource(source),\n    };\n\n    engine._sounds.add(source);\n    return source;\n}\n\n/**\n * Requests microphone access and wraps the resulting stream as a sound source.\n * The source does not auto-connect to the main bus by default (to avoid\n * feedback); attach an analyzer or set an `outBus` to use it.\n * @param engine - The audio engine.\n * @param options - Source options.\n * @returns A promise that resolves with the ready microphone source.\n * @throws If microphone access is denied or unavailable.\n */\nexport async function createMicrophoneSoundSourceAsync(engine: AudioEngine, options: SoundSourceOptions = {}): Promise<AudioInputSource> {\n    let mediaStream: MediaStream;\n    try {\n        mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });\n    } catch (e) {\n        throw new Error(\"Unable to access microphone: \" + String(e), { cause: e });\n    }\n\n    const node = new MediaStreamAudioSourceNode(engine._ctx as AudioContext, { mediaStream });\n    return createSoundSourceAsync(engine, node, { outBusAutoDefault: false, ...options });\n}\n\n/**\n * Sets the source volume, optionally ramping.\n * @param source - The sound source.\n * @param value - Linear gain (`1` = unity).\n * @param options - Optional ramp options.\n */\nexport function setSoundSourceVolume(source: AudioInputSource, value: number, options?: RampOptions): void {\n    setSoundSubGraphVolume(source._graph, value, options);\n}\n\n/**\n * Disposes a sound source, stopping any microphone tracks and releasing its\n * graph.\n * @param source - The sound source.\n */\nexport function disposeSoundSource(source: AudioInputSource): void {\n    const node = source._node;\n    if (node) {\n        if (typeof MediaStreamAudioSourceNode !== \"undefined\" && node instanceof MediaStreamAudioSourceNode) {\n            for (const track of node.mediaStream.getTracks()) {\n                track.stop();\n            }\n        }\n        node.disconnect();\n        source._node = null;\n    }\n    disposeSoundSubGraph(source._graph);\n    source._engine._sounds.delete(source);\n}\n"],"names":[],"mappings":";;;AAgEA,eAAsB,sBAAA,CAAuB,MAAA,EAAqB,IAAA,EAAiB,OAAA,GAA8B,EAAC,EAA8B;AAC5I,EAAA,MAAM,QAAQ,mBAAA,CAAoB,MAAA,CAAO,MAAM,MAAA,EAAQ,OAAA,CAAQ,UAAU,CAAC,CAAA;AAE1E,EAAA,IAAI,MAAA,GAAiC,IAAA;AACrC,EAAA,IAAI,QAAQ,MAAA,EAAQ;AAChB,IAAA,MAAA,GAAS,OAAA,CAAQ,MAAA;AAAA,EACrB,CAAA,MAAA,IAAW,OAAA,CAAQ,iBAAA,KAAsB,KAAA,EAAO;AAC5C,IAAA,MAAA,GAAS,MAAA,CAAO,QAAA;AAAA,EACpB;AACA,EAAA,IAAI,MAAA,EAAQ;AACR,IAAA,oBAAA,CAAqB,KAAA,EAAO,eAAA,CAAgB,MAAM,CAAC,CAAA;AAAA,EACvD;AAEA,EAAA,IAAA,CAAK,OAAA,CAAQ,MAAM,GAAG,CAAA;AAEtB,EAAA,MAAM,MAAA,GAA2B;AAAA,IAC7B,IAAA,EAAM,QAAQ,IAAA,IAAQ,EAAA;AAAA,IACtB,OAAA,EAAS,MAAA;AAAA,IACT,KAAA,EAAO,IAAA;AAAA,IACP,MAAA,EAAQ,KAAA;AAAA,IACR,OAAA,EAAS,MAAA;AAAA,IACT,UAAA,sBAAgB,GAAA,CAAI,CAAC,EAAE,WAAA,EAAa,IAAA,EAAM,CAAC,CAAA;AAAA,IAC3C,QAAA,EAAU,MAAM,kBAAA,CAAmB,MAAM;AAAA,GAC7C;AAEA,EAAA,MAAA,CAAO,OAAA,CAAQ,IAAI,MAAM,CAAA;AACzB,EAAA,OAAO,MAAA;AACX;AAWA,eAAsB,gCAAA,CAAiC,MAAA,EAAqB,OAAA,GAA8B,EAAC,EAA8B;AACrI,EAAA,IAAI,WAAA;AACJ,EAAA,IAAI;AACA,IAAA,WAAA,GAAc,MAAM,SAAA,CAAU,YAAA,CAAa,aAAa,EAAE,KAAA,EAAO,MAAM,CAAA;AAAA,EAC3E,SAAS,CAAA,EAAG;AACR,IAAA,MAAM,IAAI,MAAM,+BAAA,GAAkC,MAAA,CAAO,CAAC,CAAA,EAAG,EAAE,KAAA,EAAO,CAAA,EAAG,CAAA;AAAA,EAC7E;AAEA,EAAA,MAAM,OAAO,IAAI,0BAAA,CAA2B,OAAO,IAAA,EAAsB,EAAE,aAAa,CAAA;AACxF,EAAA,OAAO,sBAAA,CAAuB,QAAQ,IAAA,EAAM,EAAE,mBAAmB,KAAA,EAAO,GAAG,SAAS,CAAA;AACxF;AAQO,SAAS,oBAAA,CAAqB,MAAA,EAA0B,KAAA,EAAe,OAAA,EAA6B;AACvG,EAAA,sBAAA,CAAuB,MAAA,CAAO,MAAA,EAAQ,KAAA,EAAO,OAAO,CAAA;AACxD;AAOO,SAAS,mBAAmB,MAAA,EAAgC;AAC/D,EAAA,MAAM,OAAO,MAAA,CAAO,KAAA;AACpB,EAAA,IAAI,IAAA,EAAM;AACN,IAAA,IAAI,OAAO,0BAAA,KAA+B,WAAA,IAAe,IAAA,YAAgB,0BAAA,EAA4B;AACjG,MAAA,KAAA,MAAW,KAAA,IAAS,IAAA,CAAK,WAAA,CAAY,SAAA,EAAU,EAAG;AAC9C,QAAA,KAAA,CAAM,IAAA,EAAK;AAAA,MACf;AAAA,IACJ;AACA,IAAA,IAAA,CAAK,UAAA,EAAW;AAChB,IAAA,MAAA,CAAO,KAAA,GAAQ,IAAA;AAAA,EACnB;AACA,EAAA,oBAAA,CAAqB,OAAO,MAAM,CAAA;AAClC,EAAA,MAAA,CAAO,OAAA,CAAQ,OAAA,CAAQ,MAAA,CAAO,MAAM,CAAA;AACxC;;;;"}

package/lib/audio/sound-sub-graph.js

@@ -0,0 +1,72 @@
+import { createRampParam, setRampTarget } from './audio-param.js';
+
+function createSoundSubGraph(ctx, clock, volume = 1) {
+  const gain = new GainNode(ctx);
+  gain.gain.value = volume;
+  return {
+    _ctx: ctx,
+    _volume: gain,
+    _volumeRamp: createRampParam(gain.gain, clock),
+    _spatial: null,
+    _stereo: null,
+    _analyzer: null,
+    _root: null,
+    _in: gain,
+    _out: gain
+  };
+}
+function rebuildSoundSubGraphHead(graph, instances) {
+  const spatial = graph._spatial;
+  const stereo = graph._stereo;
+  let head;
+  if (spatial && stereo) {
+    const root = graph._root ??= new GainNode(graph._ctx);
+    root.disconnect();
+    root.connect(spatial._inputNode);
+    root.connect(stereo._inputNode);
+    head = root;
+  } else {
+    if (graph._root) {
+      graph._root.disconnect();
+      graph._root = null;
+    }
+    head = spatial?._inputNode ?? stereo?._inputNode ?? graph._volume;
+  }
+  const oldHead = graph._in;
+  if (oldHead === head) {
+    return;
+  }
+  graph._in = head;
+  if (instances) {
+    for (const instance of instances) {
+      try {
+        instance._volumeNode.disconnect(oldHead);
+      } catch {
+      }
+      instance._volumeNode.connect(head);
+    }
+  }
+}
+function setSoundSubGraphVolume(graph, value, options) {
+  setRampTarget(graph._volumeRamp, value, options);
+}
+function connectSoundSubGraph(graph, downstream) {
+  graph._out.connect(downstream);
+}
+function disconnectSoundSubGraph(graph, downstream) {
+  graph._out.disconnect(downstream);
+}
+function disposeSoundSubGraph(graph) {
+  graph._spatial?._dispose();
+  graph._spatial = null;
+  graph._stereo?._dispose();
+  graph._stereo = null;
+  graph._analyzer?._dispose();
+  graph._analyzer = null;
+  graph._root?.disconnect();
+  graph._root = null;
+  graph._volume.disconnect();
+}
+
+export { connectSoundSubGraph, createSoundSubGraph, disconnectSoundSubGraph, disposeSoundSubGraph, rebuildSoundSubGraphHead, setSoundSubGraphVolume };
+//# sourceMappingURL=sound-sub-graph.js.map

package/lib/audio/sound-sub-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound-sub-graph.js","sources":["../../../src/audio/sound-sub-graph.ts"],"sourcesContent":["/**\n * Per-sound sub-graph.\n *\n * Faithful port of AudioV2 `_WebAudioBaseSubGraph` + `_WebAudioBusAndSoundSubGraph`\n * + `_VolumeWebAudioSubNode`. The volume `GainNode` is always present; the\n * spatial, stereo, and analyzer sub-nodes are optional and spliced in on demand\n * by their (tree-shaken) feature modules.\n *\n * Signal flow (mirrors AudioV2 `_onSubNodesChanged`):\n * - none: `instances` -\\> `_volume` (`_in` === `_out`)\n * - spatial OR stereo: `instances` -\\> `subNode._inputNode` -\\> `_volume`\n * - spatial AND stereo: `instances` -\\> `_root` (split) -\\> [spatial, stereo] -\\> `_volume`\n * - analyzer (any of the above): `_volume` also fans out to the analyzer tap\n */\n\nimport { type RampClock, type RampOptions, type RampParam, createRampParam, setRampTarget } from \"./audio-param.js\";\n\n/**\n * Minimal structural view of a pre-volume sub-node (spatial or stereo), kept\n * local so this module does NOT import the feature modules (Pillar 4:\n * tree-shaking) and so the `.d.ts` rollup has no import cycle. The full node\n * (assigned by the feature functions) is structurally compatible. @internal\n */\nexport interface PreVolumeSlot {\n    /** Head input node of the sub-node. @internal */ _inputNode: AudioNode;\n    /** @internal */ _dispose(): void;\n}\n\n/** Minimal structural view of the analyzer tap sub-node. @internal */\nexport interface AnalyzerSlot {\n    /** @internal */ _dispose(): void;\n}\n\n/** Sound sub-graph state. @internal */\nexport interface SoundSubGraph {\n    /** @internal */ _ctx: BaseAudioContext;\n    /** @internal */ _volume: GainNode;\n    /** @internal */ _volumeRamp: RampParam;\n    /** Optional spatial (3D panner) sub-node. @internal */ _spatial: PreVolumeSlot | null;\n    /** Optional stereo-pan sub-node. @internal */ _stereo: PreVolumeSlot | null;\n    /** Optional analyzer tap off {@link _volume}. @internal */ _analyzer: AnalyzerSlot | null;\n    /** Split gain feeding both spatial and stereo when both are present. @internal */ _root: GainNode | null;\n    /** Head node — where playing instances connect. @internal */ _in: AudioNode;\n    /** Tail node — connects to the output bus. @internal */ _out: AudioNode;\n}\n\n/** @internal */\nexport function createSoundSubGraph(ctx: BaseAudioContext, clock: RampClock, volume = 1): SoundSubGraph {\n    const gain = new GainNode(ctx);\n    gain.gain.value = volume;\n    return {\n        _ctx: ctx,\n        _volume: gain,\n        _volumeRamp: createRampParam(gain.gain, clock),\n        _spatial: null,\n        _stereo: null,\n        _analyzer: null,\n        _root: null,\n        _in: gain,\n        _out: gain,\n    };\n}\n\n/**\n * Recomputes the head node (`_in`) after a pre-volume sub-node (spatial/stereo)\n * is added or removed, mirroring AudioV2 `_onSubNodesChanged`. When both spatial\n * and stereo are present they run in parallel, fed by a split `_root` gain. Any\n * live instances are reconnected from the old head to the new one. @internal\n */\nexport function rebuildSoundSubGraphHead(graph: SoundSubGraph, instances?: Iterable<{ _volumeNode: AudioNode }>): void {\n    const spatial = graph._spatial;\n    const stereo = graph._stereo;\n\n    let head: AudioNode;\n    if (spatial && stereo) {\n        const root = (graph._root ??= new GainNode(graph._ctx));\n        root.disconnect();\n        root.connect(spatial._inputNode);\n        root.connect(stereo._inputNode);\n        head = root;\n    } else {\n        if (graph._root) {\n            graph._root.disconnect();\n            graph._root = null;\n        }\n        head = spatial?._inputNode ?? stereo?._inputNode ?? graph._volume;\n    }\n\n    const oldHead = graph._in;\n    if (oldHead === head) {\n        return;\n    }\n    graph._in = head;\n\n    if (instances) {\n        for (const instance of instances) {\n            try {\n                instance._volumeNode.disconnect(oldHead);\n            } catch {\n                // Instance may not yet be connected; ignore.\n            }\n            instance._volumeNode.connect(head);\n        }\n    }\n}\n\n/** @internal */\nexport function setSoundSubGraphVolume(graph: SoundSubGraph, value: number, options?: RampOptions): void {\n    setRampTarget(graph._volumeRamp, value, options);\n}\n\n/** Connects the sub-graph output to a downstream input node. @internal */\nexport function connectSoundSubGraph(graph: SoundSubGraph, downstream: AudioNode): void {\n    graph._out.connect(downstream);\n}\n\n/** Disconnects the sub-graph output from a downstream input node. @internal */\nexport function disconnectSoundSubGraph(graph: SoundSubGraph, downstream: AudioNode): void {\n    graph._out.disconnect(downstream);\n}\n\n/** @internal */\nexport function disposeSoundSubGraph(graph: SoundSubGraph): void {\n    graph._spatial?._dispose();\n    graph._spatial = null;\n    graph._stereo?._dispose();\n    graph._stereo = null;\n    graph._analyzer?._dispose();\n    graph._analyzer = null;\n    graph._root?.disconnect();\n    graph._root = null;\n    graph._volume.disconnect();\n}\n"],"names":[],"mappings":"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"}