> ## 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-modular

# songbird-modular

Songbird Modular runtime — two stock plugins (instrument + fx) that each
wrap a `DspGraph` of atoms, molecules, and live-compiled DSL nodes. The
plugin's audio I/O bridges to `source` / `sink` io nodes inside the
graph; users wire any combination of `NodeDescriptor`-registered nodes
between them.

## What it owns

* The `SongbirdModular` plugin struct (implements `songbird-plugins::Plugin`).
* The `source` / `sink` io `DspNode` impls that connect plugin I/O to
  graph ports.
* The MIDI router that delivers `MidiEvent`s to the graph's `note_in`
  / `trigger_in` ports (instrument variant only).
* The audio-thread-safe topology swap (SPSC ring) for hot graph mutation.
* The template loader/saver that round-trips a graph through
  `~/.songbird/modules/<name>.json`.

## Public API

```rust theme={null}
pub fn instrument(channels: usize) -> SongbirdModular;
pub fn fx(channels: usize) -> SongbirdModular;
pub use template_loader::{load_template, save_template};
```

Internal types stay internal. Downstream crates (DSL plan, Plugin Chain
plan) consume shared infrastructure (`songbird_dsp::node_registry`,
`songbird_types::ModularTemplate`) rather than reaching into this crate.

## How it fits

`songbird-plugins` depends on this crate and registers the two stock
plugin variants (`songbirdModularInstrument`, `songbirdModularFx`) in
its `create_plugin()` factory. Everything else flows through that
registration.

This crate depends on:

* `songbird-dsp` — the `DspGraph` runtime + node registry
* `songbird-types` — the cross-crate template schema types
* `songbird-plugins` — the `Plugin` trait + `AudioBuffer` + `MidiEvent`

## Tests

`cargo test -p songbird-modular`

See also: `handoffs/archive/modular/2026-05-12-songbird-modular.md` (the plan
this crate implements).