forge-audio 0.1.0

# forge-audio

**Zero-allocation, lock-free audio architecture for Rust.**

Built to eliminate main-thread blocking, GC thrashing, and AudioWorklet starvation in browser DAWs, WASM game engines, and real-time audio applications.

## The Problem

Every browser DAW and WebAudio game engine hits the same wall:

- **JavaScript GC pauses** cause audio dropouts in AudioWorklet processors
- **SharedArrayBuffer contention** between the main thread and audio thread causes unpredictable latency spikes
- **WebAudio graph rebuilds** on the main thread block rendering while the audio thread starves
- **No rollback** — networked game audio has no deterministic replay mechanism

Standard solutions (Web Audio API, FMOD, Wwise) were not designed for zero-allocation real-time constraints.

## The Architecture

forge-audio solves this with a pure Rust, `#![no_alloc]` hot-path architecture:

| Component | What it does |
|-----------|-------------|
| **Lock-free mixer** | Crossbeam zero-contention design. No mutex, no spinlock, no allocation on the audio thread. |
| **120-frame rollback buffer** | 18-byte packed `WavDiff` records in a 1.1MB pre-allocated ring buffer. Bidirectional replay with Blake3 checksums for bitwise determinism verification across networked clients. |
| **Double-buffer viz staging** | CPU writes buffer A while GPU reads buffer B. The flip IS the synchronization — no mutex needed. |
| **Integer-deterministic audio** | All simulation-coupled audio uses integer arithmetic. Floating point is confined to the final DAC output stage. |
| **Phase-aligned beat sync** | Sub-sample accurate beat grid alignment for tempo-locked mixing. |
| **Brick-wall limiter** | Zero-allocation, lookahead limiter that never clips, never allocates. |

### Performance

- **~269KB** stack-allocated footprint (entire mixer state)
- **0 heap allocations** after initialization on the 120Hz hot path
- **2.5ms** audio callback deadline met consistently (measured on commodity hardware)
- **PDC = Rollback Equivalence** — Plugin Delay Compensation and network rollback use the same diff/replay mechanism

## Quick Start

```rust
use forge_audio::engine::AudioEngine;
use forge_audio::graph::{AudioGraph, NodeKind};

// Build an audio graph
let mut graph = AudioGraph::new();
let input = graph.add_node(NodeKind::Input);
let limiter = graph.add_node(NodeKind::Effect);
let output = graph.add_node(NodeKind::Output);
graph.connect(input, limiter)?;
graph.connect(limiter, output)?;

// The engine runs the graph on the audio thread
// with zero allocations after this point
let engine = AudioEngine::new(graph, 48000)?;
```

## The Rollback Buffer

The `diff_pool` module implements a novel approach to deterministic audio state:

```rust
use forge_audio::diff_pool::{DiffPool, RollbackBuffer, WavDiff, FrameSnapshot};

// Pre-allocated at boot — never grows
let mut pool = DiffPool::new();      // 1.1MB ring buffer
let mut rollback = RollbackBuffer::new(); // 120 frames

// Record a mutation
let idx = pool.push(WavDiff {
    channel: 0, frame_offset: 0, param_id: 0,
    index: 42,
    old_val: 0,  // enables O(1) rollback
    new_val: 7,
});

// Rewind and replay are symmetric
diff_pool::rewind(&pool, &rollback, start_tick, end_tick, |coords, idx, val| {
    // apply old_val to restore previous state
});
diff_pool::replay(&pool, &rollback, start_tick, end_tick, |coords, idx, val| {
    // apply new_val to fast-forward
});
```

Every frame's diffs are checksummed with Blake3. Two clients that process the same inputs will produce byte-identical checksums — guaranteed by integer-only arithmetic.

## License

**Dual-licensed.**

- **AGPLv3** — Free for open-source and non-commercial projects. If you use forge-audio in a network service (cloud DAW, browser game, SaaS), you must open-source your entire backend under AGPLv3.

- **Commercial B2B License** — For integration into proprietary, closed-source, or commercial SaaS/cloud platforms. Includes the full DSP effect library (18 procedural effects), advanced DSP bridge, and priority support.

**Contact:** dev@deveraux.dev