cacophony 0.23.0 → 0.24.0

package/dist/cacophony.d.ts

@@ -1,12 +1,14 @@
 import { Bus } from './bus';
 import { ICache } from './cache';
 import { AudioBuffer, AudioListener, AudioNode, AudioWorkletNode, BaseContext, BiquadFilterNode, ChannelMergerNode, ChannelSplitterNode, GainNode, PannerNode } from './context';
-import { CacophonyEffect, ReverbEffect, ReverbOptions } from './effects';
+import { CacophonyEffect, DynamicsEffect, DynamicsOptions, FdnReverbEffect, FdnReverbOptions, FoaDecoder, FoaDecoderOptions, 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';
+import { LoudnessMeter } from './meters/loudness-meter';
 import { MicrophoneStream } from './microphone';
 import { ThreeDOptions } from './pannerMixin';
+import { TimeStretchOptions } from './processors/timestretch-core';
 import { Sound } from './sound';
 import { Synth } from './synth';
 export type SoundType = "html" | "streaming" | "buffer" | "oscillator";
@@ -137,6 +139,15 @@ export declare class Cacophony {
      * the second construct would throw with no module registered.
      */
     private loadedAudioWorklets;
+    /**
+     * Per-context cache of the decoded order-1 SH-HRIR `AudioBuffer` used by
+     * {@link FoaDecoder}. Keyed on the context (like
+     * {@link loadedAudioWorklets}) because `decodeAudioData` produces a buffer
+     * bound to ONE context's sample rate; a buffer decoded on context A must not
+     * be reused on context B. Stores the in-flight Promise so concurrent
+     * `loadFoaHrir` calls share a single fetch/decode.
+     */
+    private foaHrirCache;
     private finalizationRegistry;
     private eventEmitter;
     private cache;
@@ -205,6 +216,32 @@ export declare class Cacophony {
      * @throws Error if the context does not support offline rendering
      */
     startRendering(): Promise<AudioBuffer>;
+    /**
+     * OFFLINE independent time-stretch: change an AudioBuffer's tempo WITHOUT
+     * changing its pitch, returning a NEW AudioBuffer of length ≈
+     * `round(buffer.length · factor)` at the same sample rate.
+     *
+     * Algorithm: Phase Gradient Heap Integration (PGHI) per Zdeněk Průša & Nicki
+     * Holighaus, "Phase Vocoder Done Right" (EUSIPCO 2017 / arXiv:2202.07382).
+     * The signal is STFT'd, the synthesis phase is reconstructed by integrating
+     * the analysis-phase time/frequency gradients along the magnitude ridges
+     * (max-heap), then overlap-added at the stretched synthesis hop. No peak
+     * picking and no transient detection. Each channel is processed independently.
+     *
+     * This is an OFFLINE buffer transform, NOT a real-time worklet: the project's
+     * OLA worklet base is unity-rate (analysis hop == synthesis hop, fixed to the
+     * 128-sample render quantum) and cannot change the time base in real time. A
+     * genuine independent stretch needs analysis hop ≠ synthesis hop, which only
+     * the whole-buffer offline path provides.
+     *
+     * @param buffer The source AudioBuffer to time-stretch.
+     * @param factor Stretch factor (`> 0`). `> 1` lengthens (slower tempo), `< 1`
+     *               shortens (faster tempo); pitch is preserved either way.
+     * @param options Optional PGHI parameters (fftSize, analysisHop, tol, seed).
+     * @returns A new, time-stretched AudioBuffer.
+     * @throws If the context cannot create buffers, or `factor <= 0`.
+     */
+    timeStretchBuffer(buffer: AudioBuffer, factor: number, options?: TimeStretchOptions): AudioBuffer;
     /**
      * Register event listener.
      * @returns Cleanup function
@@ -218,6 +255,21 @@ export declare class Cacophony {
     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
@@ -243,6 +295,137 @@ export declare class Cacophony {
      *   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.
+     */
+    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>;
+    /**
+     * 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.
+     */
+    createLoudnessMeterNode(options?: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
+    /**
+     * Fetches and decodes the bundled order-1 SH-HRIR
+     * (`sh_hrir_order_1.wav`, from Omnitone, Apache-2.0 — see
+     * `src/assets/NOTICE`) into an `AudioBuffer`, memoized per context. The
+     * buffer is the 4-channel (ACN rows W,Y,Z,X) SH-domain HRIR consumed by
+     * {@link FoaDecoder} to drive its WY/ZX stereo ConvolverNodes
+     * (Ahrens 2022 eq.31 decode).
+     *
+     * The WAV is 48 kHz; `decodeAudioData` resamples it to the context's sample
+     * rate automatically when they differ (standard Web Audio behavior, which
+     * Omnitone relies on).
+     *
+     * @param context Optional BaseContext to decode on. Defaults to this host's
+     *   own `context`. Supplied so a {@link FoaDecoder} added to a bus on
+     *   a different context decodes the HRIR on the right context.
+     */
+    loadFoaHrir(context?: BaseContext): Promise<AudioBuffer>;
     createWorkletNode(name: string, url: string, signal?: AbortSignal, options?: AudioWorkletNodeOptions, context?: BaseContext): Promise<AudioWorkletNode>;
     createStereoToBFormatNode(signal?: AbortSignal): Promise<AudioWorkletNode>;
     /**
@@ -346,6 +529,180 @@ export declare class Cacophony {
      * chain via `bus.addFilter(effect)`.
      */
     createReverb(options?: ReverbOptions): ReverbEffect;
+    /**
+     * Creates a Feedback Delay Network (FDN) {@link CacophonyEffect} — an
+     * algorithmic reverb with a lossless degree-0 paraunitary Hadamard feedback
+     * matrix (Schlecht & Habets 2019), per-delay-line absorption filters setting
+     * the reverberation time T60 (Jot & Chaigne 1991), and multiplication-free
+     * velvet-noise input diffusion (Fagerström et al. 2020). The effect's
+     * `build` lazily registers the worklet module (no-op if already loaded) and
+     * constructs the AudioWorkletNode with the supplied {@link FdnReverbOptions}
+     * as `parameterData`. Add the returned effect to a {@link Bus} via
+     * `bus.addFilter(effect)`.
+     */
+    createFdnReverb(options?: FdnReverbOptions): FdnReverbEffect;
+    /**
+     * Creates a dynamics {@link CacophonyEffect} configured as a COMPRESSOR
+     * (ratio > 1 reduces the level of signals above threshold). Implements the
+     * feed-forward design of Giannoulis, Massberg & Reiss 2012. Add the returned
+     * effect to a {@link Bus} via `bus.addFilter(effect)`. The same machinery
+     * (gain computer + log-domain smooth-branching detector) backs the limiter
+     * and gate presets below.
+     */
+    createCompressor(options?: DynamicsOptions): DynamicsEffect;
+    /**
+     * Creates a dynamics {@link CacophonyEffect} preset as a LIMITER — a
+     * compressor with an effectively infinite ratio so output is clamped at the
+     * threshold (Giannoulis 2012 eqs 18-19). The ratio is fixed to the worklet's
+     * limiter sentinel; caller-supplied `ratio` is ignored. Other params
+     * (threshold, knee, attack, release, makeup) remain configurable.
+     */
+    createLimiter(options?: Omit<DynamicsOptions, "ratio">): DynamicsEffect;
+    /**
+     * Creates a dynamics {@link CacophonyEffect} preset as a downward EXPANDER /
+     * GATE — ratio < 1 so signals BELOW the threshold are pushed further down
+     * (Giannoulis 2012 p.403). The default `ratio` of 0.1 gives gate-like
+     * downward expansion; pass a `ratio` closer to 1 for gentler expansion.
+     */
+    createGate(options?: DynamicsOptions): DynamicsEffect;
+    /**
+     * Creates a {@link WaveshaperEffect} — an antialiased distortion/waveshaper
+     * implementing first-order Antiderivative Antialiasing (Parker, Zavalishin &
+     * Le Bivic 2016, DAFx-16): y[n] = (F0(x_n) - F0(x_{n-1}))/(x_n - x_{n-1})
+     * (eq.9), with an f(midpoint) fallback at the 0/0 singularity (eq.10). Ships
+     * two nonlinearities — `shape: 0` hard clip (polynomial F0, eq.25), `shape: 1`
+     * tanh soft clip (F0 = log cosh, eq.20). Carries an inherent 0.5-sample group
+     * delay (eq.17). Add the returned effect to a {@link Bus} via
+     * `bus.addFilter(effect)`.
+     */
+    createWaveshaper(options?: WaveshaperOptions): WaveshaperEffect;
+    /**
+     * Creates a {@link WaveshaperEffect} preset as a DISTORTION — the tanh soft
+     * clipper (`shape: 1`, F0 = log cosh, Parker 2016 eq.20) with a default drive
+     * of 4 for an audible saturated tone. A convenience wrapper over
+     * {@link createWaveshaper}; caller-supplied options override the defaults.
+     */
+    createDistortion(options?: WaveshaperOptions): WaveshaperEffect;
+    /**
+     * Creates a {@link ModulatedDelayEffect} preset as a DELAY / ECHO — Dattorro's
+     * unified modulated-delay circuit (JAES 1997, Fig. 36) with the modulation OFF
+     * (`depth: 0`, `rate: 0`). Echo knobs (Table 6): full dry `blend: 1` plus a
+     * unity wet tap `feedforward: 1`; feedback defaults to 0 (a single tap) but is
+     * caller-configurable for a regenerating echo (|feedback| < 1, Table 6). The
+     * 250 ms tap sits in the echo range (Table 7). All knobs are exposed.
+     */
+    createDelay(options?: ModulatedDelayOptions): ModulatedDelayEffect;
+    /**
+     * Creates a {@link ModulatedDelayEffect} preset as a (white) CHORUS — Dattorro
+     * Table 6 white-chorus knobs `blend: 0.7071`, `feedforward: 1`,
+     * `feedback: 0.7071` (blend = feedback, feedforward = 1, the negative-feedback
+     * path that minimizes the spectral aberration of a plain dry+wet chorus). A
+     * 9 ms tap modulated 4 ms at 0.5 Hz sits in the chorus range (Table 7).
+     *
+     * NOTE: Dattorro's white chorus (p.776) combines this negative-feedback path
+     * with ALLPASS fractional-delay interpolation. This implementation uses the
+     * white-chorus knob settings but substitutes cubic-Lagrange interpolation
+     * (Laakso 1996) — transient-safe under modulation (Laakso p.52), trading some
+     * high-frequency trough depth versus a true allpass-interpolated white chorus.
+     */
+    createChorus(options?: ModulatedDelayOptions): ModulatedDelayEffect;
+    /**
+     * Creates a {@link ModulatedDelayEffect} preset as a FLANGER — Dattorro Table 6
+     * flanger knobs `blend: 0.7071`, `feedforward: 0.7071` (blend = feedforward for
+     * the deepest comb trough), `feedback: -0.7071` (negative feedback deepens the
+     * troughs). A short 5 ms tap swept 4 ms at 0.25 Hz gives the classic flange
+     * (Table 7).
+     */
+    createFlanger(options?: ModulatedDelayOptions): ModulatedDelayEffect;
+    /**
+     * Creates a {@link ModulatedDelayEffect} preset as a VIBRATO — Dattorro Table 6
+     * vibrato knobs `blend: 0`, `feedforward: 1`, `feedback: 0` (100% wet, no dry
+     * path, no feedback), so only the pitch-modulated delayed signal is heard. A
+     * 5 ms tap swept 3 ms at 5 Hz (Table 7).
+     */
+    createVibrato(options?: ModulatedDelayOptions): ModulatedDelayEffect;
+    /**
+     * Creates a {@link ModulatedDelayEffect} preset as DOUBLING ("double tracking")
+     * — Dattorro Table 6 doubling knobs `blend: 0.7071`, `feedforward: 0.7071`,
+     * `feedback: 0` (no feedback). A ~20 ms tap (Table 7 doubling nominal) with a
+     * gentle 1 ms / 0.4 Hz wobble fattens a single take into two.
+     */
+    createDoubling(options?: ModulatedDelayOptions): ModulatedDelayEffect;
+    /**
+     * Creates a {@link PhaserEffect} — a classic MXR/Univibe-style phase shifter: a
+     * cascade of first-order allpass sections at a common LFO-swept break frequency
+     * summed additively with the dry signal to sweep notches through the spectrum
+     * (Smith STAN-M-21; PASP §8.9). Two allpass sections per notch (default 4
+     * sections = 2 notches). Add the returned effect to a {@link Bus} via
+     * `bus.addFilter(effect)`.
+     */
+    createPhaser(options?: PhaserOptions): PhaserEffect;
+    /**
+     * Creates a {@link TremoloEffect} — LFO-driven amplitude modulation (a VCA
+     * swung by a low-frequency oscillator). The gain swings between (1 - depth)
+     * and 1, never inverting (a true tremolo, not ring modulation). Anchored to
+     * standard AM theory, Dattorro 1997 (p.776) for the quadrature stereo LFO, and
+     * Mitcheltree et al. (DAFx23) for the LFO-driven-effect framing. `shape` selects
+     * the LFO waveform (0 = sine, 1 = triangle, 2 = square); `stereoPhase` offsets
+     * the per-channel LFO. Add the returned effect to a {@link Bus} via
+     * `bus.addFilter(effect)`.
+     */
+    createTremolo(options?: TremoloOptions): TremoloEffect;
+    /**
+     * Creates a {@link TremoloEffect} preset as an AUTO-PAN — a tremolo with
+     * `stereoPhase: 180`, so the left and right channel gains modulate in
+     * anti-phase (the sound swings hard between the speakers). The 180-deg
+     * per-channel LFO offset is Dattorro's stereo-modulation convention (p.776). A
+     * convenience wrapper over {@link createTremolo}; caller options override the
+     * preset.
+     */
+    createAutoPan(options?: TremoloOptions): TremoloEffect;
+    /** The default audio context for this Cacophony instance (used by
+     * {@link FoaDecoder} when no explicit context is supplied). */
+    defaultContext(): BaseContext;
+    /**
+     * Creates a {@link FoaDecoder} — a standalone first-order ambisonic (FOA) ->
+     * binaural FORMAT CONVERTER built from native Web Audio nodes (no worklet).
+     * It decodes a 4-channel ACN/SN3D `[W, Y, Z, X]` signal to headphone stereo
+     * via the per-SH-channel HRIR decode of Ahrens 2022 (eq.31), using
+     * 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:
+     * feed FOA into `decoder.input` (4-ch) and route `decoder.output` (2-ch
+     * stereo) downstream:
+     * ```ts
+     *   const decoder = await cacophony.createFoaDecoder();
+     *   foaSource.connect(decoder.input);
+     *   decoder.output.connect(bus.input); // or context.destination
+     * ```
+     * Build is async (the bundled HRIR is fetched + decoded). Pair it with
+     * {@link encodeMonoToFoaSN3D} (clean, physically correct) or with
+     * `createStereoToBFormatNode` (the perceptual, approximate stereo-upmix path).
+     */
+    createFoaDecoder(options?: FoaDecoderOptions, context?: BaseContext): Promise<FoaDecoder>;
+    /**
+     * 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
+     * (400 ms), short-term (3 s), and gated integrated loudness in LKFS/LUFS, plus
+     * true-peak level in dBTP (Annex 2 4× oversampling).
+     *
+     * The tap is a BRANCH: the target's output is connected to the metering
+     * worklet in ADDITION to its existing forward edge, and the worklet's output
+     * is routed through an owned zero-gain sink to keep the branch silent and live.
+     * By default the target is the
+     * master bus output (`master.output`), measuring everything that reaches the
+     * destination — the integrated-loudness target. Pass a {@link Bus} to meter
+     * one bus's output, or any {@link AudioNode} to meter that node.
+     *
+     * Lazily registers the `loudness-meter` worklet module (no-op if already
+     * loaded) on the target's context, then constructs the node and branch-taps.
+     *
+     * @param target Node or bus whose output to meter. Defaults to the master bus.
+     * @returns A {@link LoudnessMeter} handle exposing the live readings.
+     */
+    createLoudnessMeter(target?: Bus | AudioNode): Promise<LoudnessMeter>;
     /**
      * Creates a new {@link Bus}. If `name` is provided, the bus is registered
      * so {@link getBus} can look it up by name. Anonymous buses (no name) are

package/dist/context.d.ts

@@ -62,8 +62,21 @@ export interface ChannelSplitterNode extends AudioNode {
 }
 export interface ChannelMergerNode extends AudioNode {
 }
+export interface ConvolverNode extends AudioNode {
+    buffer: AudioBuffer | null;
+    normalize: boolean;
+}
 export interface AudioWorkletNode extends AudioNode {
     readonly port: MessagePort;
+    /**
+     * The node's AudioParam map (Web Audio `AudioParamMap`). Modelled as the
+     * minimal `get(name)` surface this library uses to drive worklet params
+     * (e.g. the phase-vocoder `pitchFactor`). Optional because test/mock
+     * contexts may not synthesise the param map.
+     */
+    readonly parameters?: {
+        get(name: string): AudioParam | undefined;
+    };
 }
 export interface AudioBufferSourceNode extends AudioNode {
     buffer: AudioBuffer | null;
@@ -125,6 +138,8 @@ export interface BaseContext {
     createStereoPanner(): StereoPannerNode;
     createChannelSplitter?(numberOfOutputs?: number): ChannelSplitterNode;
     createChannelMerger?(numberOfInputs?: number): ChannelMergerNode;
+    createConvolver?(): ConvolverNode;
+    createBuffer?(numberOfChannels: number, length: number, sampleRate: number): AudioBuffer;
     createOscillator(): OscillatorNode;
     decodeAudioData(audioData: ArrayBuffer): Promise<AudioBuffer>;
     decodeAudioData(audioData: ArrayBuffer, successCallback: (buffer: AudioBuffer) => void, errorCallback?: (error: DOMException) => void): Promise<AudioBuffer>;