cacophony 0.25.1 → 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

@@ -39,10 +39,10 @@ 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 _filterNodes} — so {@link filters} order, identity, and
+     * 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.
@@ -273,15 +273,16 @@ export declare class Bus {
     private _refreshFilters;
     /**
      * Compute the desired ordered chain edge list from the current
-     * `_filterNodes`, skipping any node in {@link _bypassedFilters}: the series
+     * `_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 _filterNodes} (and thus in
+     * 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