# Soundgen

8-bit sound synthesizer in Rust for game audio assets, with LLM integration via MCP.

## Status

Phases 1-4 complete. `PLAN.md` is the authoritative design doc.

## Architecture (from PLAN.md)

Cargo **workspace** with these crate boundaries:

- `soundgen-core` — synthesis engine (generators, effects, mixer). No I/O. Renders to `Vec<f32>`.
- `soundgen-fmt` — `SoundSpec` JSON schema (serde) + `PresetRegistry` loading from `presets/`.
- `soundgen-io` — WAV writer (`hound`) and playback (subprocess fallback: `paplay`/`aplay`).
- `soundgen-seq` — sequencer: patterns, songs.
- `soundgen-cli` — `gen`, `render`, `render-song`, `list-presets` commands (`clap`).
- `soundgen-mcp` — MCP server exposing `list_presets`, `generate_sfx`, `render_sound` tools (JSON-RPC over stdio, no rmcp dependency).
- `soundgen-gui` — egui editor with virtual keyboard, preset browser, SFX editor, sequencer, undo/redo, file dialogs.
- `soundgen-runtime` — NES-authentic nonlinear DAC + `SoundBank` for game embedding.

Presets are **JSON data files** in `presets/{sfx,ui,ambient}/`, not compiled code.

## Conventions

- **JSON-first**: every sound is a `SoundSpec` JSON object. LLMs generate JSON; CLI/MCP render to WAV.
- **No allocations in audio hot path**: generators use `&mut self`, `tick() -> f32`, no `Vec` per-sample.
- **Presets as data**: extend `presets/` with new `.json` files, no recompilation needed.
- **MIT license**.

## Commands

```bash
cargo test --workspace           # run all tests (90 passing)
cargo run --bin soundgen -- list-presets
cargo run --bin soundgen -- gen <preset> --out <path>
cargo run --bin soundgen -- render <spec.json> --out <path>
cargo run --bin soundgen -- render-song <song.json> --out <path>
cargo run -p soundgen-mcp -- --presets-dir presets   # MCP server on stdio
cargo run -p soundgen-gui                            # GUI editor
```

## Roadmap

Phase 1 (MVP): core generators (pulse/triangle/noise) + envelope/sweep/mixer + WAV I/O + CLI + SFX/UI presets.
Phase 2: DPCM/wavetable/FM + sequencer + MCP server + ambient presets.
Phase 3: egui GUI + realtime playback.
Phase 4: NES-authentic DAC, runtime library, sound bank.

See `PLAN.md` for full details, dependency versions, and the `SoundSpec` JSON format.