> ## Documentation Index
> Fetch the complete documentation index at: https://songbird.studiocollective.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# songbird-dsp

# songbird-dsp

Shared DSP primitives used across the engine, plugins, and state layers.
This is the canonical location for all reusable audio math — plugin crates
should import from here rather than implementing DSP inline.

## Organization

The crate uses **atomic design** to organize DSP code:

| Module       | Purpose                                                             |
| ------------ | ------------------------------------------------------------------- |
| `atoms/`     | Single-purpose DSP primitives grouped by domain                     |
| `molecules/` | Composed building blocks (multi-atom processing chains)             |
| `backend/`   | `DspBackend` trait + platform implementations (`RustNativeBackend`) |
| `graph/`     | `DspNode` trait + runtime graph evaluator                           |
| `util`       | dB/gain conversions, metering helpers, ballistic smoothing          |

### Atoms (by domain)

* `atoms::filter` — Biquad (TDF-II, Audio EQ Cookbook), SVF (Zavalishin TPT).
* `atoms::osc` — Oscillators (planned: sine, polyblep, wavetable, noise).
* `atoms::envelope` — ADSR envelopes (linear + exponential curves).
* `atoms::delay` — Delay lines with fractional interpolation (none, linear, cubic Hermite).
* `atoms::dynamics` — Dynamics processors (planned: compressor, limiter, gate).
* `atoms::modulation` — Modulation sources (planned: LFO, sample & hold, slew).
* `atoms::spectral` — FFT wrapper (rustfft), STFT/iSTFT, windowing, spectrum analyzer, oversampling.
* `atoms::resample` — Linear + windowed sinc resampling (Blackman-Harris, up to 64 taps).
* `atoms::midi` — MPE tracker and voice allocator.
* `atoms::output` — Dither (TPDF with xorshift64).

## Public API

### Backward-compatible re-exports

Existing imports like `songbird_dsp::biquad::BiquadFilter` continue to work.
New code should prefer the canonical paths (e.g. `songbird_dsp::atoms::filter::biquad::BiquadFilter`).

### Conversions (via `util`)

`db_to_gain`, `gain_to_db`, `db_to_percent`, `ballistic_smooth`, and variants.

### Backend

`DspBackend` trait with `RustNativeBackend` (pulp SIMD). Operations: `biquad_cascade`,
`mix_add`, `gain`, `dot`, `copy_gain`, `sum`, `crossfade`, `clear`, `peak_abs`.

## How it fits

Foundation crate. Imported by `songbird-plugins`, `songbird-engine`,
`songbird-state`, `songbird-sync`, `songbird-headless`,
`songbird-reverb-vst3`, `songbird-separator`. Depends on `rustfft` and `pulp`.

## Roadmap

See [ROADMAP.md](ROADMAP.md) for the DSP optimization plan covering:

* Primitive extraction from plugins (OnePole, Phasor, EnvelopeFollower, etc.)
* Per-sample and block-level optimizations (FMA, scalarization, block-rate coefficients)
* SIMD strategy (pulp for runtime dispatch, Accelerate/vDSP for macOS)
* `DspNode` trait + `DspGraph` runtime for canvas and vibe-coded plugins

## Tests

`cargo test -p songbird-dsp` — runs unit tests, golden-file reference tests
(biquad + SVF validated against Python/scipy at 1e-5 tolerance), and backend tests.