A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { AudioBus, type AudioBusConfig } from './AudioBus';
export interface AudioMixerConfig {
masterVolume?: number;
musicVolume?: number;
sfxVolume?: number;
uiVolume?: number;
voiceVolume?: number;
}
/**
* Sidechain ducking rule: while `trigger` carries signal, the target bus's
* duck stage ramps to `amount`; when it falls silent, it ramps back to 1.
*/
export interface BusDuckRule {
trigger: string;
/** Duck level 0..1 while the trigger bus is active. */
amount: number;
/** Ramp-down time constant in seconds (default 0.05). */
attack?: number;
/** Ramp-up time constant in seconds (default 0.4). */
release?: number;
/** RMS level (0..1) above which the trigger counts as active (default 0.003). */
threshold?: number;
}
interface DuckState {
rule: BusDuckRule;
analyser: AnalyserNode;
data: Uint8Array;
}
/**
* The buses every mixer starts with, their parent, and what each rests at.
*
* Declared because a second reader needs it: an editor showing a project's
* overrides has to know what an override is a change FROM, and a copy of these
* numbers there would be a second author for a runtime fact.
*/
export const BUILTIN_AUDIO_BUSES = [
{ name: 'master', parent: null, volume: 1.0 },
{ name: 'music', parent: 'master', volume: 0.8 },
{ name: 'sfx', parent: 'master', volume: 1.0 },
{ name: 'ui', parent: 'master', volume: 1.0 },
{ name: 'voice', parent: 'master', volume: 1.0 },
] as const satisfies ReadonlyArray<{ name: string; parent: string | null; volume: number }>;
/** A built-in bus's resting volume, or null when `name` is not one of them. */
export function builtinBusVolume(name: string): number | null {
return BUILTIN_AUDIO_BUSES.find((b) => b.name === name)?.volume ?? null;
}
const volumeOf = (name: string) => builtinBusVolume(name) ?? 1.0;
export class AudioMixer {
readonly master: AudioBus;
readonly music: AudioBus;
readonly sfx: AudioBus;
readonly ui: AudioBus;
readonly voice: AudioBus;
private readonly context_: AudioContext;
private readonly buses_ = new Map<string, AudioBus>();
constructor(context: AudioContext, config: AudioMixerConfig = {}) {
this.context_ = context;
this.master = new AudioBus(context, { name: 'master', volume: config.masterVolume ?? volumeOf('master') });
this.master.connect(context.destination);
this.music = new AudioBus(context, { name: 'music', volume: config.musicVolume ?? volumeOf('music') });
this.master.addChild(this.music);
this.sfx = new AudioBus(context, { name: 'sfx', volume: config.sfxVolume ?? volumeOf('sfx') });
this.master.addChild(this.sfx);
this.ui = new AudioBus(context, { name: 'ui', volume: config.uiVolume ?? volumeOf('ui') });
this.master.addChild(this.ui);
this.voice = new AudioBus(context, { name: 'voice', volume: config.voiceVolume ?? volumeOf('voice') });
this.master.addChild(this.voice);
this.buses_.set('master', this.master);
this.buses_.set('music', this.music);
this.buses_.set('sfx', this.sfx);
this.buses_.set('ui', this.ui);
this.buses_.set('voice', this.voice);
}
getBus(name: string): AudioBus | undefined {
return this.buses_.get(name);
}
/** Registered bus names, in creation order (master first). */
busNames(): string[] {
return [...this.buses_.keys()];
}
createBus(config: AudioBusConfig): AudioBus {
const bus = new AudioBus(this.context_, config);
const parent = config.parent ? this.buses_.get(config.parent) : this.master;
if (parent) {
parent.addChild(bus);
}
this.buses_.set(config.name, bus);
return bus;
}
// -- sidechain ducking ----------------------------------------------------
private ducks_ = new Map<string, DuckState>();
/** Install (or clear with null) the duck rule targeting `target`. */
setDucking(target: string, rule: BusDuckRule | null): boolean {
const targetBus = this.buses_.get(target);
if (!targetBus) return false;
const existing = this.ducks_.get(target);
if (existing) {
// The tap is trigger.node → analyser (INCOMING to the analyser), so
// disconnect it from the trigger; analyser.disconnect() drops the
// analyser's outputs (none) and leaks the tap on every re-apply.
this.buses_.get(existing.rule.trigger)?.node.disconnect(existing.analyser);
this.ducks_.delete(target);
targetBus.duckTo(1, existing.rule.release ?? 0.4);
}
if (!rule) return true;
const trigger = this.buses_.get(rule.trigger);
if (!trigger) return false;
// Sink-only tap on the trigger's OUTPUT (post-volume), so a muted
// trigger bus stops ducking.
const analyser = this.context_.createAnalyser();
analyser.fftSize = 256;
trigger.node.connect(analyser);
this.ducks_.set(target, { rule: { ...rule }, analyser, data: new Uint8Array(analyser.fftSize) });
return true;
}
getDucking(target: string): BusDuckRule | null {
const d = this.ducks_.get(target);
return d ? { ...d.rule } : null;
}
/** Per-frame: measure each trigger's RMS and ramp its target's duck stage. */
updateDucking(): void {
for (const [target, d] of this.ducks_) {
const targetBus = this.buses_.get(target);
if (!targetBus) continue;
// lib.dom narrowed getByteTimeDomainData to Uint8Array<ArrayBuffer> in
// TS 5.7; ours is a plain Uint8Array (ArrayBufferLike) — safe to cast.
d.analyser.getByteTimeDomainData(d.data as Uint8Array<ArrayBuffer>);
let sum = 0;
for (let i = 0; i < d.data.length; i++) {
const v = (d.data[i] - 128) / 128;
sum += v * v;
}
const rms = Math.sqrt(sum / d.data.length);
const active = rms > (d.rule.threshold ?? 0.003);
targetBus.duckTo(
active ? d.rule.amount : 1,
active ? (d.rule.attack ?? 0.05) : (d.rule.release ?? 0.4)
);
}
}
}