# euterpe-instrument

Euterpe's `dsp-core` polyphonic synth, packaged as a **CLAP + VST3 instrument plugin**
so the same engine that powers the in-browser DAW can run inside any plugin host
(Ableton, Bitwig, Reaper, FL, Logic via a wrapper, …).

## Why this exists

A whole DAW doesn't load as a VST — the *instrument/effects engine* is the right unit.
This crate exposes Euterpe's poly synth (oscillators, filter, dual envelopes, LFO,
glide) as a standard plugin, reusing the tested `dsp-core` kernel rather than
reimplementing DSP.

## Structure

| Module | Role | Verified |
| --- | --- | --- |
| `params` | Pure normalized-`[0,1]` ↔ engine-unit mapping (log cutoff/time, ADSR, detune, gain). The single source of truth for ranges + display. | ✅ 8 cargo tests (known-value curves) |
| `engine` | `EuterpeInstrument`: apply a `ParamSnapshot`, feed MIDI `NoteEvent`s, render blocks. Drives the real `PolySynth`. | ✅ 5 cargo tests (silence→note→release, determinism, gain, poly) |
| `plugin` (feature `plugin`) | The `nih-plug` host binding — declares params, handles sample-accurate MIDI, exports CLAP + VST3 entry points. | API-verified against fetched nih-plug source; compile is the packaging step |

The `plugin` module sits behind a Cargo feature, so the default `cargo test` /
`cargo build` compiles only `dsp-core` + this crate (no plugin framework). `nih-plug`
is git-only (not on crates.io), so it's an optional git dependency.

## Build

```bash
# Engine + params (light, what CI/dev runs):
cargo test                                  # 13 tests, no plugin framework

# The actual CLAP/VST3 plugin (needs the audio toolchain; compiles nih-plug + clap-sys
# + vst3-sys). Produces a cdylib that nih-plug bundles into .clap / .vst3:
cargo build --release --features plugin
# then bundle with nih-plug's xtask (see https://github.com/robbert-vdh/nih-plug):
#   cargo xtask bundle euterpe-instrument --release --features plugin
```

## Parameters

Waveform (Sine/Saw/Square/Triangle/Noise), Filter type (LP/HP/BP/Notch/Peak/shelves/AP),
Cutoff, Resonance, Filter-env amount, Amp ADSR, Filter ADSR, Detune, Osc2 semitones,
LFO rate/depth, Glide, Output — all automatable, each with an engineering-unit readout
derived from `params` (e.g. Cutoff shows Hz, envelopes show ms).

## Verification status

Verified here without the heavyweight compile:

- `cargo test` — **13 tests pass** (param curves hit exact known values; the engine is
  silent until a note, audible while held, decays on release, deterministic, gain-scaled,
  and polyphonic — all against the real `dsp-core` `PolySynth`).
- `cargo tree --features plugin` resolves the full graph: `nih_plug` (git `f36931f7`),
  `clap-sys`, `vst3-sys`, `nih_plug_derive` — and `nih_plug` is absent from the default
  build tree (feature gating confirmed).
- `src/plugin.rs` is written against the **fetched** nih-plug source: every symbol used
  (`Plugin`/`ClapPlugin`/`Vst3Plugin` items, `FloatParam`/`IntParam`/`IntRange`,
  `NoteEvent::{NoteOn,NoteOff,Choke}`, `timing()`, `AudioIOLayout::const_default`,
  `nih_export_clap!`/`nih_export_vst3!`) was confirmed against that source.

**Full compile — verified on-box (2026-06-06):** `cargo build --features plugin -j2`
finished in ~25 s and produced `target/debug/libeuterpe_instrument.dylib`, compiling
nih-plug + `clap-sys` + `vst3-sys` and linking the `nih_export_clap!`/`nih_export_vst3!`
entry points. So `src/plugin.rs` is not merely API-correct against the fetched source —
it genuinely compiles and links into a CLAP/VST3 cdylib. (`-j2` kept peak memory safe on
the 16 GB laptop.) Bundling into `.clap`/`.vst3` is the only remaining packaging step.
