@zakkster/lite-audio-pool

🎧 What is lite-audio-pool?

@zakkster/lite-audio-pool is a zero-allocation, pre-wired, high-performance Web Audio sound system designed for real-time games.

It gives you:

• 🔊 32+ concurrent voices
• ⚡ O(1) channel reuse
• 🔄 Voice stealing with 20ms anti-pop fade
• 🎚️ Volume, pan, and pitch per sound
• 🧩 Sprite-based audio (single buffer, many sounds)
• 🧼 Zero garbage collection during gameplay
• 🪶 < 1 KB minified

It's the opposite of a big audio framework — it's a tiny, raw, predictable tool that gives you full control without overhead.

Part of the @zakkster/lite-* ecosystem — micro-libraries built for deterministic, cache-friendly game development.

🚀 Install

npm i @zakkster/lite-audio-pool

🕹️ Quick Start

import { AudioPool } from '@zakkster/lite-audio-pool';

// Your Web Audio context
const ctx = new AudioContext();

// Your sprite atlas (one AudioBuffer, many slices)
const spriteMap = {
  laser:   { start: 0.00, duration: 0.15 },
  hit:     { start: 0.20, duration: 0.10 },
  explode: { start: 0.35, duration: 0.40 }
};

// Create a pool with 32 channels
const pool = new AudioPool(ctx, audioBuffer, spriteMap, 32);

// Play a sound (returns channel ID)
const ch = pool.play('laser', 1.0, 0.0, 1.0);
//                     id    vol   pan  pitch

// Stop a specific channel (20ms anti-pop fade)
pool.stop(ch);

// Stop everything (scene transitions)
pool.stopAll();

🧠 Why This Exists

Most JS audio libraries:

• allocate new nodes per sound
• create garbage on every play
• cause audio pops when stealing voices
• hide Web Audio behind abstractions
• weigh 10–40 KB

lite-audio-pool does the opposite:

• pre-allocates everything at construction
• reuses channels in O(1)
• applies a 20ms gain ramp to prevent pops
• exposes raw Web Audio behavior
• weighs under 1 KB

It's built for games, not apps.

📊 Comparison

| Library | Size | Allocations | Voice Stealing | Pitch | Pan | Use Case | |---------|------|-------------|----------------|-------|-----|----------| | howler.js | ~35 KB | High | No | Yes | Yes | General audio | | pizzicato | ~12 KB | Medium | No | Yes | Yes | Effects chains | | lite-audio-pool | < 1 KB | Zero | Yes (anti-pop) | Yes | Yes | Games, SFX, sprites |

⚙️ API

new AudioPool(ctx, audioBuffer, spriteMap, capacity?)

Creates a pool of pre-wired audio channels.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | ctx | AudioContext | — | Your Web Audio context | | audioBuffer | AudioBuffer | — | The decoded sprite file | | spriteMap | Record<string, { start, duration }> | — | Named slices into the buffer | | capacity | number | 32 | Max concurrent voices (clamped to 256) |

play(spriteId, volume?, pan?, pitch?)

Plays a sound sprite immediately. Returns the channel index used, or -1 if the sprite ID is invalid.

| Parameter | Type | Default | Range | Description | |-----------|------|---------|-------|-------------| | spriteId | string | — | — | Key from your sprite map | | volume | number | 1.0 | 0–∞ | Gain multiplier | | pan | number | 0.0 | -1 to 1 | Stereo position (clamped) | | pitch | number | 1.0 | 0–∞ | Playback rate (2 = octave up) |

If all channels are busy, the oldest channel is stolen with a 20ms anti-pop fade-out before the new sound starts.

stop(channelId)

Stops a specific channel with a 20ms fade. Safe to call with invalid IDs.

stopAll()

Stops all active channels. Useful for scene transitions or pause screens.

Sprite Map Format

{
  laser:   { start: 0.00, duration: 0.15 },
  hit:     { start: 0.20, duration: 0.10 },
  explode: { start: 0.35, duration: 0.40 }
}

Each entry defines a time slice within the single AudioBuffer. The start is in seconds from the beginning of the buffer, duration is the length in seconds.

🧪 Benchmark

32 concurrent voices, rapid fire:

howler.js:
  - Allocates new AudioBufferSourceNode per play
  - GC spikes at 60–120ms intervals

lite-audio-pool:
  - Reuses pre-wired nodes
  - Zero allocations during gameplay
  - No GC spikes
  - Smooth 60–240 FPS gameplay

🔧 Internal Architecture

                ┌─────────────────────────────────┐
                │         AudioPool               │
                │                                 │
  play('laser') │  ┌─ Channel 0 ──────────────┐  │
  ─────────────►│  │ StereoPanner → GainNode ──┤──┼──► ctx.destination
                │  │ BufferSource ─►           │  │
                │  └───────────────────────────┘  │
                │  ┌─ Channel 1 ──────────────┐  │
                │  │ StereoPanner → GainNode ──┤──┤
                │  │ BufferSource ─►           │  │
                │  └───────────────────────────┘  │
                │  ...                            │
                │  ┌─ Channel N ──────────────┐  │
                │  │ StereoPanner → GainNode ──┤──┤
                │  │ BufferSource ─►           │  │
                │  └───────────────────────────┘  │
                │                                 │
                │  expireTimes: Float32Array(N)    │
                │  sources:     Array(N)          │
                └─────────────────────────────────┘

GainNode and StereoPanner are pre-wired at construction.
Only BufferSource is created per play (required by Web Audio spec).
Voice stealing: oldest channel → 20ms gain ramp to 0.0001 → stop → new source.

📦 TypeScript

Full TypeScript declarations included in AudioPool.d.ts.

📚 LLM-Friendly Documentation

See llms.txt for AI-optimized metadata and usage examples.

License

MIT