cacophony 0.25.0 → 0.28.0

package/README.md

@@ -350,9 +350,9 @@ API documented below. The Bus class supersedes the older user-built
 A `Bus` is a named summing node with its own filter chain and per-edge
 gain on outgoing connections. Sounds and synths route to buses via
 `routeTo`; buses can carry rich effects (not just BiquadFilter) by
-adding a `CacophonyEffect` to their filter chain. The built-in
-`cacophony.createReverb()` returns a DattorroReverb effect ready to drop
-into a bus.
+adding a `CacophonyEffect` to their filter chain. The built-in
+`cacophony.createReverb()` and `cacophony.createImpulseResponse()` effects
+are ready to drop into a bus.
 
 ```typescript
 // 1. Create a named bus
@@ -393,29 +393,60 @@ the same node as `cacophony.globalGainNode`, so the existing
 transparently. Routing a sound to `cacophony.master` (or never calling
 `routeTo`) sends it through the master path.
 
-### Bus-to-bus routing with per-edge gain
+### Bus-to-bus routing with per-edge gain
 
 ```typescript
 const groupBus = cacophony.createBus('group');
 const sendBus = cacophony.createBus('aux');
 groupBus.connect(sendBus, 0.2);   // 20% send: groupBus.output → sendGain(0.2) → sendBus.input
-groupBus.disconnect(sendBus);     // tears down the sendGain too
-```
-
-### Adding custom effects to a bus
-
-Bus filter chains accept Cacophony-built BiquadFilters and any
-`CacophonyEffect`. Raw third-party AudioNodes are rejected unless you
-wrap them explicitly with `cacophony.shareEffect(node)` — this surfaces
-the shared-state intent (the same node will run on every bus that adds it).
+groupBus.disconnect(sendBus);     // tears down the sendGain too
+```
+
+### Native impulse responses
+
+`createImpulseResponse()` builds a native `ConvolverNode` effect from an
+`AudioBuffer` or URL. URL-backed IRs are fetched and decoded once per audio
+context and URL; failed loads are evicted so a later call can retry. Convolver
+normalization defaults to `false`, preserving measured IR gain.
+
+```typescript
+// Wet-only send bus: returns a single ConvolverNode internally.
+const chamber = cacophony.createBus('chamber');
+await chamber.addFilter(cacophony.createImpulseResponse('/irs/chamber.wav'));
+vocals.routeTo(chamber, 0.25);
+
+// Inline dry/wet graph: exposes dry/wet AudioParams for bus automation.
+const room = cacophony.createImpulseResponse('/irs/room.wav', {
+  dry: 0.7,
+  wet: 0.3,
+  normalize: false,
+});
+const handle = await bus.addFilter(room);
+bus.rampFilterParam(handle, 'wet', 0.6, { duration: 500 });
+```
+
+### Adding custom effects to a bus
+
+Bus filter chains accept Cacophony-built BiquadFilters and any
+`CacophonyEffect`. Raw third-party AudioNodes are rejected unless you
+wrap them explicitly with `cacophony.shareEffect(node)` — this surfaces
+the shared-state intent (the same node will run on every bus that adds it).
+An effect can build either a single `AudioNode` or a `BuiltEffectGraph` with
+separate `input`/`output` endpoints for multi-node processors.
 
 ```typescript
 const eq = cacophony.createBiquadFilter({ type: 'highshelf', frequency: 4000, gain: 3 });
 await bus.addFilter(eq);
 
-const sharedWorklet = new AudioWorkletNode(cacophony.context, 'my-fx');
-await bus.addFilter(cacophony.shareEffect(sharedWorklet));
-```
+const sharedWorklet = new AudioWorkletNode(cacophony.context, 'my-fx');
+await bus.addFilter(cacophony.shareEffect(sharedWorklet));
+```
+
+FOA binaural decoding is available in both forms. Use
+`createFoaDecoder()` when you want explicit custom wiring through
+`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.
 
 ### Cleaning up
 

package/dist/bus.d.ts

@@ -1,3 +1,4 @@
+import { FadeType } from './cacophony';
 import { AudioNode, BaseContext, BiquadFilterNode, GainNode } from './context';
 import { CacophonyEffect } from './effects';
 /**
@@ -6,6 +7,20 @@ import { CacophonyEffect } from './effects';
  * directly to it — escape hatch for advanced wiring).
  */
 export type BusConnectionTarget = Bus | AudioNode;
+/**
+ * Structural contract a routed source (e.g. a {@link Sound}) implements so a
+ * Bus can move it off itself before teardown. Declared here — rather than
+ * importing `Sound` — to avoid an import cycle (`sound.ts` already imports
+ * `Bus`). A Bus only ever needs this one method on its inbound sources.
+ */
+export interface BusRoutedSource {
+    /**
+     * Called by {@link Bus.drainTo} to move this source off the draining bus
+     * onto `target`. The source reroutes its primary route and/or any send that
+     * targeted `bus`.
+     */
+    _onBusDrained(bus: Bus, target: Bus): void;
+}
 /**
  * A named summing node with a filter chain and per-edge send gain. See
  * module-level docstring for topology.
@@ -24,10 +39,26 @@ export declare class Bus {
      */
     readonly output: GainNode;
     private readonly _context;
-    private readonly _filterNodes;
+    private readonly _filterEntries;
+    /**
+     * Filter nodes currently bypassed (skipped in the audible chain). A bypassed
+     * node stays in {@link _filterEntries} — so {@link filters} order, identity, and
+     * its live AudioParams are preserved — but {@link _desiredFilterChainEdges}
+     * builds the series chain over the NON-bypassed filters only, wiring the
+     * signal around it. Membership is by node identity.
+     */
+    private readonly _bypassedFilters;
     private readonly _filterChainEdges;
     private readonly _sendGains;
     private readonly _directConnections;
+    /**
+     * Inbound sources currently routed to this bus (primary route and/or sends).
+     * A Web Audio node cannot enumerate its own inputs, so sources register
+     * themselves here (via {@link _registerRoutedSource}) when they route to
+     * this bus and unregister on reroute/cleanup. {@link drainTo} walks this set
+     * to move live sounds off the bus before it is torn down.
+     */
+    private readonly _routedSources;
     /**
      * Hook invoked by the owning Cacophony instance to remove this bus from
      * the named-bus registry on destroy. Anonymous buses leave this undefined.
@@ -61,10 +92,15 @@ export declare class Bus {
      *   `cacophony.shareEffect(node)` (or a proper CacophonyEffect class) to
      *   make the shared-state intent explicit.
      *
+     * @returns the built AudioNode that was added to the chain. For a biquad this
+     *   is the argument itself; for a {@link CacophonyEffect} it is the node
+     *   produced by `build`. The returned handle can be passed to
+     *   {@link rampFilterParam} to automate the node's parameters. Existing
+     *   callers that ignore the result keep working unchanged.
      * @throws if the bus has been destroyed, or if the argument is a raw
      *   AudioNode that is not a Cacophony-built biquad.
      */
-    addFilter(arg: BiquadFilterNode | CacophonyEffect | AudioNode): Promise<void>;
+    addFilter(arg: BiquadFilterNode | CacophonyEffect | AudioNode): Promise<AudioNode>;
     /**
      * Remove a filter node from the bus's chain. The node must have been added
      * via {@link addFilter}; the same object identity is used to match.
@@ -72,6 +108,93 @@ export declare class Bus {
      * @throws if the bus has been destroyed or if the node was never added.
      */
     removeFilter(node: AudioNode): void;
+    /**
+     * Reorder the existing filter chain. `nodes` must be a PERMUTATION of the
+     * current filters — the same set of node objects (matched by identity), the
+     * same length, with no duplicates — just in a new order. Because
+     * {@link _refreshFilters} is incremental, only the edges that actually move
+     * are reconnected; unchanged edges are left untouched.
+     *
+     * @throws if the bus has been destroyed, or if `nodes` is not a permutation
+     *   of the current filters.
+     */
+    setFilterOrder(nodes: readonly AudioNode[]): void;
+    /**
+     * Bypass (or un-bypass) a filter without removing it from the chain. A
+     * bypassed filter stays in {@link filters} — its order, identity, and live
+     * AudioParams are preserved (so an automation target survives a bypass) — but
+     * it is skipped in the audible series chain: the signal is wired around it.
+     * Un-bypassing wires it back in at its original position.
+     *
+     * The reconnect goes through the incremental {@link _refreshFilters}, so only
+     * the seam around `node` is touched — the rest of the chain is left connected.
+     *
+     * @param node A filter node currently on this bus (from {@link addFilter} or
+     *   {@link filters}).
+     * @param bypassed `true` to skip the node, `false` to wire it back in. A no-op
+     *   if the node is already in the requested state.
+     * @throws if the bus has been destroyed, or if `node` was never added to this
+     *   bus.
+     */
+    setFilterBypassed(node: AudioNode, bypassed: boolean): void;
+    /**
+     * Whether `node` is currently bypassed (skipped in the audible chain). Returns
+     * `false` for nodes that were never added to this bus.
+     */
+    isFilterBypassed(node: AudioNode): boolean;
+    /**
+     * Ramp an effect node's parameter to a target value over time. This is the
+     * uniform automation handle for filter-chain effects: pass a node obtained
+     * from {@link addFilter} (or the {@link filters} getter) and the name of the
+     * parameter to drive.
+     *
+     * Parameter resolution:
+     * - If `node` exposes a worklet-style `parameters` AudioParamMap, the param
+     *   is resolved via `parameters.get(paramName)` (e.g. a worklet effect's
+     *   named params).
+     * - Otherwise, if `node[paramName]` is itself an AudioParam (native nodes
+     *   such as a biquad expose `.frequency` / `.Q` / `.gain` directly), that is
+     *   used.
+     *
+     * Ramp shape (mirrors the codebase fade convention): the target time base is
+     * `node.context.currentTime`. With no `duration` (or `duration <= 0`) the
+     * value is set immediately via `setValueAtTime(value, now)`. Otherwise the
+     * start is pinned with `setValueAtTime(param.value, now)` and the value ramps
+     * to `now + duration / 1000` (milliseconds) using `linearRampToValueAtTime`
+     * (default) or `exponentialRampToValueAtTime` when `type` is `"exponential"`
+     * (an exponential target of 0 is floored to 0.0001, matching `fadeTo`).
+     *
+     * Automation degrades gracefully: if `node` is not on this bus, or the
+     * parameter cannot be resolved to an AudioParam, a warning is logged and the
+     * call is a no-op. The only condition that throws is a destroyed bus.
+     *
+     * @param node A filter node currently on this bus (from {@link addFilter}).
+     * @param paramName The name of the parameter to automate.
+     * @param value The target value.
+     * @param options.duration Ramp duration in milliseconds. Absent/`<= 0` sets
+     *   the value immediately.
+     * @param options.type Ramp curve, `"linear"` (default) or `"exponential"`.
+     * @throws if the bus has been destroyed.
+     */
+    rampFilterParam(node: AudioNode, paramName: string, value: number, options?: {
+        duration?: number;
+        type?: FadeType;
+    }): void;
+    /**
+     * Resolve the named {@link AudioParam} on a node. Tries the worklet
+     * `parameters` map first, then a directly-exposed native param
+     * (`node[paramName]`). Returns `undefined` if neither yields an AudioParam.
+     *
+     * Detection is structural (duck-typed), never `instanceof` — the mocked test
+     * context may not provide the `AudioParam` global.
+     */
+    private _resolveAudioParam;
+    /**
+     * Structural AudioParam check: a value is treated as an AudioParam if it
+     * exposes the ramp scheduling methods. Avoids `instanceof AudioParam` so it
+     * works under the standardized-audio-context mock (which may lack the global).
+     */
+    private _isAudioParam;
     /**
      * Connect this bus's output to another bus or to a raw AudioNode.
      *
@@ -95,22 +218,71 @@ export declare class Bus {
      * @throws if the bus has been destroyed.
      */
     disconnect(target: BusConnectionTarget): void;
+    /**
+     * Register an inbound source that routes to this bus (primary and/or send).
+     * Called by the source when it begins routing here. Idempotent (Set). Safe
+     * to call without a destroyed guard — registration during normal routing
+     * must never throw — but a destroyed bus has nothing to drain, so this
+     * early-returns once destroyed.
+     *
+     * @internal
+     */
+    _registerRoutedSource(source: BusRoutedSource): void;
+    /**
+     * Unregister an inbound source (it rerouted away or was cleaned up). No-op
+     * if the source was never registered.
+     *
+     * @internal
+     */
+    _unregisterRoutedSource(source: BusRoutedSource): void;
+    /**
+     * Move every source currently routed to this bus onto `target`, so live
+     * sounds keep feeding a live bus instead of the dead `input` after this bus
+     * is torn down. Each registered source's {@link BusRoutedSource._onBusDrained}
+     * reroutes its primary route and/or the send that targeted this bus.
+     *
+     * @throws if this bus has been destroyed, or if `target` is this bus.
+     */
+    drainTo(target: Bus): void;
     /**
      * Tear down the bus — disconnects input, output, every send-gain, every
      * filter, then deregisters from the owner Cacophony's named-bus map.
      * Subsequent `addFilter`/`removeFilter`/`connect`/`disconnect` calls throw.
      *
-     * Sounds routed to a destroyed bus fall back to master on their next
+     * If `options.drainTo` is provided, every source routed to this bus is first
+     * rerouted onto that bus (via {@link drainTo}) so live sounds keep playing
+     * through a live bus. With no options the default teardown is unchanged:
+     * sounds routed to the destroyed bus fall back to master on their next
      * playback (the routeTo machinery checks `destroyed` at preplay).
      */
-    destroy(): void;
+    destroy(options?: {
+        drainTo?: Bus;
+    }): void;
     /**
-     * Rebuild the chain `input → [filter1 → ... → filterN] → output`. Called
-     * after any add/remove of a filter. Disconnects only the internal chain
-     * edges this bus created, then reapplies the chain. The output node's edges
-     * to downstream targets are not touched.
+     * Reconcile the live chain to `input → [filter1 → ... → filterN] → output`.
+     * Called after any add/remove/reorder of a filter. This is an INCREMENTAL
+     * diff, not a full rebuild: it disconnects only edges that are no longer part
+     * of the desired chain and connects only edges that are newly required,
+     * leaving edges present in both the old and new chain connected and
+     * untouched (no audible click on the unchanged portion of the chain).
+     *
+     * Edges are matched by OBJECT IDENTITY on both endpoints. Only this bus's own
+     * internal `input → ... → output` edges are touched — never a broad
+     * `node.disconnect()`, never the outbound send/direct edges.
      */
     private _refreshFilters;
+    /**
+     * Compute the desired ordered chain edge list from the current
+     * `_filterEntries`, skipping any node in {@link _bypassedFilters}: the series
+     * chain is built over the NON-bypassed filters only. With no active (non-
+     * bypassed) filters — whether the bus has no filters at all or every filter is
+     * bypassed — the desired list is `[[input, output]]` (the direct edge);
+     * otherwise `[[input, a1], [a1, a2], ..., [aN, output]]` over the active
+     * filters `a1..aN`. Bypassed nodes stay in {@link _filterEntries} (and thus in
+     * {@link filters}) but receive no inbound/outbound chain edge.
+     */
+    private _desiredFilterChainEdges;
+    private _normalizeBuiltEffect;
     private _connectFilterChainEdge;
     private _disconnectFilterChainEdges;
     private _throwIfDestroyed;

package/dist/cacophony.d.ts

@@ -1,7 +1,7 @@
 import { Bus } from './bus';
 import { ICache } from './cache';
 import { AudioBuffer, AudioListener, AudioNode, AudioWorkletNode, BaseContext, BiquadFilterNode, ChannelMergerNode, ChannelSplitterNode, GainNode, PannerNode } from './context';
-import { CacophonyEffect, DynamicsEffect, DynamicsOptions, FdnReverbEffect, FdnReverbOptions, FoaDecoder, FoaDecoderOptions, ModulatedDelayEffect, ModulatedDelayOptions, PhaserEffect, PhaserOptions, ReverbEffect, ReverbOptions, TremoloEffect, TremoloOptions, WaveshaperEffect, WaveshaperOptions } from './effects';
+import { CacophonyEffect, DynamicsEffect, DynamicsOptions, FdnReverbEffect, FdnReverbOptions, FoaDecoder, FoaDecoderEffect, FoaDecoderOptions, ImpulseResponseEffect, ImpulseResponseOptions, ImpulseResponseSource, ModulatedDelayEffect, ModulatedDelayOptions, PhaserEffect, PhaserOptions, ReverbEffect, ReverbOptions, TremoloEffect, TremoloOptions, WaveshaperEffect, WaveshaperOptions } from './effects';
 import { CacophonyEvents } from './events';
 import { Group } from './group';
 import { MediaStreamSound, MediaStreamSoundOptions } from './mediaStream';
@@ -11,6 +11,7 @@ import { ThreeDOptions } from './pannerMixin';
 import { TimeStretchOptions } from './processors/timestretch-core';
 import { Sound } from './sound';
 import { Synth } from './synth';
+import { WorkletModule } from './worklets';
 export type SoundType = "html" | "streaming" | "buffer" | "oscillator";
 /**
  * Represents a 3D position in space.
@@ -148,6 +149,12 @@ export declare class Cacophony {
      * `loadFoaHrir` calls share a single fetch/decode.
      */
     private foaHrirCache;
+    /**
+     * Per-context, per-URL decoded impulse-response cache. Stores in-flight
+     * promises so concurrent effect builds for the same context/URL share the
+     * same fetch/decode. Rejected promises are evicted so the caller can retry.
+     */
+    private impulseResponseCache;
     private finalizationRegistry;
     private eventEmitter;
     private cache;
@@ -253,162 +260,24 @@ export declare class Cacophony {
     off<K extends keyof CacophonyEvents>(event: K, listener: (data: CacophonyEvents[K]) => void): void;
     emit<K extends keyof CacophonyEvents>(event: K, data: CacophonyEvents[K]): void;
     emitAsync<K extends keyof CacophonyEvents>(event: K, data: CacophonyEvents[K]): Promise<void>;
-    loadWorklets(signal?: AbortSignal): Promise<void>;
-    loadStereoToBFormatWorklet(signal?: AbortSignal): Promise<void>;
-    /**
-     * Idempotently registers the `phase-vocoder` AudioWorkletProcessor (peak-based
-     * pitch-shifter with Identity Phase-Locking, Laroche & Dolson 1999 WASPAA) on
-     * this context. Safe to call repeatedly — subsequent calls short-circuit via
-     * the per-context {@link loadedAudioWorklets} set. Cross-context: pass
-     * `context` so a node built against a bus on a different context loads there.
-     */
-    loadPhaseVocoder(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a `phase-vocoder` AudioWorkletNode. Caller is expected to have
-     * loaded the module already (via {@link loadPhaseVocoder} or {@link loadWorklets}).
-     * Uses the same construct/fallback path as {@link createWorkletNode}. The
-     * returned node carries a single `pitchFactor` AudioParam (1 = no shift).
-     */
-    createPhaseVocoderNode(options?: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the DattorroReverb AudioWorkletProcessor on this
-     * context. Safe to call repeatedly — subsequent calls short-circuit via
-     * the {@link loadedAudioWorklets} set used by
-     * {@link loadAudioWorkletModule}.
-     *
-     * @param signal Optional abort signal forwarded to the module load.
-     * @param context Optional BaseContext to load the worklet on. Defaults to
-     *   the host Cacophony instance's `context`. Supplied so a
-     *   {@link ReverbEffect} added to a bus whose context is NOT this host's
-     *   own (cross-context use) can load the worklet on the right context.
-     */
-    loadDattorroReverb(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a DattorroReverb AudioWorkletNode. Caller is expected to have
-     * loaded the module already (via {@link loadDattorroReverb} or by reaching
-     * here through {@link ReverbEffect.build}). Uses the same construct/fallback
-     * path as {@link createWorkletNode}.
-     *
-     * @param options AudioWorkletNode construction options.
-     * @param context Optional BaseContext to construct on. Defaults to the
-     *   host Cacophony instance's `context`. See {@link loadDattorroReverb}
-     *   for the cross-context rationale.
-     */
-    createDattorroReverbNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the `dynamics` AudioWorkletProcessor (feed-forward
-     * compressor/limiter/expander/gate, Giannoulis 2012) on this context. Safe to
-     * call repeatedly — subsequent calls short-circuit via the per-context
-     * {@link loadedAudioWorklets} set. Cross-context: pass `context` so a
-     * {@link DynamicsEffect} added to a bus on a different context loads there.
-     */
-    loadDynamics(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a `dynamics` AudioWorkletNode. Caller is expected to have loaded
-     * the module already (via {@link loadDynamics} or by reaching here through
-     * {@link DynamicsEffect.build}). Uses the same construct/fallback path as
-     * {@link createWorkletNode}.
-     */
-    createDynamicsNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the `fdn-reverb` AudioWorkletProcessor (Feedback
-     * Delay Network reverb — lossless paraunitary Hadamard feedback per Schlecht
-     * & Habets 2019, per-line absorption T60 per Jot 1991, velvet-noise diffusion
-     * per Fagerström 2020) on this context. Safe to call repeatedly — subsequent
-     * calls short-circuit via the per-context {@link loadedAudioWorklets} set.
-     * Cross-context: pass `context` so an {@link FdnReverbEffect} added to a bus
-     * on a different context loads there.
-     */
-    loadFdnReverb(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs an `fdn-reverb` AudioWorkletNode. Caller is expected to have
-     * loaded the module already (via {@link loadFdnReverb} or by reaching here
-     * through {@link FdnReverbEffect.build}). Uses the same construct/fallback
-     * path as {@link createWorkletNode}.
-     */
-    createFdnReverbNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the `waveshaper` AudioWorkletProcessor (antialiased
-     * distortion/waveshaper via first-order Antiderivative Antialiasing, Parker,
-     * Zavalishin & Le Bivic 2016, DAFx-16) on this context. Safe to call
-     * repeatedly — subsequent calls short-circuit via the per-context
-     * {@link loadedAudioWorklets} set. Cross-context: pass `context` so a
-     * {@link WaveshaperEffect} added to a bus on a different context loads there.
-     */
-    loadWaveshaper(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a `waveshaper` AudioWorkletNode. Caller is expected to have
-     * loaded the module already (via {@link loadWaveshaper} or by reaching here
-     * through {@link WaveshaperEffect.build}). Uses the same construct/fallback
-     * path as {@link createWorkletNode}.
-     */
-    createWaveshaperNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
     /**
-     * Idempotently registers the `modulated-delay` AudioWorkletProcessor —
-     * Dattorro's unified modulated-delay circuit (JAES 1997, Fig. 36) backing
-     * delay/chorus/flanger/vibrato/doubling, with Lagrange FIR fractional-delay
-     * interpolation (Laakso 1996) — on this context. Safe to call repeatedly —
-     * subsequent calls short-circuit via the per-context {@link loadedAudioWorklets}
-     * set. Cross-context: pass `context` so a {@link ModulatedDelayEffect} added to
-     * a bus on a different context loads there.
+     * Eagerly registers every bundled AudioWorklet module on this context. This is
+     * OPTIONAL — effects load their own worklet lazily in `build`, and the
+     * pitch-shift path loads the phase-vocoder on first use. Call this up front to
+     * pay the registration cost ahead of time. Idempotent per context (each module
+     * short-circuits via the per-context {@link loadedAudioWorklets} set).
      */
-    loadModulatedDelay(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a `modulated-delay` AudioWorkletNode. Caller is expected to have
-     * loaded the module already (via {@link loadModulatedDelay} or by reaching here
-     * through {@link ModulatedDelayEffect.build}). Uses the same construct/fallback
-     * path as {@link createWorkletNode}.
-     */
-    createModulatedDelayNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the `phaser` AudioWorkletProcessor — a classic
-     * MXR/Univibe-style allpass-cascade phase shifter (Smith STAN-M-21; PASP §8.9:
-     * a cascade of first-order allpass sections at a common LFO-swept break
-     * frequency, summed additively with the dry signal to sweep notches) on this
-     * context. Safe to call repeatedly — subsequent calls short-circuit via the
-     * per-context {@link loadedAudioWorklets} set. Cross-context: pass `context` so
-     * a {@link PhaserEffect} added to a bus on a different context loads there.
-     */
-    loadPhaser(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a `phaser` AudioWorkletNode. Caller is expected to have loaded the
-     * module already (via {@link loadPhaser} or by reaching here through
-     * {@link PhaserEffect.build}). Uses the same construct/fallback path as
-     * {@link createWorkletNode}.
-     */
-    createPhaserNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the `tremolo` AudioWorkletProcessor — LFO-driven
-     * amplitude modulation (a VCA swung by a low-frequency oscillator; standard AM
-     * theory + Dattorro 1997 p.776 quadrature stereo LFO + Mitcheltree et al.
-     * DAFx23 LFO framing) on this context. Safe to call repeatedly — subsequent
-     * calls short-circuit via the per-context {@link loadedAudioWorklets} set.
-     * Cross-context: pass `context` so a {@link TremoloEffect} added to a bus on a
-     * different context loads there.
-     */
-    loadTremolo(signal?: AbortSignal, context?: BaseContext): Promise<void>;
-    /**
-     * Constructs a `tremolo` AudioWorkletNode. Caller is expected to have loaded the
-     * module already (via {@link loadTremolo} or by reaching here through
-     * {@link TremoloEffect.build}). Uses the same construct/fallback path as
-     * {@link createWorkletNode}.
-     */
-    createTremoloNode(options: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
-    /**
-     * Idempotently registers the `loudness-meter` AudioWorkletProcessor (ITU-R
-     * BS.1770-5 momentary / short-term / integrated loudness + true-peak) on this
-     * context. Safe to call repeatedly — subsequent calls short-circuit via the
-     * per-context {@link loadedAudioWorklets} set. Cross-context: pass `context`
-     * so a meter tapping a bus on a different context loads there.
-     */
-    loadLoudnessMeter(signal?: AbortSignal, context?: BaseContext): Promise<void>;
+    loadWorklets(signal?: AbortSignal): Promise<void>;
+    loadStereoToBFormatWorklet(signal?: AbortSignal): Promise<void>;
     /**
-     * Constructs a `loudness-meter` AudioWorkletNode. Caller is expected to have
-     * loaded the module already (via {@link loadLoudnessMeter} or {@link createLoudnessMeter}).
-     * The node is a PASS-THROUGH metering tap (1 input, 1 output) that posts
-     * momentary/short-term/integrated loudness and true-peak back over its port.
+     * The single worklet-effect construction seam ({@link WorkletEffectHost}).
+     * Idempotently registers `worklet`'s module on `context` — or this host's own
+     * context when omitted, honoring the cross-context contract that effects'
+     * `build(context)` promises — then constructs the AudioWorkletNode with
+     * `parameterData`. Every worklet-backed {@link CacophonyEffect} routes through
+     * here, as does the phase-vocoder pitch-shift path ({@link Playback.setPitchShift}).
      */
-    createLoudnessMeterNode(options?: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
+    buildWorkletEffect(worklet: WorkletModule, parameterData: Record<string, number>, context?: BaseContext): Promise<AudioWorkletNode>;
     /**
      * Fetches and decodes the bundled order-1 SH-HRIR
      * (`sh_hrir_order_1.wav`, from Omnitone, Apache-2.0 — see
@@ -426,6 +295,18 @@ export declare class Cacophony {
      *   a different context decodes the HRIR on the right context.
      */
     loadFoaHrir(context?: BaseContext): Promise<AudioBuffer>;
+    /**
+     * Fetches and decodes an impulse response URL on the requested audio context,
+     * memoized per context and URL. Buffers decoded by one context are not reused
+     * on another context, matching Web Audio's context-bound decode behavior.
+     *
+     * @param url Impulse-response audio URL.
+     * @param context Optional decode context. Defaults to this Cacophony instance.
+     * @param signal Optional abort signal for the fetch. Decode itself is not
+     *   abortable in Web Audio, but an already-aborted signal is honored before
+     *   decode starts.
+     */
+    loadImpulseResponseBuffer(url: string, context?: BaseContext, signal?: AbortSignal): Promise<AudioBuffer>;
     createWorkletNode(name: string, url: string, signal?: AbortSignal, options?: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
     createStereoToBFormatNode(signal?: AbortSignal): Promise<AudioWorkletNode>;
     /**
@@ -439,6 +320,7 @@ export declare class Cacophony {
     private markWorkletLoadedOn;
     private loadAudioWorkletModule;
     private createAbortError;
+    private waitForImpulseResponseLoad;
     private createMediaSound;
     clearMemoryCache(): void;
     createOscillator(options: OscillatorOptions, panType?: PanType): Synth;
@@ -529,6 +411,14 @@ export declare class Cacophony {
      * chain via `bus.addFilter(effect)`.
      */
     createReverb(options?: ReverbOptions): ReverbEffect;
+    /**
+     * Creates a native ConvolverNode impulse-response effect. Pass an AudioBuffer
+     * for an already-decoded IR or a URL to fetch/decode through the per-context
+     * IR cache. The default is wet-only (`dry: 0`, `wet: 1`) and returns a single
+     * ConvolverNode when added to a bus; setting `dry` or non-unity `wet` builds
+     * an owned dry/wet endpoint graph exposing `dry` and `wet` automation params.
+     */
+    createImpulseResponse(source: ImpulseResponseSource, options?: ImpulseResponseOptions): ImpulseResponseEffect;
     /**
      * Creates a Feedback Delay Network (FDN) {@link CacophonyEffect} — an
      * algorithmic reverb with a lossless degree-0 paraunitary Hadamard feedback
@@ -668,8 +558,8 @@ export declare class Cacophony {
      * Omnitone's WY/ZX 2-stereo-ConvolverNode packing and the bundled order-1
      * SH-HRIR.
      *
-     * It is 4-channel-in / 2-channel-out, so it is NOT a `CacophonyEffect` and is
-     * NOT added via `bus.addFilter`. Wire it EXPLICITLY using its two endpoints:
+     * It is 4-channel-in / 2-channel-out; this method returns the explicit
+     * endpoint object for custom graph wiring:
      * feed FOA into `decoder.input` (4-ch) and route `decoder.output` (2-ch
      * stereo) downstream:
      * ```ts
@@ -682,6 +572,13 @@ export declare class Cacophony {
      * `createStereoToBFormatNode` (the perceptual, approximate stereo-upmix path).
      */
     createFoaDecoder(options?: FoaDecoderOptions, context?: BaseContext): Promise<FoaDecoder>;
+    /**
+     * Creates a bus-filter wrapper around {@link FoaDecoder}. Use this 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 custom manual
+     * wiring, use {@link createFoaDecoder} instead.
+     */
+    createFoaDecoderEffect(options?: FoaDecoderOptions): FoaDecoderEffect;
     /**
      * Creates an ITU-R BS.1770-5 {@link LoudnessMeter} that TAPS the output of a
      * target node without altering the audible path. The meter reports momentary