Data-driven audio middleware & runtime observability platform for the web. Zero-GC audio engine, deterministic voice culling, and live visual inspection for web games.
Modern 60-FPS web games and WebGL experiences fail when browser Garbage Collection (GC) pauses audio or causes frame stuttering. Standard web audio libraries treat sound as isolated triggers; SceneGrid brings AAA-grade audio middleware (FMOD/Wwise architecture) to the browser.
| Feature | Standard Web Audio / Howler | SceneGrid |
|---|---|---|
| Memory Allocation | Frequent GC spikes during heavy playback | Zero-allocation object pools (O(1) free-list & swap-and-pop) |
| Voice Management | Uncontrolled polyphony / overlapping | Deterministic voice culling & virtualization (with hysteresis) |
| Mixing States | Manual volume math in game logic | Total Recall VCA Snapshots & multi-layer crossfades |
| Observability | Console logs / blind debugging | Real-time DevTools inspector, cause chains & signal graph |
| Dynamic Audio (RTPC) | Raw frame-by-frame setters | FPS-independent modulation curves & slew-rate inertia |
| Interactive Music | Manual track switching / drift | Autonomous FSM Music Conductor & beat-quantized smart loops |
| Config & Routing | Imperative code / silent runtime failures | AOT Static Graph Validation (cycle detection & RAM quotas) |
βΉοΈ Building a simple promo site or lightweight puzzle? You probably don't need SceneGrid β check out zvuk or soundhub. If you're building a high-load game engine with complex routing β SceneGrid is for you.
npm install @scene-grid/engine
npm install @scene-grid/debugger --save-devimport { AudioEngine, WorkletLoader } from '@scene-grid/engine';
import * as config from './audio-config/index.js';
// 1. Initialize engine with your data-driven manifests & voice limits
const audio = new AudioEngine({
...config,
globalVoiceLimit: 32 // Hard limit to eliminate GC spikes
});
await audio.init({ isStrictValidation: true });
// 2. Play sound on user interaction (unlocked browser context)
window.addEventListener('pointerup', async () => {
await audio.unlock();
audio.play('backgroundMain', { isLoop: true });
// 3. Attach live visual inspector in development
if (process.env.NODE_ENV !== 'production') {
const { attachDebugUI, initAudioDebugPanel } = await import('@scene-grid/debugger');
await attachDebugUI(audio, { wrapperSelector: '#wrapper', workletLoader: WorkletLoader });
initAudioDebugPanel(audio);
}
}, { once: true });π For full TypeScript manifest generation, sound maps, banks, and HMR setup, see examples/main.ts.
- Zero-Allocation Pools (DOD): Eliminates frame stutter by pooling voices and telemetry into static flat arrays with
O(1)swap-and-pop cleanup. - Deterministic Voice Culling: Transparently virtualizes low-priority sounds with anti-flutter hysteresis when the audio budget is exceeded.
- AOT Static Graph Validation: Catches routing cycles, ghost ducking conflicts, and RAM quota violations at startup before allocating Web Audio nodes.
- Total Recall VCA Snapshots: Superimposes multi-layer mix states (e.g., Exploration β Combat) with sample-accurate crossfades.
- Lookahead Sidechain Ducking: Predictive attenuation via
AudioWorkletto dip background buses before transient peaks hit. - Interactive Music & Smart Loops: Autonomous FSM conductor, overlap-preserving loops (
preEntry/tail), phase-aware jumps, and beat-quantized stingers. - Event Macros & Logical Containers: Semantic
postEvent()triggers,Switch/Scatterercontainers, and deterministic variations viaSeededPRNG. - Memory Hygiene & LRU Quotas: Logical asset banks, concurrency-throttled decoding, and automatic LRU buffer eviction to prevent OOM crashes.
- Decoupled Hexagonal Architecture: Domain logic is strictly separated from Web Audio nodes, with live HMR config reloading and full IDE autocomplete.
Detailed architectural decisions and design docs are available separately:
- ποΈ Architecture Guide (C4 & Topology) β English | Π ΡΡΡΠΊΠ°Ρ Π²Π΅ΡΡΠΈΡ
- ποΈ Audio Signal Flow Diagram
- πΊοΈ Development Roadmap & Milestones
If SceneGrid helps your project, consider supporting its development:
- π° GitHub Sponsors β Recurring support
- β Buy Me a Coffee β One-time tip
- π Patreon β Join the community
MIT Β© Igor Zabrodin. Free for commercial games, apps, and interactive sites.