cacophony 0.25.0 → 0.25.1

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.
@@ -25,9 +40,25 @@ export declare class Bus {
     readonly output: GainNode;
     private readonly _context;
     private readonly _filterNodes;
+    /**
+     * Filter nodes currently bypassed (skipped in the audible chain). A bypassed
+     * node stays in {@link _filterNodes} — 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,70 @@ 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
+     * `_filterNodes`, 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
+     * {@link filters}) but receive no inbound/outbound chain edge.
+     */
+    private _desiredFilterChainEdges;
     private _connectFilterChainEdge;
     private _disconnectFilterChainEdges;
     private _throwIfDestroyed;

package/dist/effects.d.ts

@@ -258,6 +258,33 @@ export declare class FdnReverbEffect implements CacophonyEffect {
     constructor(host: FdnReverbHost, options?: FdnReverbOptions);
     build(context: BaseContext): Promise<AudioWorkletNode>;
 }
+/**
+ * String aliases for the integer mode indices that {@link WaveshaperOptions},
+ * {@link TremoloOptions} and {@link ModulatedDelayOptions} flow straight through
+ * as `parameterData`. An AudioParam can only carry a number, so these maps are
+ * applied inside each effect's `build()` to translate a string mode into its
+ * integer index BEFORE the options become `parameterData`. The index assignments
+ * mirror the worklet shells' `*_BY_INDEX` arrays exactly
+ * (`processors/waveshaper.ts`, `processors/tremolo.ts`,
+ * `processors/modulated-delay.ts`). Declared locally so this module does not
+ * import from the worklet/processor modules (keeping that boundary intact).
+ */
+declare const WAVESHAPER_SHAPE_TO_INDEX: {
+    readonly hardclip: 0;
+    readonly tanh: 1;
+};
+type WaveshaperShapeAlias = keyof typeof WAVESHAPER_SHAPE_TO_INDEX;
+declare const TREMOLO_SHAPE_TO_INDEX: {
+    readonly sine: 0;
+    readonly triangle: 1;
+    readonly square: 2;
+};
+type TremoloShapeAlias = keyof typeof TREMOLO_SHAPE_TO_INDEX;
+declare const MODULATED_DELAY_INTERPOLATION_TO_INDEX: {
+    readonly cubic: 0;
+    readonly linear: 1;
+};
+type ModulatedDelayInterpolationAlias = keyof typeof MODULATED_DELAY_INTERPOLATION_TO_INDEX;
 /**
  * Construction-time configuration for a {@link WaveshaperEffect}, mirroring the
  * `waveshaper` AudioWorkletProcessor's AudioParam set (see
@@ -273,8 +300,13 @@ export declare class FdnReverbEffect implements CacophonyEffect {
 export interface WaveshaperOptions {
     /** Pre-gain (drive) into the nonlinearity. Default 1. Range 0..100; >1 = harder saturation. */
     drive?: number;
-    /** Nonlinearity index: 0 = hard clip (polynomial F0, eq.25), 1 = tanh soft clip (F0 = log cosh, eq.20). Default 0. */
-    shape?: number;
+    /**
+     * Nonlinearity: 0 = hard clip (polynomial F0, eq.25), 1 = tanh soft clip
+     * (F0 = log cosh, eq.20). Default 0. Accepts either the integer index or the
+     * matching string alias (`"hardclip"` = 0, `"tanh"` = 1), translated to the
+     * index in `build()`.
+     */
+    shape?: number | WaveshaperShapeAlias;
     /** Wet/dry mix (0..1); 0 = dry bypass, 1 = fully shaped. Default 1. */
     mix?: number;
     /** Post-nonlinearity output gain (linear). Default 1. Range 0..4. */
@@ -323,8 +355,12 @@ export interface ModulatedDelayOptions {
     blend?: number;
     /** Wet (modulated tap) gain (feedforward). Default 0.7071. Range 0..1. */
     feedforward?: number;
-    /** Interpolation index: 0 = cubic (4-tap Lagrange N=3), 1 = linear (2-tap N=1). Default 0. */
-    interpolation?: number;
+    /**
+     * Interpolation: 0 = cubic (4-tap Lagrange N=3), 1 = linear (2-tap N=1).
+     * Default 0. Accepts either the integer index or the matching string alias
+     * (`"cubic"` = 0, `"linear"` = 1), translated to the index in `build()`.
+     */
+    interpolation?: number | ModulatedDelayInterpolationAlias;
 }
 /**
  * CacophonyEffect that builds a `modulated-delay` AudioWorkletNode — Dattorro's
@@ -402,8 +438,12 @@ export interface TremoloOptions {
     rate?: number;
     /** Modulation depth (0 = bypass, 1 = full 0..1 swing). Default 0.5. Range 0..1. */
     depth?: number;
-    /** LFO shape index: 0 = sine, 1 = triangle, 2 = square. Default 0. */
-    shape?: number;
+    /**
+     * LFO shape: 0 = sine, 1 = triangle, 2 = square. Default 0. Accepts either
+     * the integer index or the matching string alias (`"sine"` = 0,
+     * `"triangle"` = 1, `"square"` = 2), translated to the index in `build()`.
+     */
+    shape?: number | TremoloShapeAlias;
     /** Per-channel LFO phase offset in degrees (0 = mono, 90 = quadrature, 180 = auto-pan). Default 0. Range 0..180. */
     stereoPhase?: number;
 }