Bus
A named mix bucket with its own gain stage, FX chain, voice limit, and optional sidechain key.
Twenty sounds are playing and the player drags the "music" slider. Without somewhere to put that instruction, you are iterating live voices and hoping you catch the ones that started half a frame ago.
A bus is a named mix bucket. It owns a gain stage, an FX chain, a voice
limit, and an optional sidechain key. Sounds are routed to it by name at
play time, and the level you set on the bus applies to everything on it,
including voices that start later. See Bus
for the full reference.
What does a bus actually do?
You declare it once in createEngine and then talk to it by
name. Level changes and mutes ramp over 10 ms internally, so a slider drag
doesn't click. fadeTo takes a curve when you want something
longer than a slider.
API surface
class Bus {
readonly name: string;
readonly input: GainNode; // connect voices/sources here
readonly output: GainNode; // connected to master
level: number; // setter ramps over 10ms (click-free)
muted: boolean; // setter ramps over 10ms
fadeTo(target: number, duration: number, curve?: FadeCurve): Promise<void>; // duration in seconds
voiceCount: number;
voices(): readonly Voice[];
concurrency: ConcurrencyConfig | null;
setConcurrency(c: ConcurrencyConfig | null): void;
addFx(fx: FxInsert): void;
removeFx(fx: FxInsert): void;
fx(): readonly FxInsert[];
meter(): { rms: number; peak: number }; // live amplitude readout (lazy analyser tap)
send(target: Bus, options?: { amount?: number; post?: boolean }): Send;
removeSend(send: Send): void;
sends(): readonly Send[];
solo(on?: boolean): void; // engine coordinates "any soloed → mute the rest"
unsolo(): void;
readonly soloed: boolean;
}Live demo
Slam the slider. No click. The fade buttons run the same gain through a curve.
Recipes
Direct level vs. fadeTo
// Smooth fade — won't pop because of the 10ms internal ramp on direct writes,
// or use fadeTo() with a curve for longer transitions.
engine.bus('music').level = 0.5;
await engine.bus('music').fadeTo(0, 1.2, 'equal-power');Enumerate active voices on a bus
const bus = engine.bus('sfx');
console.log('voices on this bus:', bus.voiceCount);
for (const v of bus.voices()) v.fade({ to: 0, duration: 0.2 });Live VU meter via bus.meter()
Returns { rms, peak } as linear values in [0..1].
The first call attaches a passive AnalyserNode tap. Nothing is allocated
until you read, and the audio path is unchanged. The
rhythm-metronome
example drives a VU bar and a per-voice peak meter from it.
// Drive a VU bar from bus.meter() inside your render loop.
function tick() {
const m = engine.bus('music').meter();
vuBar.style.width = (m.rms * 200) + '%';
peakDot.style.left = (m.peak * 100) + '%';
requestAnimationFrame(tick);
}
requestAnimationFrame(tick);
// First call lazily attaches an AnalyserNode as a sibling of bus.output —
// no cost until you read. Subsequent calls reuse the same analyser.Sends: route a copy of one bus into another
A send routes a configurable share of one bus's signal into another, instead of inserting an effect directly on the source. It is the Wwise primitive for shared reverb. "Send 30 % of music to a verb-only bus" is two lines, and the amount is adjustable while audio is playing.
// Send 30% of music to a dedicated reverb bus.
const verbSend = engine.bus('music').send(engine.bus('reverb'), { amount: 0.3 });
// Adjust live; the setter ramps over 10ms to avoid clicks.
verbSend.amount = 0.5;
await verbSend.fadeTo(0, 1.2); // smooth fade-out
// Remove the send entirely.
verbSend.dispose();
// or
engine.bus('music').removeSend(verbSend);
// Pre-fader / pre-FX tap (rare — useful for monitor sends that should
// hear the dry signal regardless of how the source bus is faded).
engine.bus('music').send(engine.bus('monitor'), { post: false });Solo: A/B one bus without disturbing the rest
The engine coordinates the global rule. While any bus is in the solo set,
every non-soloed bus is muted through the same 10 ms ramp, and when the
set drains, every bus is restored. Solo is tracked separately from
muted, so un-soloing returns each bus to whatever the user
had set.
// Solo this bus — every other bus is muted while the solo set is non-empty.
engine.bus('voice').solo();
engine.bus('music').solo(); // additive — both still audible
engine.bus('voice').unsolo(); // music is still soloed; everyone else still muted
engine.bus('music').unsolo(); // solo set drains — every bus restored
// Solo state is independent of muted: un-soloing returns each bus to its
// own .muted setting, not unconditionally to "audible".Bus groups: address several buses at once
A BusGroup is a logical handle
rather than an audio node. It applies level,
fadeTo, muted and solo to every
member in parallel. Reach for it when several buses always move together.
Combat is usually weapons plus enemies plus environment; a voice group is
usually dialogue plus effort sounds.
// Group several buses so a single call addresses all of them.
const combat = engine.busGroup('combat', [
engine.bus('weapons'),
engine.bus('enemies'),
engine.bus('environment'),
]);
combat.level = 0.5; // sets every member's level
await combat.fadeTo(0, 0.8); // fades every member in parallel
combat.muted = true; // mutes the whole group
combat.solo(); // solos every member at once
// Look up later by name.
engine.busGroup('combat').level = 1;Pitfalls
output.gain.value directly.Related
- Concurrency sets the voice-limit policy on a bus.
- Mixer is the wider bus graph this sits in.
- Ducking sidechains one bus from another.