cacophony 0.30.4 → 0.31.0

package/README.md

@@ -19,10 +19,36 @@ Cacophony is a powerful and intuitive audio library designed for modern web appl
 ## Installation
 
 ```bash
-npm install cacophony
-```
-
-## Quick Start
+npm install cacophony
+```
+
+## Bundling and lazy loading
+
+Use named ESM imports so your bundler can discard unused modules:
+
+```typescript
+import { AudioCache } from 'cacophony';
+```
+
+The package preserves its module boundaries and declares import side effects.
+Importing `AudioCache` or an individual effect does not pull in the full
+`Cacophony` class or the offline FFT implementation. The `Cacophony` class keeps
+its complete factory API, so importing that class still includes the code its
+methods reference.
+
+`createStream()` loads MediaBunny on demand when using the WebCodecs transport.
+HLS streams and browsers without `AudioDecoder` take their existing fallback
+paths without loading it. Each AudioWorklet payload loads when its processor is
+first needed. Call `await audio.loadWorklets()` to preload all processors.
+
+Consumer bundlers must support code splitting to keep these imports in separate
+downloadable chunks. Deploy all generated chunks with the application. MediaBunny
+remains an installed dependency; lazy loading defers its runtime load.
+
+Run `npm run build` followed by `npm run check:bundles -- --report` to inspect
+initial bundle sizes for cache-only, full-factory, and single-effect consumers.
+
+## Quick Start
 
 ```typescript
 import { Cacophony } from 'cacophony';
@@ -124,10 +150,49 @@ setTimeout(() => playback1.pause(), 1000);
 setTimeout(() => playback2.stop(), 2000);
 
 // Or control all playbacks through the Sound
-sound.stop();  // Stops all three playbacks
-```
-
-## Sound Types
+sound.stop();  // Stops all three playbacks
+```
+
+### Audio Sprites for Games
+
+Pack many short effects into one decoded WAV atlas while keeping each named
+region as an ordinary, independently configurable `Sound`:
+
+```bash
+cacophony sprite sfx/laser.wav sfx/engine.wav \
+  --out public/sfx-atlas.wav --map public/sfx-atlas.json --gap 10
+```
+
+```typescript
+import { Cacophony, type SpriteMap } from 'cacophony';
+
+const map = {
+  laser: { start: 0, duration: 0.35 },
+  engine: { start: 0.36, duration: 1.2, loopCount: 'infinite' },
+} as const satisfies SpriteMap;
+
+const cacophony = new Cacophony();
+const sprite = await cacophony.createSprite('/sfx-atlas.wav', map);
+
+// Literal keys stay typed. Each child uses the normal Sound API.
+sprite.sounds.laser.volume = 0.7;
+sprite.sounds.laser.play();
+
+// Dynamic names use the checked lookup.
+const selected: string = chooseEffectName();
+if (sprite.has(selected)) sprite.get(selected).play();
+
+// Child configuration is independent; the atlas has no shared play controls.
+sprite.sounds.engine.loop('infinite');
+sprite.sounds.engine.play();
+
+sprite.cleanup();
+```
+
+All child Sounds share the atlas `AudioBuffer`. `cleanup()` owns those children
+but not clones created with `sound.clone()`, which remain independently usable.
+
+## Sound Types
 
 Cacophony supports three URL-backed sound labels:
 
@@ -551,6 +616,27 @@ FOA binaural decoding is available in both forms. Use
 `decoder.input` and `decoder.output`; use `createFoaDecoderEffect()` only on a
 dedicated 4-channel ACN/SN3D FOA bus, typically as the first and only filter
 that converts that bus to stereo binaural output.
+
+For physically correct mono positioning, use `encodeMonoToFoaSN3D()` and feed
+its ACN/SN3D `[W, Y, Z, X]` output to the decoder. Stereo recordings can instead
+be perceptually upmixed with `createStereoToBFormatNode()`. The default
+`algorithm: 'perceptual'` path preserves the existing three-band front cue;
+`algorithm: 'bcc'` uses frequency-domain coherence and pan analysis:
+
+```typescript
+const upmixer = await cacophony.createStereoToBFormatNode({ algorithm: 'bcc' });
+const decoder = await cacophony.createFoaDecoder();
+stereoSource.connect(upmixer);
+upmixer.connect(decoder.input);
+decoder.output.connect(cacophony.context.destination);
+
+// BCC analysis is stateful. Reset it after a seek or other discontinuity.
+upmixer.port.postMessage({ type: 'reset' });
+```
+
+Both stereo upmix algorithms emit ACN `[W, Y, Z, X]` but are perceptual
+approximations, neither N3D nor SN3D. The BCC path produces W/Y only and keeps
+Z/X at zero, trading the default path's front cue for per-band spatial analysis.
 
 ### Cleaning up
 

package/dist/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));exports.__toESM=s;

package/dist/assets/sh_hrir_order_1.wav_url.cjs

@@ -0,0 +1,2 @@
+var e=`data:audio/wav;base64,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`;exports.default=e;
+//# sourceMappingURL=sh_hrir_order_1.wav_url.cjs.map

package/dist/assets/sh_hrir_order_1.wav_url.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_hrir_order_1.wav_url.cjs","names":[],"sources":["../../src/assets/sh_hrir_order_1.wav?url"],"sourcesContent":["export default \"data:audio/wav;base64,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\""],"mappings":"AAAA,IAAA,EAAe"}

package/dist/assets/sh_hrir_order_1.wav_url.mjs

@@ -0,0 +1,6 @@
+//#region src/assets/sh_hrir_order_1.wav?url
+var e = "data:audio/wav;base64,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";
+//#endregion
+export { e as default };
+
+//# sourceMappingURL=sh_hrir_order_1.wav_url.mjs.map

package/dist/assets/sh_hrir_order_1.wav_url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_hrir_order_1.wav_url.mjs","names":[],"sources":["../../src/assets/sh_hrir_order_1.wav?url"],"sourcesContent":["export default \"data:audio/wav;base64,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\""],"mappings":";AAAA,IAAA,IAAe"}

package/dist/audioSprite.cjs

@@ -0,0 +1,2 @@
+var e=class{sounds;names;cleanedUp=!1;constructor(e,t){this.sounds=Object.freeze(e),this.names=Object.freeze([...t])}get(e){if(!Object.hasOwn(this.sounds,e))throw Error(`Unknown audio sprite name: ${e}`);return this.sounds[e]}has(e){return Object.hasOwn(this.sounds,e)}cleanup(){if(!this.cleanedUp){this.cleanedUp=!0;for(let e of this.names)this.sounds[e].cleanup()}}};exports.AudioSprite=e;
+//# sourceMappingURL=audioSprite.cjs.map

package/dist/audioSprite.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioSprite.cjs","names":[],"sources":["../src/audioSprite.ts"],"sourcesContent":["import type { LoopCount } from \"./cacophony\";\nimport type { Sound } from \"./sound\";\n\n/** A named, immutable region of an audio atlas, expressed in seconds. */\nexport interface SpriteRegion {\n  readonly start: number;\n  readonly duration: number;\n  readonly loopCount?: LoopCount;\n}\n\n/** Named regions used to construct an {@link AudioSprite}. */\nexport type SpriteMap = Readonly<Record<string, SpriteRegion>>;\n\n/** Options shared by every child Sound created for a sprite. */\nexport interface CreateSpriteOptions {\n  panType?: import(\"./cacophony\").PanType;\n  signal?: AbortSignal;\n}\n\n/**\n * A typed registry and lifetime owner for the ordinary Sounds in an atlas.\n * Playback and configuration remain child-Sound operations.\n */\nexport class AudioSprite<K extends string = string> {\n  readonly sounds: Readonly<Record<K, Sound>>;\n  readonly names: readonly K[];\n  private cleanedUp = false;\n\n  /** @internal Construct sprites through Cacophony.createSprite(). */\n  constructor(sounds: Record<K, Sound>, names: readonly K[]) {\n    this.sounds = Object.freeze(sounds);\n    this.names = Object.freeze([...names]);\n  }\n\n  get(name: K): Sound {\n    if (!Object.hasOwn(this.sounds, name)) {\n      throw new Error(`Unknown audio sprite name: ${name}`);\n    }\n    return this.sounds[name];\n  }\n\n  has(name: string): name is K {\n    return Object.hasOwn(this.sounds, name);\n  }\n\n  cleanup(): void {\n    if (this.cleanedUp) return;\n    this.cleanedUp = true;\n    for (const name of this.names) {\n      this.sounds[name].cleanup();\n    }\n  }\n}\n"],"mappings":"AAuBA,IAAa,EAAb,KAAoD,CAClD,OACA,MACA,UAAoB,GAGpB,YAAY,EAA0B,EAAqB,CACzD,KAAK,OAAS,OAAO,OAAO,CAAM,EAClC,KAAK,MAAQ,OAAO,OAAO,CAAC,GAAG,CAAK,CAAC,CACvC,CAEA,IAAI,EAAgB,CAClB,GAAI,CAAC,OAAO,OAAO,KAAK,OAAQ,CAAI,EAClC,MAAU,MAAM,8BAA8B,GAAM,EAEtD,OAAO,KAAK,OAAO,EACrB,CAEA,IAAI,EAAyB,CAC3B,OAAO,OAAO,OAAO,KAAK,OAAQ,CAAI,CACxC,CAEA,SAAgB,CACV,SAAK,UACT,MAAK,UAAY,GACjB,IAAK,IAAM,KAAQ,KAAK,MACtB,KAAK,OAAO,GAAM,QAAQ,CAFX,CAInB,CACF"}

package/dist/audioSprite.d.ts

@@ -0,0 +1,29 @@
+import { LoopCount } from './cacophony';
+import { Sound } from './sound';
+/** A named, immutable region of an audio atlas, expressed in seconds. */
+export interface SpriteRegion {
+    readonly start: number;
+    readonly duration: number;
+    readonly loopCount?: LoopCount;
+}
+/** Named regions used to construct an {@link AudioSprite}. */
+export type SpriteMap = Readonly<Record<string, SpriteRegion>>;
+/** Options shared by every child Sound created for a sprite. */
+export interface CreateSpriteOptions {
+    panType?: import('./cacophony').PanType;
+    signal?: AbortSignal;
+}
+/**
+ * A typed registry and lifetime owner for the ordinary Sounds in an atlas.
+ * Playback and configuration remain child-Sound operations.
+ */
+export declare class AudioSprite<K extends string = string> {
+    readonly sounds: Readonly<Record<K, Sound>>;
+    readonly names: readonly K[];
+    private cleanedUp;
+    /** @internal Construct sprites through Cacophony.createSprite(). */
+    constructor(sounds: Record<K, Sound>, names: readonly K[]);
+    get(name: K): Sound;
+    has(name: string): name is K;
+    cleanup(): void;
+}

package/dist/audioSprite.mjs

@@ -0,0 +1,26 @@
+//#region src/audioSprite.ts
+var e = class {
+	sounds;
+	names;
+	cleanedUp = !1;
+	constructor(e, t) {
+		this.sounds = Object.freeze(e), this.names = Object.freeze([...t]);
+	}
+	get(e) {
+		if (!Object.hasOwn(this.sounds, e)) throw Error(`Unknown audio sprite name: ${e}`);
+		return this.sounds[e];
+	}
+	has(e) {
+		return Object.hasOwn(this.sounds, e);
+	}
+	cleanup() {
+		if (!this.cleanedUp) {
+			this.cleanedUp = !0;
+			for (let e of this.names) this.sounds[e].cleanup();
+		}
+	}
+};
+//#endregion
+export { e as AudioSprite };
+
+//# sourceMappingURL=audioSprite.mjs.map

package/dist/audioSprite.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"audioSprite.mjs","names":[],"sources":["../src/audioSprite.ts"],"sourcesContent":["import type { LoopCount } from \"./cacophony\";\nimport type { Sound } from \"./sound\";\n\n/** A named, immutable region of an audio atlas, expressed in seconds. */\nexport interface SpriteRegion {\n  readonly start: number;\n  readonly duration: number;\n  readonly loopCount?: LoopCount;\n}\n\n/** Named regions used to construct an {@link AudioSprite}. */\nexport type SpriteMap = Readonly<Record<string, SpriteRegion>>;\n\n/** Options shared by every child Sound created for a sprite. */\nexport interface CreateSpriteOptions {\n  panType?: import(\"./cacophony\").PanType;\n  signal?: AbortSignal;\n}\n\n/**\n * A typed registry and lifetime owner for the ordinary Sounds in an atlas.\n * Playback and configuration remain child-Sound operations.\n */\nexport class AudioSprite<K extends string = string> {\n  readonly sounds: Readonly<Record<K, Sound>>;\n  readonly names: readonly K[];\n  private cleanedUp = false;\n\n  /** @internal Construct sprites through Cacophony.createSprite(). */\n  constructor(sounds: Record<K, Sound>, names: readonly K[]) {\n    this.sounds = Object.freeze(sounds);\n    this.names = Object.freeze([...names]);\n  }\n\n  get(name: K): Sound {\n    if (!Object.hasOwn(this.sounds, name)) {\n      throw new Error(`Unknown audio sprite name: ${name}`);\n    }\n    return this.sounds[name];\n  }\n\n  has(name: string): name is K {\n    return Object.hasOwn(this.sounds, name);\n  }\n\n  cleanup(): void {\n    if (this.cleanedUp) return;\n    this.cleanedUp = true;\n    for (const name of this.names) {\n      this.sounds[name].cleanup();\n    }\n  }\n}\n"],"mappings":";AAuBA,IAAa,IAAb,MAAoD;CAClD;CACA;CACA,YAAoB;CAGpB,YAAY,GAA0B,GAAqB;EAEzD,AADA,KAAK,SAAS,OAAO,OAAO,CAAM,GAClC,KAAK,QAAQ,OAAO,OAAO,CAAC,GAAG,CAAK,CAAC;CACvC;CAEA,IAAI,GAAgB;EAClB,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAI,GAClC,MAAU,MAAM,8BAA8B,GAAM;EAEtD,OAAO,KAAK,OAAO;CACrB;CAEA,IAAI,GAAyB;EAC3B,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAI;CACxC;CAEA,UAAgB;EACV,UAAK,WACT;QAAK,YAAY;GACjB,KAAK,IAAM,KAAQ,KAAK,OACtB,KAAK,OAAO,GAAM,QAAQ;EAFX;CAInB;AACF"}

package/dist/autoplayUnlock.cjs

@@ -0,0 +1,2 @@
+var e=[`touchend`,`click`,`keydown`],t={capture:!0,passive:!0};function n(n){let{context:r,onUnlock:i}=n;if(typeof document>`u`)return()=>{};let a=r.resume;if(typeof a!=`function`)return()=>{};let o=document,s=o.body??o,c=r,l=!1,u=!1,d=!1,f=()=>{if(l){for(let n of e)s.removeEventListener(n,p,t);l=!1}},p=()=>{if(!(d||u)){u=!0,f();try{let e=r.createBuffer(1,1,r.sampleRate),t=r.createBufferSource();t.buffer=e,t.connect(r.destination),t.start(0),t.stop(0)}catch(e){console.warn(`[cacophony/autoplayUnlock] primer failed:`,e)}a.call(r).then(()=>{if(u=!1,!d)try{i()}catch(e){console.error(`[cacophony/autoplayUnlock] onUnlock callback threw:`,e)}},e=>{u=!1,!d&&(console.warn(`[cacophony/autoplayUnlock] resume failed:`,e),h())})}},m=()=>{if(!(d||l||u)){for(let n of e)s.addEventListener(n,p,t);l=!0}};function h(){c.state===`suspended`||c.state===`interrupted`?m():f()}let g=()=>{d||h()};return c.addEventListener?.(`statechange`,g),h(),()=>{d||(d=!0,f(),c.removeEventListener?.(`statechange`,g))}}exports.installAutoplayUnlock=n;
+//# sourceMappingURL=autoplayUnlock.cjs.map

package/dist/autoplayUnlock.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoplayUnlock.cjs","names":[],"sources":["../src/autoplayUnlock.ts"],"sourcesContent":["import type { BaseContext } from \"./context\";\n\n/**\n * Autoplay unlock — Howler-parity automatic AudioContext resume on first\n * user gesture.\n *\n * On mobile browsers (especially iOS Safari) an `AudioContext` constructed\n * before any user interaction is created in `suspended` state. It will not\n * produce sound until BOTH:\n *\n *   1. `context.resume()` is called, AND\n *   2. an `AudioBufferSourceNode` is created and started inside the user\n *      gesture's call stack (the iOS \"primer\").\n *\n * Many callers do (1) but not (2), and hear silence with no obvious cause.\n * This module watches the context for suspension and arms `touchend` / `click`\n * / `keydown` listeners on `document.body` (or `document` as fallback). A\n * gesture resumes the context, plays a 1-sample silent primer inside the\n * gesture call stack, removes all three listeners, and calls the `onUnlock`\n * callback. If the context suspends again, the listeners are re-armed.\n *\n * Design adapted (not copied) from Howler.js `_unlockAudio` — MIT licensed.\n */\n\nconst UNLOCK_EVENT_TYPES: ReadonlyArray<\"touchend\" | \"click\" | \"keydown\"> = [\"touchend\", \"click\", \"keydown\"];\nconst GESTURE_LISTENER_OPTIONS = { capture: true, passive: true } as const;\n\n/**\n * A `Document`-like type with the methods we need. Avoids a hard dependency\n * on DOM lib types so the package keeps building when `lib: [\"dom\"]` is off.\n */\ninterface DocumentLike {\n  body?: EventTargetLike | null;\n  addEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n  removeEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n}\n\ninterface EventTargetLike {\n  addEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n  removeEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n}\n\n/**\n * Options for `installAutoplayUnlock`.\n */\nexport interface AutoplayUnlockOptions {\n  /**\n   * The audio context that should be resumed and primed.\n   */\n  context: BaseContext;\n\n  /**\n   * Called after the context has been resumed and the primer buffer has been\n   * started. Used by `Cacophony` to emit the public `unlock` event.\n   * Errors thrown by the callback are caught and logged so a faulty listener\n   * cannot break the unlock flow.\n   */\n  onUnlock: () => void;\n}\n\n/**\n * Watch for context suspension and install unlock listeners while needed.\n * Returns a cleanup function that removes both the context watcher and any\n * armed gesture listeners (e.g. when a `Cacophony` instance is torn down).\n *\n * If the environment is non-browser (`document` is undefined), this is a\n * no-op and returns a no-op cleanup.\n *\n * @internal\n */\nexport function installAutoplayUnlock(opts: AutoplayUnlockOptions): () => void {\n  const { context, onUnlock } = opts;\n\n  // Server-side / non-browser: nothing to do.\n  if (typeof document === \"undefined\") {\n    return () => {};\n  }\n\n  // `BaseContext.resume` is optional. If this context has no resume() we\n  // cannot actually unlock it — installing gesture listeners would be noise,\n  // and firing the `unlock` event without a fulfilled resume() would violate\n  // the contract (caller would see `unlock` while `Cacophony.locked` stays\n  // true, since `locked` is derived from `context.state === \"suspended\"`).\n  // Treat the absence as \"this context isn't ours to unlock\" and bail.\n  const resume = (context as unknown as { resume?: () => Promise<void> }).resume;\n  if (typeof resume !== \"function\") {\n    return () => {};\n  }\n\n  const doc = document as unknown as DocumentLike;\n  const target: EventTargetLike = (doc.body as EventTargetLike | null | undefined) ?? doc;\n  const observableContext = context as unknown as {\n    state?: string;\n    addEventListener?: (type: string, listener: () => void) => void;\n    removeEventListener?: (type: string, listener: () => void) => void;\n  };\n\n  let armed = false;\n  let resumeInFlight = false;\n  let disposed = false;\n\n  const removeAll = () => {\n    if (!armed) return;\n    for (const type of UNLOCK_EVENT_TYPES) {\n      target.removeEventListener(type, handler, GESTURE_LISTENER_OPTIONS);\n    }\n    armed = false;\n  };\n\n  const handler = () => {\n    if (disposed || resumeInFlight) return;\n    resumeInFlight = true;\n\n    // Remove listeners FIRST so a re-entrant gesture cannot re-trigger us\n    // while resume() is in flight.\n    removeAll();\n\n    // Play the iOS primer INSIDE the gesture call stack. iOS requires that\n    // an AudioBufferSourceNode be created and started synchronously inside\n    // the gesture handler for the context to truly unlock — calling\n    // resume() alone is not sufficient. A 1-sample silent buffer is the\n    // minimum that satisfies the requirement and is inaudible.\n    try {\n      // BaseContext doesn't declare createBuffer because Cacophony's normal\n      // code path always feeds an AudioBuffer constructed externally; the\n      // primer needs to construct a 1-sample buffer in-place, so we widen\n      // the type locally here. Both AudioContext and OfflineAudioContext\n      // expose createBuffer.\n      const ctxWithCreateBuffer = context as unknown as {\n        createBuffer(numberOfChannels: number, length: number, sampleRate: number): unknown;\n      };\n      const buffer = ctxWithCreateBuffer.createBuffer(1, 1, context.sampleRate);\n      const source = context.createBufferSource();\n      source.buffer = buffer as any;\n      source.connect(context.destination);\n      // The load-bearing iOS pattern is start(0); stop(0) on a silent buffer\n      // INSIDE the gesture call stack. A 1-sample non-looping buffer would\n      // end on its own, but the pair is what the platform contract names.\n      source.start(0);\n      source.stop(0);\n    } catch (err) {\n      // Primer failure should not block the rest of the unlock; the\n      // context.resume() call below is still useful on platforms that do\n      // not require the primer.\n      console.warn(\"[cacophony/autoplayUnlock] primer failed:\", err);\n    }\n\n    // Resume the context, then emit unlock. The `unlock` event signals that\n    // audio is actually playable, so we must wait for resume() to fulfill\n    // before emitting. On rejection we surface the error and do NOT emit\n    // unlock — a failed resume is not an unlock. `resume` is guaranteed to\n    // be a function here (guarded at install time above).\n    resume.call(context).then(\n      () => {\n        resumeInFlight = false;\n        if (disposed) return;\n        try {\n          onUnlock();\n        } catch (err) {\n          console.error(\"[cacophony/autoplayUnlock] onUnlock callback threw:\", err);\n        }\n      },\n      (err: unknown) => {\n        resumeInFlight = false;\n        if (disposed) return;\n        console.warn(\"[cacophony/autoplayUnlock] resume failed:\", err);\n        syncGestureListeners();\n      },\n    );\n  };\n\n  const armAll = () => {\n    if (disposed || armed || resumeInFlight) return;\n    for (const type of UNLOCK_EVENT_TYPES) {\n      target.addEventListener(type, handler, GESTURE_LISTENER_OPTIONS);\n    }\n    armed = true;\n  };\n\n  function syncGestureListeners(): void {\n    if (observableContext.state === \"suspended\" || observableContext.state === \"interrupted\") {\n      armAll();\n    } else {\n      removeAll();\n    }\n  }\n\n  const handleStateChange = () => {\n    if (!disposed) syncGestureListeners();\n  };\n\n  observableContext.addEventListener?.(\"statechange\", handleStateChange);\n  syncGestureListeners();\n\n  return () => {\n    if (disposed) return;\n    disposed = true;\n    removeAll();\n    observableContext.removeEventListener?.(\"statechange\", handleStateChange);\n  };\n}\n"],"mappings":"AAwBA,IAAM,EAAsE,CAAC,WAAY,QAAS,SAAS,EACrG,EAA2B,CAAE,QAAS,GAAM,QAAS,EAAK,EA6ChE,SAAgB,EAAsB,EAAyC,CAC7E,GAAM,CAAE,UAAS,YAAa,EAG9B,GAAI,OAAO,SAAa,IACtB,UAAa,CAAC,EAShB,IAAM,EAAU,EAAwD,OACxE,GAAI,OAAO,GAAW,WACpB,UAAa,CAAC,EAGhB,IAAM,EAAM,SACN,EAA2B,EAAI,MAA+C,EAC9E,EAAoB,EAMtB,EAAQ,GACR,EAAiB,GACjB,EAAW,GAET,MAAkB,CACjB,KACL,KAAK,IAAM,KAAQ,EACjB,EAAO,oBAAoB,EAAM,EAAS,CAAwB,EAEpE,EAAQ,EAF4D,CAGtE,EAEM,MAAgB,CAChB,QAAY,GAKhB,CAJA,EAAiB,GAIjB,EAAU,EAOV,GAAI,CASF,IAAM,EAAS,EAAoB,aAAa,EAAG,EAAG,EAAQ,UAAU,EAClE,EAAS,EAAQ,mBAAmB,EAC1C,EAAO,OAAS,EAChB,EAAO,QAAQ,EAAQ,WAAW,EAIlC,EAAO,MAAM,CAAC,EACd,EAAO,KAAK,CAAC,CACf,OAAS,EAAK,CAIZ,QAAQ,KAAK,4CAA6C,CAAG,CAC/D,CAOA,EAAO,KAAK,CAAO,EAAE,SACb,CACJ,KAAiB,GACb,GACJ,GAAI,CACF,EAAS,CACX,OAAS,EAAK,CACZ,QAAQ,MAAM,sDAAuD,CAAG,CAC1E,CACF,EACC,GAAiB,CAChB,EAAiB,GACb,KACJ,QAAQ,KAAK,4CAA6C,CAAG,EAC7D,EAAqB,EACvB,CACF,CArDU,CAsDZ,EAEM,MAAe,CACf,QAAY,GAAS,GACzB,KAAK,IAAM,KAAQ,EACjB,EAAO,iBAAiB,EAAM,EAAS,CAAwB,EAEjE,EAAQ,EAFyD,CAGnE,EAEA,SAAS,GAA6B,CAChC,EAAkB,QAAU,aAAe,EAAkB,QAAU,cACzE,EAAO,EAEP,EAAU,CAEd,CAEA,IAAM,MAA0B,CACzB,GAAU,EAAqB,CACtC,EAKA,OAHA,EAAkB,mBAAmB,cAAe,CAAiB,EACrE,EAAqB,MAER,CACP,IACJ,EAAW,GACX,EAAU,EACV,EAAkB,sBAAsB,cAAe,CAAiB,EAC1E,CACF"}

package/dist/autoplayUnlock.mjs

@@ -0,0 +1,58 @@
+//#region src/autoplayUnlock.ts
+var e = [
+	"touchend",
+	"click",
+	"keydown"
+], t = {
+	capture: !0,
+	passive: !0
+};
+function n(n) {
+	let { context: r, onUnlock: i } = n;
+	if (typeof document > "u") return () => {};
+	let a = r.resume;
+	if (typeof a != "function") return () => {};
+	let o = document, s = o.body ?? o, c = r, l = !1, u = !1, d = !1, f = () => {
+		if (l) {
+			for (let n of e) s.removeEventListener(n, p, t);
+			l = !1;
+		}
+	}, p = () => {
+		if (!(d || u)) {
+			u = !0, f();
+			try {
+				let e = r.createBuffer(1, 1, r.sampleRate), t = r.createBufferSource();
+				t.buffer = e, t.connect(r.destination), t.start(0), t.stop(0);
+			} catch (e) {
+				console.warn("[cacophony/autoplayUnlock] primer failed:", e);
+			}
+			a.call(r).then(() => {
+				if (u = !1, !d) try {
+					i();
+				} catch (e) {
+					console.error("[cacophony/autoplayUnlock] onUnlock callback threw:", e);
+				}
+			}, (e) => {
+				u = !1, !d && (console.warn("[cacophony/autoplayUnlock] resume failed:", e), h());
+			});
+		}
+	}, m = () => {
+		if (!(d || l || u)) {
+			for (let n of e) s.addEventListener(n, p, t);
+			l = !0;
+		}
+	};
+	function h() {
+		c.state === "suspended" || c.state === "interrupted" ? m() : f();
+	}
+	let g = () => {
+		d || h();
+	};
+	return c.addEventListener?.("statechange", g), h(), () => {
+		d || (d = !0, f(), c.removeEventListener?.("statechange", g));
+	};
+}
+//#endregion
+export { n as installAutoplayUnlock };
+
+//# sourceMappingURL=autoplayUnlock.mjs.map

package/dist/autoplayUnlock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoplayUnlock.mjs","names":[],"sources":["../src/autoplayUnlock.ts"],"sourcesContent":["import type { BaseContext } from \"./context\";\n\n/**\n * Autoplay unlock — Howler-parity automatic AudioContext resume on first\n * user gesture.\n *\n * On mobile browsers (especially iOS Safari) an `AudioContext` constructed\n * before any user interaction is created in `suspended` state. It will not\n * produce sound until BOTH:\n *\n *   1. `context.resume()` is called, AND\n *   2. an `AudioBufferSourceNode` is created and started inside the user\n *      gesture's call stack (the iOS \"primer\").\n *\n * Many callers do (1) but not (2), and hear silence with no obvious cause.\n * This module watches the context for suspension and arms `touchend` / `click`\n * / `keydown` listeners on `document.body` (or `document` as fallback). A\n * gesture resumes the context, plays a 1-sample silent primer inside the\n * gesture call stack, removes all three listeners, and calls the `onUnlock`\n * callback. If the context suspends again, the listeners are re-armed.\n *\n * Design adapted (not copied) from Howler.js `_unlockAudio` — MIT licensed.\n */\n\nconst UNLOCK_EVENT_TYPES: ReadonlyArray<\"touchend\" | \"click\" | \"keydown\"> = [\"touchend\", \"click\", \"keydown\"];\nconst GESTURE_LISTENER_OPTIONS = { capture: true, passive: true } as const;\n\n/**\n * A `Document`-like type with the methods we need. Avoids a hard dependency\n * on DOM lib types so the package keeps building when `lib: [\"dom\"]` is off.\n */\ninterface DocumentLike {\n  body?: EventTargetLike | null;\n  addEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n  removeEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n}\n\ninterface EventTargetLike {\n  addEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n  removeEventListener(type: string, listener: (ev: any) => void, options?: any): void;\n}\n\n/**\n * Options for `installAutoplayUnlock`.\n */\nexport interface AutoplayUnlockOptions {\n  /**\n   * The audio context that should be resumed and primed.\n   */\n  context: BaseContext;\n\n  /**\n   * Called after the context has been resumed and the primer buffer has been\n   * started. Used by `Cacophony` to emit the public `unlock` event.\n   * Errors thrown by the callback are caught and logged so a faulty listener\n   * cannot break the unlock flow.\n   */\n  onUnlock: () => void;\n}\n\n/**\n * Watch for context suspension and install unlock listeners while needed.\n * Returns a cleanup function that removes both the context watcher and any\n * armed gesture listeners (e.g. when a `Cacophony` instance is torn down).\n *\n * If the environment is non-browser (`document` is undefined), this is a\n * no-op and returns a no-op cleanup.\n *\n * @internal\n */\nexport function installAutoplayUnlock(opts: AutoplayUnlockOptions): () => void {\n  const { context, onUnlock } = opts;\n\n  // Server-side / non-browser: nothing to do.\n  if (typeof document === \"undefined\") {\n    return () => {};\n  }\n\n  // `BaseContext.resume` is optional. If this context has no resume() we\n  // cannot actually unlock it — installing gesture listeners would be noise,\n  // and firing the `unlock` event without a fulfilled resume() would violate\n  // the contract (caller would see `unlock` while `Cacophony.locked` stays\n  // true, since `locked` is derived from `context.state === \"suspended\"`).\n  // Treat the absence as \"this context isn't ours to unlock\" and bail.\n  const resume = (context as unknown as { resume?: () => Promise<void> }).resume;\n  if (typeof resume !== \"function\") {\n    return () => {};\n  }\n\n  const doc = document as unknown as DocumentLike;\n  const target: EventTargetLike = (doc.body as EventTargetLike | null | undefined) ?? doc;\n  const observableContext = context as unknown as {\n    state?: string;\n    addEventListener?: (type: string, listener: () => void) => void;\n    removeEventListener?: (type: string, listener: () => void) => void;\n  };\n\n  let armed = false;\n  let resumeInFlight = false;\n  let disposed = false;\n\n  const removeAll = () => {\n    if (!armed) return;\n    for (const type of UNLOCK_EVENT_TYPES) {\n      target.removeEventListener(type, handler, GESTURE_LISTENER_OPTIONS);\n    }\n    armed = false;\n  };\n\n  const handler = () => {\n    if (disposed || resumeInFlight) return;\n    resumeInFlight = true;\n\n    // Remove listeners FIRST so a re-entrant gesture cannot re-trigger us\n    // while resume() is in flight.\n    removeAll();\n\n    // Play the iOS primer INSIDE the gesture call stack. iOS requires that\n    // an AudioBufferSourceNode be created and started synchronously inside\n    // the gesture handler for the context to truly unlock — calling\n    // resume() alone is not sufficient. A 1-sample silent buffer is the\n    // minimum that satisfies the requirement and is inaudible.\n    try {\n      // BaseContext doesn't declare createBuffer because Cacophony's normal\n      // code path always feeds an AudioBuffer constructed externally; the\n      // primer needs to construct a 1-sample buffer in-place, so we widen\n      // the type locally here. Both AudioContext and OfflineAudioContext\n      // expose createBuffer.\n      const ctxWithCreateBuffer = context as unknown as {\n        createBuffer(numberOfChannels: number, length: number, sampleRate: number): unknown;\n      };\n      const buffer = ctxWithCreateBuffer.createBuffer(1, 1, context.sampleRate);\n      const source = context.createBufferSource();\n      source.buffer = buffer as any;\n      source.connect(context.destination);\n      // The load-bearing iOS pattern is start(0); stop(0) on a silent buffer\n      // INSIDE the gesture call stack. A 1-sample non-looping buffer would\n      // end on its own, but the pair is what the platform contract names.\n      source.start(0);\n      source.stop(0);\n    } catch (err) {\n      // Primer failure should not block the rest of the unlock; the\n      // context.resume() call below is still useful on platforms that do\n      // not require the primer.\n      console.warn(\"[cacophony/autoplayUnlock] primer failed:\", err);\n    }\n\n    // Resume the context, then emit unlock. The `unlock` event signals that\n    // audio is actually playable, so we must wait for resume() to fulfill\n    // before emitting. On rejection we surface the error and do NOT emit\n    // unlock — a failed resume is not an unlock. `resume` is guaranteed to\n    // be a function here (guarded at install time above).\n    resume.call(context).then(\n      () => {\n        resumeInFlight = false;\n        if (disposed) return;\n        try {\n          onUnlock();\n        } catch (err) {\n          console.error(\"[cacophony/autoplayUnlock] onUnlock callback threw:\", err);\n        }\n      },\n      (err: unknown) => {\n        resumeInFlight = false;\n        if (disposed) return;\n        console.warn(\"[cacophony/autoplayUnlock] resume failed:\", err);\n        syncGestureListeners();\n      },\n    );\n  };\n\n  const armAll = () => {\n    if (disposed || armed || resumeInFlight) return;\n    for (const type of UNLOCK_EVENT_TYPES) {\n      target.addEventListener(type, handler, GESTURE_LISTENER_OPTIONS);\n    }\n    armed = true;\n  };\n\n  function syncGestureListeners(): void {\n    if (observableContext.state === \"suspended\" || observableContext.state === \"interrupted\") {\n      armAll();\n    } else {\n      removeAll();\n    }\n  }\n\n  const handleStateChange = () => {\n    if (!disposed) syncGestureListeners();\n  };\n\n  observableContext.addEventListener?.(\"statechange\", handleStateChange);\n  syncGestureListeners();\n\n  return () => {\n    if (disposed) return;\n    disposed = true;\n    removeAll();\n    observableContext.removeEventListener?.(\"statechange\", handleStateChange);\n  };\n}\n"],"mappings":";AAwBA,IAAM,IAAsE;CAAC;CAAY;CAAS;AAAS,GACrG,IAA2B;CAAE,SAAS;CAAM,SAAS;AAAK;AA6ChE,SAAgB,EAAsB,GAAyC;CAC7E,IAAM,EAAE,YAAS,gBAAa;CAG9B,IAAI,OAAO,WAAa,KACtB,aAAa,CAAC;CAShB,IAAM,IAAU,EAAwD;CACxE,IAAI,OAAO,KAAW,YACpB,aAAa,CAAC;CAGhB,IAAM,IAAM,UACN,IAA2B,EAAI,QAA+C,GAC9E,IAAoB,GAMtB,IAAQ,IACR,IAAiB,IACjB,IAAW,IAET,UAAkB;EACjB,OACL;QAAK,IAAM,KAAQ,GACjB,EAAO,oBAAoB,GAAM,GAAS,CAAwB;GAEpE,IAAQ;EAF4D;CAGtE,GAEM,UAAgB;EAChB,WAAY,IAKhB;GAJA,IAAiB,IAIjB,EAAU;GAOV,IAAI;IASF,IAAM,IAAS,EAAoB,aAAa,GAAG,GAAG,EAAQ,UAAU,GAClE,IAAS,EAAQ,mBAAmB;IAO1C,AANA,EAAO,SAAS,GAChB,EAAO,QAAQ,EAAQ,WAAW,GAIlC,EAAO,MAAM,CAAC,GACd,EAAO,KAAK,CAAC;GACf,SAAS,GAAK;IAIZ,QAAQ,KAAK,6CAA6C,CAAG;GAC/D;GAOA,EAAO,KAAK,CAAO,EAAE,WACb;IACJ,QAAiB,IACb,IACJ,IAAI;KACF,EAAS;IACX,SAAS,GAAK;KACZ,QAAQ,MAAM,uDAAuD,CAAG;IAC1E;GACF,IACC,MAAiB;IAChB,IAAiB,IACb,OACJ,QAAQ,KAAK,6CAA6C,CAAG,GAC7D,EAAqB;GACvB,CACF;EArDU;CAsDZ,GAEM,UAAe;EACf,WAAY,KAAS,IACzB;QAAK,IAAM,KAAQ,GACjB,EAAO,iBAAiB,GAAM,GAAS,CAAwB;GAEjE,IAAQ;EAFyD;CAGnE;CAEA,SAAS,IAA6B;EACpC,AAAI,EAAkB,UAAU,eAAe,EAAkB,UAAU,gBACzE,EAAO,IAEP,EAAU;CAEd;CAEA,IAAM,UAA0B;EAC9B,AAAK,KAAU,EAAqB;CACtC;CAKA,OAHA,EAAkB,mBAAmB,eAAe,CAAiB,GACrE,EAAqB,SAER;EACP,MACJ,IAAW,IACX,EAAU,GACV,EAAkB,sBAAsB,eAAe,CAAiB;CAC1E;AACF"}

package/dist/basePlayback.cjs

@@ -0,0 +1,2 @@
+const e=require("./effectChain.cjs"),t=require("./eventEmitter.cjs"),n=require("./filters.cjs"),r=require("./pannerMixin.cjs"),i=require("./volumeMixin.cjs");var a=class extends r.PannerMixin(i.VolumeMixin(n.FilterManager)){source;_effectChain;_effectContext;_sendGains=new Map;_state=`unplayed`;origin;eventEmitter=new t.TypedEventEmitter;constructor(e){super(),this.origin=e}setEffectChainEndpoints(t,n){if(this._effectContext=t.context??this.origin.context,this._effectChain){this._effectChain.setEndpoints(t,n);return}this._effectChain=new e.EffectChain(t,n,this.constructor.name)}addEffect(e){try{return this.materializeEffect(e)}catch(e){return Promise.reject(e)}}_addSourceEffect(e){return this.materializeEffect(e)}_addFilterEffect(e){return this.materializeEffect(e,e=>{this._filters.push(e)})}materializeEffect(e,t){if(!this._effectChain||!this._effectContext)throw Error(`Cannot add an effect before the playback effect chain is initialized`);let n=this._effectChain,r=n.reserve(),i;try{i=e.build(this._effectContext)}catch(e){throw n.cancel(r),e}if(i instanceof Promise||typeof i==`object`&&i&&`then`in i)return Promise.resolve(i).then(e=>{let i=n.resolve(r,e);return t?.(i),i},e=>{throw n.cancel(r),e});try{let e=n.resolve(r,i);return t?.(e),Promise.resolve(e)}catch(e){throw n.cancel(r),e}}rampEffectParam(e,t,n,r){if(!this._effectChain)throw Error(`Cannot automate an effect before the playback effect chain is initialized`);this._effectChain.rampParam(e,t,n,r)}addFilter(e){if(!this._effectChain)throw Error(`Cannot add a filter before the playback effect chain is initialized`);this._effectChain.add(e,this._filters.length),this._filters.push(e)}removeFilter(e){if(!this._effectChain)throw Error(`Cannot remove a filter before the playback effect chain is initialized`);this._effectChain.remove(e),this._filters=this._filters.filter(t=>t!==e)}setFilterOrder(e){if(!this._effectChain)throw Error(`Cannot reorder filters before the playback effect chain is initialized`);let t=this._effectChain.nodes.filter(e=>!this._filters.includes(e));this._effectChain.setOrder([...e,...t]),this._filters=[...e]}setFilterBypassed(e,t){if(!this._effectChain)throw Error(`Cannot bypass a filter before the playback effect chain is initialized`);this._effectChain.setBypassed(e,t)}isFilterBypassed(e){return this._effectChain?.isBypassed(e)??!1}rampFilterParam(e,t,n,r){if(!this._effectChain)throw Error(`Cannot automate a filter before the playback effect chain is initialized`);this._effectChain.rampParam(e,t,n,r)}get isPlaying(){return this._state===`playing`}get isPaused(){return this._state===`paused`}markPlaying(){this._state=`playing`}markPaused(){this._state=`paused`}markStopped(){this._state=`stopped`}emitPlayStarted(e){this.markPlaying(),this.emit(`play`,this),e&&this.emit(`resume`,void 0),this.origin.cacophony?.emit(`globalPlay`,{source:this.origin,timestamp:Date.now()})}emitPaused(){this.markPaused(),this.emit(`pause`,void 0),this.origin.cacophony?.emit(`globalPause`,{source:this.origin,timestamp:Date.now()})}emitStopped(){this.markStopped(),this.emit(`stop`,void 0),this.origin.cacophony?.emit(`globalStop`,{source:this.origin,timestamp:Date.now()})}on(e,t){return this.eventEmitter.on(e,t)}off(e,t){this.eventEmitter.off(e,t)}emit(e,t){this.eventEmitter.emit(e,t)}async emitAsync(e,t){return this.eventEmitter.emitAsync(e,t)}fadeTo(e,t,n=`linear`,r){return this.emit(`fadeStart`,{target:e,duration:t,type:n}),super.fadeTo(e,t,n,r).then(()=>{this.emit(`fadeEnd`,void 0)})}cancelFade(){let e=this._isFading;super.cancelFade(),e&&this.emit(`fadeCancel`,void 0)}cleanup(){for(let e of this._sendGains.values())try{e.disconnect()}catch{}this._sendGains.clear(),this._effectChain?.destroy(),this._effectChain=void 0,this._effectContext=void 0,this.eventEmitter.removeAllListeners(),super.cleanup()}};exports.BasePlayback=a;
+//# sourceMappingURL=basePlayback.cjs.map

package/dist/basePlayback.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"basePlayback.cjs","names":[],"sources":["../src/basePlayback.ts"],"sourcesContent":["import type { Bus } from \"./bus\";\nimport type { FadeType, PlayOptions } from \"./cacophony\";\nimport type { PlaybackContainer } from \"./container\";\nimport type { AudioNode, BaseContext, BiquadFilterNode, GainNode } from \"./context\";\nimport { EffectChain } from \"./effectChain\";\nimport type { CacophonyEffect } from \"./effects\";\nimport { TypedEventEmitter } from \"./eventEmitter\";\nimport type { PlaybackEvents } from \"./events\";\nimport { FilterManager } from \"./filters\";\nimport { PannerMixin } from \"./pannerMixin\";\nimport { VolumeMixin } from \"./volumeMixin\";\n\nexport type PlaybackState = \"unplayed\" | \"playing\" | \"paused\" | \"stopped\";\n\nexport abstract class BasePlayback extends /* @__PURE__ */ PannerMixin(/* @__PURE__ */ VolumeMixin(FilterManager)) {\n  public source?: AudioNode;\n  protected _effectChain?: EffectChain;\n  private _effectContext?: BaseContext;\n  /**\n   * Per-playback send-gain allocations owned by the shared routing state\n   * machine. Cleanup disconnects every allocation deterministically.\n   */\n  _sendGains: Map<Bus, GainNode> = new Map();\n  protected _state: PlaybackState = \"unplayed\";\n  public origin: PlaybackContainer;\n  public eventEmitter: TypedEventEmitter<PlaybackEvents> = new TypedEventEmitter<PlaybackEvents>();\n\n  constructor(origin: PlaybackContainer) {\n    super();\n    this.origin = origin;\n  }\n\n  protected setEffectChainEndpoints(input: AudioNode, output: AudioNode): void {\n    this._effectContext =\n      (input.context as BaseContext | undefined) ??\n      (this.origin as PlaybackContainer & { context?: BaseContext }).context;\n    if (this._effectChain) {\n      this._effectChain.setEndpoints(input, output);\n      return;\n    }\n    this._effectChain = new EffectChain(input, output, this.constructor.name);\n  }\n\n  /** Build and splice an effect into this live playback's pre-panner chain. */\n  addEffect(effect: CacophonyEffect): Promise<AudioNode> {\n    try {\n      return this.materializeEffect(effect);\n    } catch (error) {\n      return Promise.reject(error);\n    }\n  }\n\n  /** @internal Source preplay path that preserves synchronous native-build failures. */\n  _addSourceEffect(effect: CacophonyEffect): Promise<AudioNode> {\n    return this.materializeEffect(effect);\n  }\n\n  /** @internal Materialize a source-level biquad recipe and retain filter API compatibility. */\n  _addFilterEffect(effect: CacophonyEffect): Promise<AudioNode> {\n    return this.materializeEffect(effect, (handle) => {\n      this._filters.push(handle as BiquadFilterNode);\n    });\n  }\n\n  private materializeEffect(effect: CacophonyEffect, onBuilt?: (handle: AudioNode) => void): Promise<AudioNode> {\n    if (!this._effectChain || !this._effectContext) {\n      throw new Error(\"Cannot add an effect before the playback effect chain is initialized\");\n    }\n    const chain = this._effectChain;\n    const reservation = chain.reserve();\n    let built;\n    try {\n      built = effect.build(this._effectContext);\n    } catch (error) {\n      chain.cancel(reservation);\n      throw error;\n    }\n    if (built instanceof Promise || (typeof built === \"object\" && built !== null && \"then\" in built)) {\n      return Promise.resolve(built).then(\n        (resolved) => {\n          const handle = chain.resolve(reservation, resolved);\n          onBuilt?.(handle);\n          return handle;\n        },\n        (error) => {\n          chain.cancel(reservation);\n          throw error;\n        },\n      );\n    }\n    try {\n      const handle = chain.resolve(reservation, built);\n      onBuilt?.(handle);\n      return Promise.resolve(handle);\n    } catch (error) {\n      chain.cancel(reservation);\n      throw error;\n    }\n  }\n\n  rampEffectParam(\n    handle: AudioNode,\n    paramName: string,\n    value: number,\n    options?: { duration?: number; type?: FadeType },\n  ): void {\n    if (!this._effectChain) {\n      throw new Error(\"Cannot automate an effect before the playback effect chain is initialized\");\n    }\n    this._effectChain.rampParam(handle, paramName, value, options);\n  }\n\n  addFilter(filter: BiquadFilterNode): void {\n    if (!this._effectChain) {\n      throw new Error(\"Cannot add a filter before the playback effect chain is initialized\");\n    }\n    this._effectChain.add(filter, this._filters.length);\n    this._filters.push(filter);\n  }\n\n  removeFilter(filter: BiquadFilterNode): void {\n    if (!this._effectChain) {\n      throw new Error(\"Cannot remove a filter before the playback effect chain is initialized\");\n    }\n    this._effectChain.remove(filter);\n    this._filters = this._filters.filter((candidate) => candidate !== filter);\n  }\n\n  setFilterOrder(filters: readonly BiquadFilterNode[]): void {\n    if (!this._effectChain) {\n      throw new Error(\"Cannot reorder filters before the playback effect chain is initialized\");\n    }\n    const nonFilters = this._effectChain.nodes.filter((node) => !this._filters.includes(node as BiquadFilterNode));\n    this._effectChain.setOrder([...filters, ...nonFilters]);\n    this._filters = [...filters];\n  }\n\n  setFilterBypassed(filter: BiquadFilterNode, bypassed: boolean): void {\n    if (!this._effectChain) {\n      throw new Error(\"Cannot bypass a filter before the playback effect chain is initialized\");\n    }\n    this._effectChain.setBypassed(filter, bypassed);\n  }\n\n  isFilterBypassed(filter: BiquadFilterNode): boolean {\n    return this._effectChain?.isBypassed(filter) ?? false;\n  }\n\n  rampFilterParam(\n    filter: BiquadFilterNode,\n    paramName: string,\n    value: number,\n    options?: { duration?: number; type?: FadeType },\n  ): void {\n    if (!this._effectChain) {\n      throw new Error(\"Cannot automate a filter before the playback effect chain is initialized\");\n    }\n    this._effectChain.rampParam(filter, paramName, value, options);\n  }\n\n  abstract play(options?: PlayOptions): [this];\n  abstract pause(): void;\n  abstract stop(): void;\n\n  /**\n   * Checks if the audio is currently playing.\n   */\n\n  get isPlaying(): boolean {\n    return this._state === \"playing\";\n  }\n\n  get isPaused(): boolean {\n    return this._state === \"paused\";\n  }\n\n  protected markPlaying(): void {\n    this._state = \"playing\";\n  }\n\n  protected markPaused(): void {\n    this._state = \"paused\";\n  }\n\n  protected markStopped(): void {\n    this._state = \"stopped\";\n  }\n\n  protected emitPlayStarted(isResume: boolean): void {\n    this.markPlaying();\n    this.emit(\"play\", this);\n    if (isResume) {\n      this.emit(\"resume\", undefined);\n    }\n    this.origin.cacophony?.emit(\"globalPlay\", {\n      source: this.origin,\n      timestamp: Date.now(),\n    });\n  }\n\n  protected emitPaused(): void {\n    this.markPaused();\n    this.emit(\"pause\", undefined);\n    this.origin.cacophony?.emit(\"globalPause\", {\n      source: this.origin,\n      timestamp: Date.now(),\n    });\n  }\n\n  protected emitStopped(): void {\n    this.markStopped();\n    this.emit(\"stop\", undefined);\n    this.origin.cacophony?.emit(\"globalStop\", {\n      source: this.origin,\n      timestamp: Date.now(),\n    });\n  }\n\n  /**\n   * Register event listener.\n   * @returns Cleanup function\n   */\n  on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): () => void {\n    return this.eventEmitter.on(event, listener);\n  }\n\n  /**\n   * Remove event listener.\n   */\n  off<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): void {\n    this.eventEmitter.off(event, listener);\n  }\n\n  public emit<K extends keyof PlaybackEvents>(event: K, data: PlaybackEvents[K]): void {\n    this.eventEmitter.emit(event, data);\n  }\n\n  public async emitAsync<K extends keyof PlaybackEvents>(event: K, data: PlaybackEvents[K]): Promise<void> {\n    return this.eventEmitter.emitAsync(event, data);\n  }\n\n  /**\n   * Fades the volume to a target value, emitting fadeStart and fadeEnd events.\n   */\n  fadeTo(\n    value: number,\n    duration: number,\n    type: FadeType = \"linear\",\n    options?: { startTime?: number; startValue?: number },\n  ): Promise<void> {\n    this.emit(\"fadeStart\", { target: value, duration, type });\n    return super.fadeTo(value, duration, type, options).then(() => {\n      this.emit(\"fadeEnd\", undefined);\n    });\n  }\n\n  /**\n   * Cancels any in-progress fade, emitting fadeCancel if a fade was active.\n   */\n  cancelFade(): void {\n    const wasFading = this._isFading;\n    super.cancelFade();\n    if (wasFading) {\n      this.emit(\"fadeCancel\", undefined);\n    }\n  }\n\n  cleanup(): void {\n    for (const sendGain of this._sendGains.values()) {\n      try {\n        sendGain.disconnect();\n      } catch {\n        // The node may already have been disconnected externally.\n      }\n    }\n    this._sendGains.clear();\n    this._effectChain?.destroy();\n    this._effectChain = undefined;\n    this._effectContext = undefined;\n    this.eventEmitter.removeAllListeners();\n    super.cleanup();\n  }\n}\n"],"mappings":"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"}

package/dist/basePlayback.d.ts

@@ -1,5 +1,5 @@
 import { Bus } from './bus';
-import { FadeType } from './cacophony';
+import { FadeType, PlayOptions } from './cacophony';
 import { PlaybackContainer } from './container';
 import { AudioNode, BaseContext, BiquadFilterNode, GainNode } from './context';
 import { EffectChain } from './effectChain';
@@ -26,7 +26,7 @@ declare const BasePlayback_base: (abstract new (...args: any[]) => {
     readonly filters: BiquadFilterNode[];
     addFilters(filters: BiquadFilterNode[]): void;
 }) & typeof FilterManager & (abstract new (...args: any[]) => import('./volumeMixin').VolumeControls);
-export declare abstract class BasePlayback extends BasePlayback_base {
+export declare abstract class BasePlayback extends /* @__PURE__ */ BasePlayback_base {
     source?: AudioNode;
     protected _effectChain?: EffectChain;
     private _effectContext?;
@@ -60,7 +60,7 @@ export declare abstract class BasePlayback extends BasePlayback_base {
         duration?: number;
         type?: FadeType;
     }): void;
-    abstract play(): [this];
+    abstract play(options?: PlayOptions): [this];
     abstract pause(): void;
     abstract stop(): void;
     /**
@@ -88,7 +88,10 @@ export declare abstract class BasePlayback extends BasePlayback_base {
     /**
      * Fades the volume to a target value, emitting fadeStart and fadeEnd events.
      */
-    fadeTo(value: number, duration: number, type?: FadeType): Promise<void>;
+    fadeTo(value: number, duration: number, type?: FadeType, options?: {
+        startTime?: number;
+        startValue?: number;
+    }): Promise<void>;
     /**
      * Cancels any in-progress fade, emitting fadeCancel if a fade was active.
      */

package/dist/basePlayback.mjs

@@ -0,0 +1,157 @@
+import { EffectChain as e } from "./effectChain.mjs";
+import { TypedEventEmitter as t } from "./eventEmitter.mjs";
+import { FilterManager as n } from "./filters.mjs";
+import { PannerMixin as r } from "./pannerMixin.mjs";
+import { VolumeMixin as i } from "./volumeMixin.mjs";
+//#region src/basePlayback.ts
+var a = class extends r(/* @__PURE__ */ i(n)) {
+	source;
+	_effectChain;
+	_effectContext;
+	_sendGains = /* @__PURE__ */ new Map();
+	_state = "unplayed";
+	origin;
+	eventEmitter = new t();
+	constructor(e) {
+		super(), this.origin = e;
+	}
+	setEffectChainEndpoints(t, n) {
+		if (this._effectContext = t.context ?? this.origin.context, this._effectChain) {
+			this._effectChain.setEndpoints(t, n);
+			return;
+		}
+		this._effectChain = new e(t, n, this.constructor.name);
+	}
+	addEffect(e) {
+		try {
+			return this.materializeEffect(e);
+		} catch (e) {
+			return Promise.reject(e);
+		}
+	}
+	_addSourceEffect(e) {
+		return this.materializeEffect(e);
+	}
+	_addFilterEffect(e) {
+		return this.materializeEffect(e, (e) => {
+			this._filters.push(e);
+		});
+	}
+	materializeEffect(e, t) {
+		if (!this._effectChain || !this._effectContext) throw Error("Cannot add an effect before the playback effect chain is initialized");
+		let n = this._effectChain, r = n.reserve(), i;
+		try {
+			i = e.build(this._effectContext);
+		} catch (e) {
+			throw n.cancel(r), e;
+		}
+		if (i instanceof Promise || typeof i == "object" && i && "then" in i) return Promise.resolve(i).then((e) => {
+			let i = n.resolve(r, e);
+			return t?.(i), i;
+		}, (e) => {
+			throw n.cancel(r), e;
+		});
+		try {
+			let e = n.resolve(r, i);
+			return t?.(e), Promise.resolve(e);
+		} catch (e) {
+			throw n.cancel(r), e;
+		}
+	}
+	rampEffectParam(e, t, n, r) {
+		if (!this._effectChain) throw Error("Cannot automate an effect before the playback effect chain is initialized");
+		this._effectChain.rampParam(e, t, n, r);
+	}
+	addFilter(e) {
+		if (!this._effectChain) throw Error("Cannot add a filter before the playback effect chain is initialized");
+		this._effectChain.add(e, this._filters.length), this._filters.push(e);
+	}
+	removeFilter(e) {
+		if (!this._effectChain) throw Error("Cannot remove a filter before the playback effect chain is initialized");
+		this._effectChain.remove(e), this._filters = this._filters.filter((t) => t !== e);
+	}
+	setFilterOrder(e) {
+		if (!this._effectChain) throw Error("Cannot reorder filters before the playback effect chain is initialized");
+		let t = this._effectChain.nodes.filter((e) => !this._filters.includes(e));
+		this._effectChain.setOrder([...e, ...t]), this._filters = [...e];
+	}
+	setFilterBypassed(e, t) {
+		if (!this._effectChain) throw Error("Cannot bypass a filter before the playback effect chain is initialized");
+		this._effectChain.setBypassed(e, t);
+	}
+	isFilterBypassed(e) {
+		return this._effectChain?.isBypassed(e) ?? !1;
+	}
+	rampFilterParam(e, t, n, r) {
+		if (!this._effectChain) throw Error("Cannot automate a filter before the playback effect chain is initialized");
+		this._effectChain.rampParam(e, t, n, r);
+	}
+	get isPlaying() {
+		return this._state === "playing";
+	}
+	get isPaused() {
+		return this._state === "paused";
+	}
+	markPlaying() {
+		this._state = "playing";
+	}
+	markPaused() {
+		this._state = "paused";
+	}
+	markStopped() {
+		this._state = "stopped";
+	}
+	emitPlayStarted(e) {
+		this.markPlaying(), this.emit("play", this), e && this.emit("resume", void 0), this.origin.cacophony?.emit("globalPlay", {
+			source: this.origin,
+			timestamp: Date.now()
+		});
+	}
+	emitPaused() {
+		this.markPaused(), this.emit("pause", void 0), this.origin.cacophony?.emit("globalPause", {
+			source: this.origin,
+			timestamp: Date.now()
+		});
+	}
+	emitStopped() {
+		this.markStopped(), this.emit("stop", void 0), this.origin.cacophony?.emit("globalStop", {
+			source: this.origin,
+			timestamp: Date.now()
+		});
+	}
+	on(e, t) {
+		return this.eventEmitter.on(e, t);
+	}
+	off(e, t) {
+		this.eventEmitter.off(e, t);
+	}
+	emit(e, t) {
+		this.eventEmitter.emit(e, t);
+	}
+	async emitAsync(e, t) {
+		return this.eventEmitter.emitAsync(e, t);
+	}
+	fadeTo(e, t, n = "linear", r) {
+		return this.emit("fadeStart", {
+			target: e,
+			duration: t,
+			type: n
+		}), super.fadeTo(e, t, n, r).then(() => {
+			this.emit("fadeEnd", void 0);
+		});
+	}
+	cancelFade() {
+		let e = this._isFading;
+		super.cancelFade(), e && this.emit("fadeCancel", void 0);
+	}
+	cleanup() {
+		for (let e of this._sendGains.values()) try {
+			e.disconnect();
+		} catch {}
+		this._sendGains.clear(), this._effectChain?.destroy(), this._effectChain = void 0, this._effectContext = void 0, this.eventEmitter.removeAllListeners(), super.cleanup();
+	}
+};
+//#endregion
+export { a as BasePlayback };
+
+//# sourceMappingURL=basePlayback.mjs.map