Web Audio context the bus's nodes live on.
Name to register under, or null for an anonymous bus.
Optionalinput: GainNode
Optional pre-existing GainNode to use as the input. Used by
the master bus to alias cacophony.globalGainNode. If omitted, a
fresh GainNode is allocated.
OptionalonDestroy: () => void
Optional registry-cleanup hook fired by destroy().
Whether destroy() may tear down this bus.
ReadonlyinputEntry node — connect upstream sources here (sound playbacks, other bus outputs).
ReadonlynameStable name for registry lookup, or null for anonymous buses.
ReadonlyoutputExit node — connected to downstream targets (other bus inputs, master, raw nodes) via connect.
True after destroy has been called.
Live filter chain (read-only view).
Output node gain — controls the overall level the bus sends downstream.
Internal
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
Unregister an inbound source (it rerouted away or was cleaned up). No-op if the source was never registered.
Add a filter node to the bus's chain. Accepts:
cacophony.createBiquadFilter) → added directly to the chain.build(context) is awaited; the resulting
node is added to the chain.cacophony.shareEffect(node) (or a proper CacophonyEffect class) to
make the shared-state intent explicit.the built AudioNode that was added to the chain. For a biquad this
is the argument itself; for a CacophonyEffect it is the node
produced by build. The returned handle can be passed to
rampFilterParam to automate the node's parameters. Existing
callers that ignore the result keep working unchanged.
Connect this bus's output to another bus or to a raw AudioNode.
If gain is omitted or equal to 1, connect directly (output →
targetInput). If gain is provided, allocate an internal GainNode for
per-edge attenuation: output → sendGain → targetInput. The sendGain is
tracked so disconnect can tear it down cleanly.
Re-connecting a target that is already wired is a no-op for the direct
case; for a gained connection, the existing sendGain's gain.value is
updated in place (no new edge is allocated).
Optionalgain: numberTear 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.
If options.drainTo is provided, every source routed to this bus is first
rerouted onto that bus (via 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).
Optionaloptions: { drainTo?: Bus }Disconnect this bus's output from a target previously connected with connect. Tears down the allocated sendGain (if any). No-op if the target was never connected.
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 BusRoutedSource._onBusDrained
reroutes its primary route and/or the send that targeted this bus.
Whether node is currently bypassed (skipped in the audible chain). Returns
false for nodes that were never added to this bus.
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 addFilter (or the filters getter) and the name of the parameter to drive.
Parameter resolution:
node exposes a worklet-style parameters AudioParamMap, the param
is resolved via parameters.get(paramName) (e.g. a worklet effect's
named params).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.
A filter node currently on this bus (from addFilter).
The name of the parameter to automate.
The target value.
Optionaloptions: { duration?: number; type?: FadeType }
Optionalduration?: numberRamp duration in milliseconds. Absent/<= 0 sets
the value immediately.
Optionaltype?: FadeTypeRamp curve, "linear" (default) or "exponential".
Bypass (or un-bypass) a filter without removing it from the chain. A bypassed filter stays in 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 EffectChain, so only the
seam around node is touched — the rest of the chain is left connected.
true to skip the node, false to wire it back in. A no-op
if the node is already in the requested state.
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 the owned
EffectChain reconciles incrementally, only the edges that actually
move are reconnected; unchanged edges are left untouched.
A named summing node with a filter chain and per-edge send gain. See module-level docstring for topology.