analogue_synth/crates/synth-core/README.md

# synth-core

A `no_std` DSP library providing analogue-modelling synthesizer building blocks. Designed to compile for any target — embedded bare-metal (Cortex-M), WebAssembly, and native — with no heap allocation.

## Overview

`synth-core` is the shared engine that powers both the RP2350 firmware (`synth-embedded`) and the browser visualiser (`synth-visualiser`). All modules operate on fixed-size blocks of `f32` samples using const-generic arrays, so every allocation happens on the stack at compile time.

```
VCO → Filter → VCA ← ADSR
 ↑              ↑
LFO            LFO
```

## Modules

### `oscillator` — Voltage-Controlled Oscillator

Phase-accumulator oscillator with five waveforms.

```rust
use synth_core::{config::SR_48000, oscillator::{Vco, Waveform}, AudioProcessor};

let mut vco = Vco::new(SR_48000, 440.0, Waveform::Saw);
vco.waveform = Waveform::Square;
vco.freq_hz  = 880.0;

let mut buf = [0.0f32; 256];
vco.process(&mut buf);  // fills buf with one block of audio
```

**Waveforms:** `Sine`, `Saw`, `Square`, `Triangle`, `Pulse(f32)` (duty cycle 0–1).

### `filter` — State-Variable Filter

Two-integrator SVF with selectable mode and voltage-controlled cutoff.

```rust
use synth_core::{config::SR_48000, filter::{FilterMode, Svf}, AudioProcessor};

let mut filt = Svf::new(SR_48000, 2_000.0, 0.5, FilterMode::LowPass);
filt.cutoff_hz = 1_000.0;
filt.resonance = 0.8;   // 0.0 = flat, 1.0 = self-oscillation

filt.process(&mut buf); // in-place
```

**Modes:** `LowPass`, `HighPass`, `BandPass`, `Notch`.

### `envelope` — ADSR Envelope Generator

Classic Attack / Decay / Sustain / Release envelope.

```rust
use synth_core::{config::SR_48000, envelope::Adsr, AudioProcessor};

let mut adsr = Adsr::new(SR_48000);
adsr.attack_s  = 0.01;
adsr.decay_s   = 0.2;
adsr.sustain   = 0.7;   // 0.0–1.0
adsr.release_s = 0.5;

adsr.gate_on();          // key press
let mut env = [0.0f32; 256];
adsr.process(&mut env);  // outputs 0.0–1.0 amplitude envelope

adsr.gate_off();         // key release
```

### `vca` — Voltage-Controlled Amplifier

Multiplies audio by a gain value, optionally driven by an envelope.

```rust
use synth_core::{config::SR_48000, vca::Vca};

let mut vca = Vca::new(0.8);        // fixed gain
vca.apply_envelope(&mut audio, &env); // per-sample multiply by envelope
```

### `lfo` — Low-Frequency Oscillator

Same waveform engine as the VCO, tuned to sub-audio rates.

```rust
use synth_core::{config::SR_48000, lfo::Lfo, oscillator::Waveform, AudioProcessor};

let mut lfo = Lfo::new(SR_48000);
lfo.rate_hz  = 5.0;
lfo.depth    = 0.5;
lfo.waveform = Waveform::Sine;

let mut cv = [0.0f32; 256];
lfo.process(&mut cv);   // outputs ±depth CV
```

### `midi` — MIDI Byte-Stream Parser

Parses a raw MIDI byte stream (running status supported) into typed events.

```rust
use synth_core::midi::{MidiParser, MidiEvent};

let mut parser = MidiParser::new();

// Feed bytes from UART / USB
if let Some(event) = parser.push_byte(byte) {
    match event {
        MidiEvent::NoteOn  { channel, note, velocity } => { /* ... */ }
        MidiEvent::NoteOff { channel, note, velocity } => { /* ... */ }
        MidiEvent::ControlChange { channel, controller, value } => { /* ... */ }
        MidiEvent::PitchBend    { channel, value }              => { /* ... */ }
        MidiEvent::ProgramChange { channel, program }           => { /* ... */ }
        _ => {}
    }
}
```

### `patch` — Signal Routing / Patch Bay

Fixed-capacity cable graph connecting named outputs to inputs, no heap required.

```rust
use synth_core::patch::Patch;

let mut patch: Patch<16> = Patch::new(); // up to 16 cables
patch.connect("vco.out", "filter.in");
patch.connect("lfo.out", "filter.cv");

for cable in patch.cables() {
    println!("{} → {}", cable.src, cable.dst);
}
```

### `math` — Utility Functions

```rust
use synth_core::math::{midi_note_to_hz, db_to_linear, linear_to_db, lerp};

let freq = midi_note_to_hz(69); // 440.0 Hz  (A4)
let gain = db_to_linear(-6.0);  // ≈ 0.501
```

### `config` — Sample Rate

```rust
use synth_core::config::{SampleRate, SR_44100, SR_48000};

let period = SR_48000.period(); // 1.0 / 48000.0
```

## Traits

### `AudioProcessor<const BLOCK: usize>`

Implemented by every DSP module.

| Method | Description |
|--------|-------------|
| `process(&mut self, out: &mut [f32; BLOCK])` | Fill `out` with one block of samples |
| `reset(&mut self)` | Reset all internal state (phase, integrators, …) |

### `CVProcessor<const BLOCK: usize>`

Extends `AudioProcessor` for modules that accept a control-voltage input.

| Method | Description |
|--------|-------------|
| `set_cv(&mut self, cv: f32)` | Apply modulation (1 V/octave convention for pitch) |

## Complete Voice Example

```rust
use synth_core::{
    config::SR_48000,
    oscillator::{Vco, Waveform},
    filter::{FilterMode, Svf},
    envelope::Adsr,
    vca::Vca,
    AudioProcessor,
};

const BLOCK: usize = 256;

let sr = SR_48000;
let mut vco  = Vco::new(sr, 440.0, Waveform::Saw);
let mut filt = Svf::new(sr, 2_000.0, 0.4, FilterMode::LowPass);
let mut adsr = Adsr::new(sr);
let mut vca  = Vca::new(1.0);

adsr.gate_on();

let mut audio = [0.0f32; BLOCK];
let mut env   = [0.0f32; BLOCK];

loop {
    vco.process(&mut audio);
    adsr.process(&mut env);
    filt.process(&mut audio);
    vca.apply_envelope(&mut audio, &env);
    // send `audio` to output device
}
```

## Dependencies

| Crate | Purpose |
|-------|---------|
| `libm` | `no_std`-compatible transcendental math (`sin`, `pow`, …) |
| `micromath` | Fast numerical approximations |
| `num-traits` | Numeric trait abstractions |
| `heapless` | Fixed-size `Vec`/`ArrayVec` without allocation |
| `midi-types` | MIDI type definitions |
| `serde` | Optional serialization support |

## Building

```bash
# Native (for tests)
cargo test -p synth-core

# WebAssembly
cargo build -p synth-core --target wasm32-unknown-unknown

# Embedded (Cortex-M33, RP2350)
cargo build -p synth-core --target thumbv8m.main-none-eabihf
```