Skip to content

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.

feat(audio): per-bus DSP inserts + sidechain ducking

esenginee106208a6b9e
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f3f8fbda5..807d1ecf1 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1144 stable · 17 beta · 1 deprecated
+Symbols: 1150 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -554,6 +554,8 @@ bufferBudget: number
dispose: () => void
getBufferHandle: (url: string) => AudioBufferHandle | undefined
getBufferStats: () => AudioBufferStats
+getBusDucking: (target: string) => BusDuckRule | null
+getBusEffects: (busName: string) => BusEffectDef[]
getSpectrum: (out: Uint8Array) => boolean
invalidateBuffer: (url: string) => boolean
muteBus: (busName: string, muted: boolean) => void
@@ -566,6 +568,9 @@ releaseBuffer: (url: string) => void
retainBuffer: (url: string) => boolean
setAssetResolver: (resolver: (url: string) => ArrayBuffer | null) => void
setBufferBudget: (bytes: number | null) => void
+setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
+setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
+setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
@@ -574,6 +579,7 @@ setUIVolume: (volume: number) => void
stopAll: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
+updateDucking: () => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -595,9 +601,13 @@ id: number
```
addChild: (child: AudioBus) => void
connect: (destination: AudioBus | AudioNode) => void
+duckTo: (level: number, timeConstant: number) => void
+effects: BusEffectDef[]
+input: GainNode
muted: boolean
name: string
node: GainNode
+setEffects: (defs: BusEffectDef[]) => void
volume: number
static new (context: AudioContext, config: AudioBusConfig): AudioBus
static prototype: AudioBus
@@ -639,12 +649,16 @@ enabled: boolean
## AudioMixer — class
```
+busNames: () => string[]
createBus: (config: AudioBusConfig) => AudioBus
getBus: (name: string) => AudioBus | undefined
+getDucking: (target: string) => BusDuckRule | null
master: AudioBus
music: AudioBus
+setDucking: (target: string, rule: BusDuckRule | null) => boolean
sfx: AudioBus
ui: AudioBus
+updateDucking: () => void
voice: AudioBus
static new (context: AudioContext, config?: AudioMixerConfig): AudioMixer
static prototype: AudioMixer
@@ -1017,6 +1031,20 @@ source: string
'local' | 'lazy' | 'remote'
```
+## BusDuckRule — interface
+```
+amount: number
+attack: number | undefined
+release: number | undefined
+threshold: number | undefined
+trigger: string
+```
+
+## BusEffectDef — type
+```
+FilterEffectDef | ReverbEffectDef | CompressorEffectDef
+```
+
## Button — const
```
(...bindings: Binding[]) => ActionDef
@@ -1432,6 +1460,16 @@ spineFields: SpineFieldMeta | undefined
transient: boolean | undefined
```
+## CompressorEffectDef — interface
+```
+attack: number | undefined
+kneeDb: number | undefined
+ratio: number | undefined
+release: number | undefined
+thresholdDb: number | undefined
+type: "compressor"
+```
+
## CookedAtlasInfo — interface
```
frame: { x: number; y: number; width: number; height: number; }
@@ -2375,6 +2413,15 @@ Right = 1
Top = 3
```
+## FilterEffectDef — interface
+```
+filter: "lowpass" | "highpass" | "bandpass" | "lowshelf" | "highshelf" | "peaking" | "notch"
+frequency: number
+gainDb: number | undefined
+q: number | undefined
+type: "filter"
+```
+
## FilterExpr — type
```
| { readonly kind: 'with'; readonly component: AnyComponentDef }
@@ -4879,6 +4926,14 @@ textureEvictableCount: number
vertexBufferCount: number
```
+## ReverbEffectDef — interface
+```
+decay: number | undefined
+seconds: number | undefined
+type: "reverb"
+wet: number | undefined
+```
+
## RevoluteJoint — const
```
ComponentDef<RevoluteJointData>
@@ -8206,6 +8261,11 @@ NavPlugin
(raw: any): TimelineAsset
```
+## parseBusEffects — function
+```
+(raw: unknown): BusEffectDef[]
+```
+
## parseLocaleTable — function
```
(text: string, path: string): LocaleTableAsset
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 773bfb812..c63689d02 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1143 stable · 19 beta · 1 deprecated
+Symbols: 1149 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -549,6 +549,8 @@ bufferBudget: number
dispose: () => void
getBufferHandle: (url: string) => AudioBufferHandle | undefined
getBufferStats: () => AudioBufferStats
+getBusDucking: (target: string) => BusDuckRule | null
+getBusEffects: (busName: string) => BusEffectDef[]
getSpectrum: (out: Uint8Array) => boolean
invalidateBuffer: (url: string) => boolean
muteBus: (busName: string, muted: boolean) => void
@@ -561,6 +563,9 @@ releaseBuffer: (url: string) => void
retainBuffer: (url: string) => boolean
setAssetResolver: (resolver: (url: string) => ArrayBuffer | null) => void
setBufferBudget: (bytes: number | null) => void
+setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
+setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
+setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
@@ -569,6 +574,7 @@ setUIVolume: (volume: number) => void
stopAll: () => void
stopBGM: (fadeOut?: number) => void
trimBufferCache: () => number
+updateDucking: () => void
static new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPI
static prototype: AudioAPI
```
@@ -590,9 +596,13 @@ id: number
```
addChild: (child: AudioBus) => void
connect: (destination: AudioBus | AudioNode) => void
+duckTo: (level: number, timeConstant: number) => void
+effects: BusEffectDef[]
+input: GainNode
muted: boolean
name: string
node: GainNode
+setEffects: (defs: BusEffectDef[]) => void
volume: number
static new (context: AudioContext, config: AudioBusConfig): AudioBus
static prototype: AudioBus
@@ -634,12 +644,16 @@ enabled: boolean
## AudioMixer — class
```
+busNames: () => string[]
createBus: (config: AudioBusConfig) => AudioBus
getBus: (name: string) => AudioBus | undefined
+getDucking: (target: string) => BusDuckRule | null
master: AudioBus
music: AudioBus
+setDucking: (target: string, rule: BusDuckRule | null) => boolean
sfx: AudioBus
ui: AudioBus
+updateDucking: () => void
voice: AudioBus
static new (context: AudioContext, config?: AudioMixerConfig): AudioMixer
static prototype: AudioMixer
@@ -1012,6 +1026,20 @@ source: string
'local' | 'lazy' | 'remote'
```
+## BusDuckRule — interface
+```
+amount: number
+attack: number | undefined
+release: number | undefined
+threshold: number | undefined
+trigger: string
+```
+
+## BusEffectDef — type
+```
+FilterEffectDef | ReverbEffectDef | CompressorEffectDef
+```
+
## Button — const
```
(...bindings: Binding[]) => ActionDef
@@ -1427,6 +1455,16 @@ spineFields: SpineFieldMeta | undefined
transient: boolean | undefined
```
+## CompressorEffectDef — interface
+```
+attack: number | undefined
+kneeDb: number | undefined
+ratio: number | undefined
+release: number | undefined
+thresholdDb: number | undefined
+type: "compressor"
+```
+
## CookedAtlasInfo — interface
```
frame: { x: number; y: number; width: number; height: number; }
@@ -2370,6 +2408,15 @@ Right = 1
Top = 3
```
+## FilterEffectDef — interface
+```
+filter: "lowpass" | "highpass" | "bandpass" | "lowshelf" | "highshelf" | "peaking" | "notch"
+frequency: number
+gainDb: number | undefined
+q: number | undefined
+type: "filter"
+```
+
## FilterExpr — type
```
| { readonly kind: 'with'; readonly component: AnyComponentDef }
@@ -4874,6 +4921,14 @@ textureEvictableCount: number
vertexBufferCount: number
```
+## ReverbEffectDef — interface
+```
+decay: number | undefined
+seconds: number | undefined
+type: "reverb"
+wet: number | undefined
+```
+
## RevoluteJoint — const
```
ComponentDef<RevoluteJointData>
@@ -8211,6 +8266,11 @@ NodePlatformAdapter
(raw: any): TimelineAsset
```
+## parseBusEffects — function
+```
+(raw: unknown): BusEffectDef[]
+```
+
## parseLocaleTable — function
```
(text: string, path: string): LocaleTableAsset
diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.ts
index a5ec109d9..711ffa5fb 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -1,7 +1,8 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PlatformAudioBackend, AudioBufferHandle, AudioHandle } from './PlatformAudioBackend';
-import type { AudioMixer } from './AudioMixer';
+import type { AudioMixer, BusDuckRule } from './AudioMixer';
+import type { BusEffectDef } from './BusEffects';
import { defineResource } from '../resource';
import { RuntimeConfig } from '../defaults';
import { log } from '../logger';
@@ -375,6 +376,41 @@ export class AudioAPI {
}
}
+ setBusVolume(busName: string, volume: number): void {
+ const bus = this.mixer_?.getBus(busName);
+ if (bus) {
+ bus.volume = volume;
+ }
+ }
+
+ /** Replace a bus's DSP insert chain. No-op (false) on backends without a
+ * WebAudio graph (WeChat/Null) — same degradation as the volume APIs. */
+ setBusEffects(busName: string, effects: BusEffectDef[]): boolean {
+ const bus = this.mixer_?.getBus(busName);
+ if (!bus) return false;
+ bus.setEffects(effects);
+ return true;
+ }
+
+ getBusEffects(busName: string): BusEffectDef[] {
+ return this.mixer_?.getBus(busName)?.effects ?? [];
+ }
+
+ /** Install (or clear with null) sidechain ducking on `target` — e.g. duck
+ * 'music' to 30% while 'voice' carries signal. */
+ setBusDucking(target: string, rule: BusDuckRule | null): boolean {
+ return this.mixer_?.setDucking(target, rule) ?? false;
+ }
+
+ getBusDucking(target: string): BusDuckRule | null {
+ return this.mixer_?.getDucking(target) ?? null;
+ }
+
+ /** Advance duck envelopes (driven per-frame by AudioUpdateSystem). */
+ updateDucking(): void {
+ this.mixer_?.updateDucking();
+ }
+
getBufferHandle(url: string): AudioBufferHandle | undefined {
return this.lookupBuffer_(url);
}
diff --git a/sdk/src/audio/AudioBus.ts b/sdk/src/audio/AudioBus.ts
index f2dd63995..864905b54 100644
--- a/sdk/src/audio/AudioBus.ts
+++ b/sdk/src/audio/AudioBus.ts
@@ -1,5 +1,16 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file AudioBus.ts
+ * @brief One mixer bus: input → [effect inserts…] → duck → gain(volume) → parent.
+ *
+ * Sources and child buses connect to `input`; `node` is the OUTPUT gain (what
+ * volume/mute act on, and what parents/analysers tap). The duck stage is a
+ * separate gain so sidechain ducking never fights the user's volume setting.
+ */
+
+import { buildEffectNodes, type BusEffectDef, type EffectNodes } from './BusEffects';
+
export interface AudioBusConfig {
name: string;
volume?: number;
@@ -11,20 +22,33 @@ const SMOOTHING_TIME_CONSTANT = 0.015;
export class AudioBus {
private readonly name_: string;
+ private readonly context_: AudioContext;
+ private readonly inputNode_: GainNode;
+ private readonly duckNode_: GainNode;
private readonly gainNode_: GainNode;
private muted_: boolean = false;
private volume_: number = 1.0;
private children_: AudioBus[] = [];
+ private effectDefs_: BusEffectDef[] = [];
+ private effectNodes_: EffectNodes[] = [];
constructor(context: AudioContext, config: AudioBusConfig) {
this.name_ = config.name;
+ this.context_ = context;
+ this.inputNode_ = context.createGain();
+ this.duckNode_ = context.createGain();
this.gainNode_ = context.createGain();
+ this.inputNode_.connect(this.duckNode_);
+ this.duckNode_.connect(this.gainNode_);
this.volume_ = Math.max(0, Math.min(1, config.volume ?? 1.0));
this.muted_ = config.muted ?? false;
this.gainNode_.gain.value = this.muted_ ? 0 : this.volume_;
}
get name(): string { return this.name_; }
+ /** Entry node — sources and child buses connect HERE. */
+ get input(): GainNode { return this.inputNode_; }
+ /** Output gain (volume/mute stage) — parents and analyser taps connect FROM here. */
get node(): GainNode { return this.gainNode_; }
get volume(): number { return this.volume_; }
@@ -49,9 +73,35 @@ export class AudioBus {
);
}
+ /** The declarative insert chain currently realized on this bus. */
+ get effects(): BusEffectDef[] { return this.effectDefs_.map(e => ({ ...e })); }
+
+ /** Idempotently replace the insert chain: input → e1 → … → duck. */
+ setEffects(defs: BusEffectDef[]): void {
+ this.inputNode_.disconnect();
+ for (const fx of this.effectNodes_) fx.output.disconnect();
+ this.effectDefs_ = defs.map(e => ({ ...e }));
+ this.effectNodes_ = defs.map(d => buildEffectNodes(this.context_, d));
+ let prev: AudioNode = this.inputNode_;
+ for (const fx of this.effectNodes_) {
+ prev.connect(fx.input);
+ prev = fx.output;
+ }
+ prev.connect(this.duckNode_);
+ }
+
+ /** Sidechain duck stage: ramp toward `level` with the given time constant. */
+ duckTo(level: number, timeConstant: number): void {
+ this.duckNode_.gain.setTargetAtTime(
+ Math.max(0, Math.min(1, level)),
+ this.duckNode_.context.currentTime,
+ Math.max(0.001, timeConstant)
+ );
+ }
+
connect(destination: AudioBus | AudioNode): void {
if (destination instanceof AudioBus) {
- this.gainNode_.connect(destination.node);
+ this.gainNode_.connect(destination.input);
} else {
this.gainNode_.connect(destination);
}
diff --git a/sdk/src/audio/AudioMixer.ts b/sdk/src/audio/AudioMixer.ts
index 1d968e689..6b300d89b 100644
--- a/sdk/src/audio/AudioMixer.ts
+++ b/sdk/src/audio/AudioMixer.ts
@@ -10,6 +10,28 @@ export interface AudioMixerConfig {
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;
+}
+
const DEFAULT_MUSIC_VOLUME = 0.8;
export class AudioMixer {
@@ -51,6 +73,11 @@ export class AudioMixer {
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;
@@ -60,4 +87,57 @@ export class AudioMixer {
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) {
+ existing.analyser.disconnect();
+ 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)
+ );
+ }
+ }
}
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index bc320ae18..bbd1dedb2 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -91,6 +91,8 @@ export class AudioPlugin implements Plugin {
}
wasPlayMode = true;
+ audioAPI.updateDucking();
+
const world = app.world;
let listenerX = 0;
diff --git a/sdk/src/audio/BusEffects.ts b/sdk/src/audio/BusEffects.ts
new file mode 100644
index 000000000..0a69009c8
--- /dev/null
+++ b/sdk/src/audio/BusEffects.ts
@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file BusEffects.ts
+ * @brief Declarative per-bus DSP inserts — the serializable effect vocabulary
+ * and its WebAudio realization. Defs are pure data (the project audio
+ * config and the editor Mixer speak the same shape); non-WebAudio
+ * backends never see them (AudioAPI gates on a live mixer).
+ */
+
+export interface FilterEffectDef {
+ type: 'filter';
+ filter: 'lowpass' | 'highpass' | 'bandpass' | 'lowshelf' | 'highshelf' | 'peaking' | 'notch';
+ frequency: number;
+ /** Q factor; meaningful for all but the shelf filters. */
+ q?: number;
+ /** Boost/cut in dB; meaningful for shelf/peaking filters. */
+ gainDb?: number;
+}
+
+export interface ReverbEffectDef {
+ type: 'reverb';
+ /** Impulse length in seconds (tail size). */
+ seconds?: number;
+ /** Exponential decay rate of the impulse (higher = tighter room). */
+ decay?: number;
+ /** Wet mix 0..1 (dry is 1 - wet). */
+ wet?: number;
+}
+
+export interface CompressorEffectDef {
+ type: 'compressor';
+ thresholdDb?: number;
+ ratio?: number;
+ attack?: number;
+ release?: number;
+ kneeDb?: number;
+}
+
+export type BusEffectDef = FilterEffectDef | ReverbEffectDef | CompressorEffectDef;
+
+/** A realized effect: a sub-graph with one input and one output node. */
+export interface EffectNodes {
+ input: AudioNode;
+ output: AudioNode;
+}
+
+const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
+
+/**
+ * Procedural impulse response: stereo noise with an exponential decay tail.
+ * Good-enough room ambience with zero asset dependencies; a convolution IR
+ * asset can slot in later without changing the def shape.
+ */
+export function makeImpulseResponse(context: BaseAudioContext, seconds: number, decay: number): AudioBuffer {
+ const rate = context.sampleRate;
+ const length = Math.max(1, Math.floor(rate * Math.max(0.05, seconds)));
+ const buffer = context.createBuffer(2, length, rate);
+ for (let ch = 0; ch < 2; ch++) {
+ const data = buffer.getChannelData(ch);
+ for (let i = 0; i < length; i++) {
+ data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / length, decay);
+ }
+ }
+ return buffer;
+}
+
+function buildFilter(context: BaseAudioContext, def: FilterEffectDef): EffectNodes {
+ const node = context.createBiquadFilter();
+ node.type = def.filter;
+ node.frequency.value = Math.max(10, def.frequency);
+ if (def.q !== undefined) node.Q.value = def.q;
+ if (def.gainDb !== undefined) node.gain.value = def.gainDb;
+ return { input: node, output: node };
+}
+
+function buildReverb(context: BaseAudioContext, def: ReverbEffectDef): EffectNodes {
+ const input = context.createGain();
+ const output = context.createGain();
+ const wet = clamp01(def.wet ?? 0.35);
+
+ const dryGain = context.createGain();
+ dryGain.gain.value = 1 - wet;
+ input.connect(dryGain);
+ dryGain.connect(output);
+
+ const convolver = context.createConvolver();
+ convolver.buffer = makeImpulseResponse(context, def.seconds ?? 1.5, def.decay ?? 3.0);
+ const wetGain = context.createGain();
+ wetGain.gain.value = wet;
+ input.connect(convolver);
+ convolver.connect(wetGain);
+ wetGain.connect(output);
+
+ return { input, output };
+}
+
+function buildCompressor(context: BaseAudioContext, def: CompressorEffectDef): EffectNodes {
+ const node = context.createDynamicsCompressor();
+ if (def.thresholdDb !== undefined) node.threshold.value = def.thresholdDb;
+ if (def.ratio !== undefined) node.ratio.value = Math.max(1, def.ratio);
+ if (def.attack !== undefined) node.attack.value = Math.max(0, def.attack);
+ if (def.release !== undefined) node.release.value = Math.max(0, def.release);
+ if (def.kneeDb !== undefined) node.knee.value = Math.max(0, def.kneeDb);
+ return { input: node, output: node };
+}
+
+/** Realize one effect def as a WebAudio sub-graph. */
+export function buildEffectNodes(context: BaseAudioContext, def: BusEffectDef): EffectNodes {
+ switch (def.type) {
+ case 'filter': return buildFilter(context, def);
+ case 'reverb': return buildReverb(context, def);
+ case 'compressor': return buildCompressor(context, def);
+ }
+}
+
+/** Normalize arbitrary JSON into a valid effect list (tolerant; drops junk). */
+export function parseBusEffects(raw: unknown): BusEffectDef[] {
+ if (!Array.isArray(raw)) return [];
+ const out: BusEffectDef[] = [];
+ for (const e of raw) {
+ if (!e || typeof e !== 'object') continue;
+ const t = (e as { type?: unknown }).type;
+ if (t === 'filter') {
+ const f = e as FilterEffectDef;
+ const kinds = ['lowpass', 'highpass', 'bandpass', 'lowshelf', 'highshelf', 'peaking', 'notch'];
+ if (!kinds.includes(f.filter) || typeof f.frequency !== 'number') continue;
+ out.push({
+ type: 'filter', filter: f.filter, frequency: f.frequency,
+ ...(typeof f.q === 'number' ? { q: f.q } : {}),
+ ...(typeof f.gainDb === 'number' ? { gainDb: f.gainDb } : {}),
+ });
+ } else if (t === 'reverb') {
+ const r = e as ReverbEffectDef;
+ out.push({
+ type: 'reverb',
+ ...(typeof r.seconds === 'number' ? { seconds: r.seconds } : {}),
+ ...(typeof r.decay === 'number' ? { decay: r.decay } : {}),
+ ...(typeof r.wet === 'number' ? { wet: clamp01(r.wet) } : {}),
+ });
+ } else if (t === 'compressor') {
+ const c = e as CompressorEffectDef;
+ out.push({
+ type: 'compressor',
+ ...(typeof c.thresholdDb === 'number' ? { thresholdDb: c.thresholdDb } : {}),
+ ...(typeof c.ratio === 'number' ? { ratio: c.ratio } : {}),
+ ...(typeof c.attack === 'number' ? { attack: c.attack } : {}),
+ ...(typeof c.release === 'number' ? { release: c.release } : {}),
+ ...(typeof c.kneeDb === 'number' ? { kneeDb: c.kneeDb } : {}),
+ });
+ }
+ }
+ return out;
+}
diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.ts
index 7e461f501..cf8e1c8a1 100644
--- a/sdk/src/audio/WebAudioBackend.ts
+++ b/sdk/src/audio/WebAudioBackend.ts
@@ -272,7 +272,7 @@ export class WebAudioBackend implements PlatformAudioBackend {
const busName = config.bus ?? 'sfx';
const bus = this.mixer_.getBus(busName) ?? this.mixer_.sfx;
- poolNode.panner.connect(bus.node);
+ poolNode.panner.connect(bus.input);
const startOffset = config.startOffset ?? 0;
source.start(0, startOffset);
diff --git a/sdk/src/audio/index.ts b/sdk/src/audio/index.ts
index d37736bde..e2aae95f7 100644
--- a/sdk/src/audio/index.ts
+++ b/sdk/src/audio/index.ts
@@ -2,7 +2,12 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
export { Audio, AudioAPI } from './Audio';
export { AudioBus, type AudioBusConfig } from './AudioBus';
-export { AudioMixer, type AudioMixerConfig } from './AudioMixer';
+export { AudioMixer, type AudioMixerConfig, type BusDuckRule } from './AudioMixer';
+export {
+ buildEffectNodes, makeImpulseResponse, parseBusEffects,
+ type BusEffectDef, type FilterEffectDef, type ReverbEffectDef, type CompressorEffectDef,
+ type EffectNodes,
+} from './BusEffects';
export { AudioPool, type PooledAudioNode } from './AudioPool';
export { AudioPlugin, audioPlugin, type AudioPluginConfig } from './AudioPlugin';
export { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 50ef95047..2553e48ee 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -294,6 +294,12 @@ export {
AudioBus,
AudioMixer,
AudioPool,
+ parseBusEffects,
+ type BusEffectDef,
+ type FilterEffectDef,
+ type ReverbEffectDef,
+ type CompressorEffectDef,
+ type BusDuckRule,
AttenuationModel,
calculateAttenuation,
calculatePanning,
diff --git a/sdk/tests/audio-bus-effects.test.ts b/sdk/tests/audio-bus-effects.test.ts
new file mode 100644
index 000000000..8c92b8bca
--- /dev/null
+++ b/sdk/tests/audio-bus-effects.test.ts
@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * Bus DSP inserts + sidechain ducking: chain topology (input → effects → duck →
+ * gain), idempotent rebuild, the ducking RMS loop, and tolerant def parsing.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { AudioBus } from '../src/audio/AudioBus';
+import { AudioMixer } from '../src/audio/AudioMixer';
+import { parseBusEffects, makeImpulseResponse } from '../src/audio/BusEffects';
+
+function mockParam(v = 0): any {
+ return { value: v, setTargetAtTime: vi.fn() };
+}
+
+function createMockContext(): any {
+ const ctx: any = {
+ currentTime: 0,
+ sampleRate: 48000,
+ destination: {},
+ createGain: vi.fn(() => ({ gain: mockParam(1), connect: vi.fn(), disconnect: vi.fn(), context: ctx })),
+ createBiquadFilter: vi.fn(() => ({
+ type: '', frequency: mockParam(), Q: mockParam(1), gain: mockParam(),
+ connect: vi.fn(), disconnect: vi.fn(), context: ctx,
+ })),
+ createConvolver: vi.fn(() => ({ buffer: null, connect: vi.fn(), disconnect: vi.fn(), context: ctx })),
+ createDynamicsCompressor: vi.fn(() => ({
+ threshold: mockParam(-24), ratio: mockParam(12), attack: mockParam(0.003),
+ release: mockParam(0.25), knee: mockParam(30),
+ connect: vi.fn(), disconnect: vi.fn(), context: ctx,
+ })),
+ createAnalyser: vi.fn(() => ({
+ fftSize: 0, connect: vi.fn(), disconnect: vi.fn(),
+ getByteTimeDomainData: vi.fn(),
+ })),
+ createBuffer: vi.fn((channels: number, length: number, rate: number) => {
+ const data = Array.from({ length: channels }, () => new Float32Array(length));
+ return { length, sampleRate: rate, getChannelData: (c: number) => data[c] };
+ }),
+ };
+ return ctx;
+}
+
+describe('AudioBus effect chain', () => {
+ let ctx: any;
+ let bus: AudioBus;
+
+ beforeEach(() => {
+ ctx = createMockContext();
+ bus = new AudioBus(ctx, { name: 'music' });
+ });
+
+ it('wires input → duck → gain with no effects', () => {
+ // Constructor gains: [0]=input, [1]=duck, [2]=output.
+ const input = ctx.createGain.mock.results[0].value;
+ const duck = ctx.createGain.mock.results[1].value;
+ expect(input.connect).toHaveBeenCalledWith(duck);
+ expect(duck.connect).toHaveBeenCalledWith(bus.node);
+ });
+
+ it('splices a filter between input and duck', () => {
+ bus.setEffects([{ type: 'filter', filter: 'lowpass', frequency: 800, q: 2 }]);
+ const input = ctx.createGain.mock.results[0].value;
+ const duck = ctx.createGain.mock.results[1].value;
+ const filter = ctx.createBiquadFilter.mock.results[0].value;
+ expect(input.disconnect).toHaveBeenCalled();
+ expect(input.connect).toHaveBeenLastCalledWith(filter);
+ expect(filter.connect).toHaveBeenCalledWith(duck);
+ expect(filter.type).toBe('lowpass');
+ expect(filter.frequency.value).toBe(800);
+ expect(filter.Q.value).toBe(2);
+ });
+
+ it('rebuilds idempotently and reports stored defs', () => {
+ bus.setEffects([{ type: 'filter', filter: 'lowpass', frequency: 800 }]);
+ bus.setEffects([{ type: 'compressor', ratio: 4 }]);
+ expect(bus.effects).toEqual([{ type: 'compressor', ratio: 4 }]);
+ // The replaced filter's output must have been disconnected.
+ const filter = ctx.createBiquadFilter.mock.results[0].value;
+ expect(filter.disconnect).toHaveBeenCalled();
+ const comp = ctx.createDynamicsCompressor.mock.results[0].value;
+ expect(comp.ratio.value).toBe(4);
+ });
+
+ it('reverb builds a parallel wet/dry graph feeding one output', () => {
+ bus.setEffects([{ type: 'reverb', seconds: 0.5, wet: 0.25 }]);
+ const conv = ctx.createConvolver.mock.results[0].value;
+ expect(conv.buffer).not.toBeNull();
+ // Gains: 0-2 bus, then reverb creates input/output/dry/wet (4 more).
+ const gains = ctx.createGain.mock.results.map((r: any) => r.value);
+ const dry = gains.find((g: any) => Math.abs(g.gain.value - 0.75) < 1e-6);
+ const wet = gains.find((g: any) => Math.abs(g.gain.value - 0.25) < 1e-6);
+ expect(dry).toBeDefined();
+ expect(wet).toBeDefined();
+ });
+});
+
+describe('AudioMixer ducking', () => {
+ let ctx: any;
+ let mixer: AudioMixer;
+
+ beforeEach(() => {
+ ctx = createMockContext();
+ mixer = new AudioMixer(ctx);
+ });
+
+ const duckGainOf = (bus: any) => {
+ // Per-bus gains are created input,duck,gain — find music's duck node by
+ // walking creation order: 5 buses × 3 gains; music is the 2nd bus.
+ return ctx.createGain.mock.results[1 * 3 + 1].value;
+ };
+
+ it('installs an analyser tap on the trigger bus output', () => {
+ expect(mixer.setDucking('music', { trigger: 'voice', amount: 0.3 })).toBe(true);
+ const analyser = ctx.createAnalyser.mock.results[0].value;
+ expect(mixer.voice.node.connect).toHaveBeenCalledWith(analyser);
+ expect(mixer.getDucking('music')).toEqual({ trigger: 'voice', amount: 0.3 });
+ });
+
+ it('rejects unknown buses', () => {
+ expect(mixer.setDucking('nope', { trigger: 'voice', amount: 0.3 })).toBe(false);
+ expect(mixer.setDucking('music', { trigger: 'nope', amount: 0.3 })).toBe(false);
+ });
+
+ it('ducks on signal and releases on silence', () => {
+ mixer.setDucking('music', { trigger: 'voice', amount: 0.3, attack: 0.05, release: 0.4 });
+ const analyser = ctx.createAnalyser.mock.results[0].value;
+ const musicDuck = duckGainOf(mixer.music);
+
+ // Loud trigger: time-domain bytes far from the 128 midline.
+ analyser.getByteTimeDomainData.mockImplementation((buf: Uint8Array) => buf.fill(200));
+ mixer.updateDucking();
+ expect(musicDuck.gain.setTargetAtTime).toHaveBeenLastCalledWith(0.3, 0, 0.05);
+
+ // Silence: bytes at the midline.
+ analyser.getByteTimeDomainData.mockImplementation((buf: Uint8Array) => buf.fill(128));
+ mixer.updateDucking();
+ expect(musicDuck.gain.setTargetAtTime).toHaveBeenLastCalledWith(1, 0, 0.4);
+ });
+
+ it('clearing the rule disconnects the tap and restores the duck stage', () => {
+ mixer.setDucking('music', { trigger: 'voice', amount: 0.3 });
+ const analyser = ctx.createAnalyser.mock.results[0].value;
+ mixer.setDucking('music', null);
+ expect(analyser.disconnect).toHaveBeenCalled();
+ expect(mixer.getDucking('music')).toBeNull();
+ });
+});
+
+describe('parseBusEffects', () => {
+ it('keeps valid defs and drops junk', () => {
+ const parsed = parseBusEffects([
+ { type: 'filter', filter: 'lowpass', frequency: 500 },
+ { type: 'filter', filter: 'wave', frequency: 500 }, // bad filter kind
+ { type: 'reverb', wet: 2 }, // wet clamps
+ { type: 'unknown' },
+ null,
+ { type: 'compressor', ratio: 8 },
+ ]);
+ expect(parsed).toEqual([
+ { type: 'filter', filter: 'lowpass', frequency: 500 },
+ { type: 'reverb', wet: 1 },
+ { type: 'compressor', ratio: 8 },
+ ]);
+ });
+
+ it('returns [] for non-arrays', () => {
+ expect(parseBusEffects(undefined)).toEqual([]);
+ expect(parseBusEffects({})).toEqual([]);
+ });
+});
+
+describe('makeImpulseResponse', () => {
+ it('builds a stereo buffer with a decaying tail', () => {
+ const ctx = createMockContext();
+ const ir = makeImpulseResponse(ctx, 0.1, 3);
+ expect(ctx.createBuffer).toHaveBeenCalledWith(2, 4800, 48000);
+ const ch0 = ir.getChannelData(0);
+ // Tail decays: late samples are bounded by early envelope.
+ expect(Math.abs(ch0[ch0.length - 1])).toBeLessThanOrEqual(Math.abs(1));
+ expect(ch0.length).toBe(4800);
+ });
+});
diff --git a/sdk/tests/audio-bus.test.ts b/sdk/tests/audio-bus.test.ts
index 9556da39d..629ee6caf 100644
--- a/sdk/tests/audio-bus.test.ts
+++ b/sdk/tests/audio-bus.test.ts
@@ -101,7 +101,7 @@ describe('AudioBus', () => {
const busA = new AudioBus(context, { name: 'a' });
const busB = new AudioBus(context, { name: 'b' });
busA.connect(busB);
- expect(busA.node.connect).toHaveBeenCalledWith(busB.node);
+ expect(busA.node.connect).toHaveBeenCalledWith(busB.input);
});
it('should connect to a raw AudioNode', () => {
@@ -117,7 +117,7 @@ describe('AudioBus', () => {
const parent = new AudioBus(context, { name: 'parent' });
const child = new AudioBus(context, { name: 'child' });
parent.addChild(child);
- expect(child.node.connect).toHaveBeenCalledWith(parent.node);
+ expect(child.node.connect).toHaveBeenCalledWith(parent.input);
});
});
});
diff --git a/sdk/tests/audio-mixer.test.ts b/sdk/tests/audio-mixer.test.ts
index f0058eda4..db533fc54 100644
--- a/sdk/tests/audio-mixer.test.ts
+++ b/sdk/tests/audio-mixer.test.ts
@@ -49,10 +49,10 @@ describe('AudioMixer', () => {
it('should connect child buses to master', () => {
const mixer = new AudioMixer(context);
- expect(mixer.music.node.connect).toHaveBeenCalledWith(mixer.master.node);
- expect(mixer.sfx.node.connect).toHaveBeenCalledWith(mixer.master.node);
- expect(mixer.ui.node.connect).toHaveBeenCalledWith(mixer.master.node);
- expect(mixer.voice.node.connect).toHaveBeenCalledWith(mixer.master.node);
+ expect(mixer.music.node.connect).toHaveBeenCalledWith(mixer.master.input);
+ expect(mixer.sfx.node.connect).toHaveBeenCalledWith(mixer.master.input);
+ expect(mixer.ui.node.connect).toHaveBeenCalledWith(mixer.master.input);
+ expect(mixer.voice.node.connect).toHaveBeenCalledWith(mixer.master.input);
});
it('should apply custom volumes', () => {
@@ -101,13 +101,13 @@ describe('AudioMixer', () => {
const custom = mixer.createBus({ name: 'ambient', volume: 0.6 });
expect(custom.name).toBe('ambient');
expect(custom.volume).toBe(0.6);
- expect(custom.node.connect).toHaveBeenCalledWith(mixer.master.node);
+ expect(custom.node.connect).toHaveBeenCalledWith(mixer.master.input);
});
it('should create a custom bus connected to specified parent', () => {
const mixer = new AudioMixer(context);
const custom = mixer.createBus({ name: 'ambient', parent: 'sfx' });
- expect(custom.node.connect).toHaveBeenCalledWith(mixer.sfx.node);
+ expect(custom.node.connect).toHaveBeenCalledWith(mixer.sfx.input);
});
it('should be retrievable via getBus', () => {
diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.ts
index 50fef9e23..1d19d86b6 100644
--- a/sdk/tests/web-audio-backend.test.ts
+++ b/sdk/tests/web-audio-backend.test.ts
@@ -161,9 +161,11 @@ describe('WebAudioBackend', () => {
const analyser = mockCtx.createAnalyser.mock.results[0].value;
expect(analyser.fftSize).toBe(128);
expect(analyser.smoothingTimeConstant).toBe(0.7);
- // The master gain connects INTO the analyser (a side-branch sink).
- const master = mockCtx.createGain.mock.results[0].value;
- expect(master.connect).toHaveBeenCalledWith(analyser);
+ // The master OUTPUT gain connects INTO the analyser (a side-branch
+ // sink). A bus creates input/duck/gain in order, so master's output
+ // is the third gain the context vended.
+ const masterOut = mockCtx.createGain.mock.results[2].value;
+ expect(masterOut.connect).toHaveBeenCalledWith(analyser);
});
});