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

# songbird-orchestrator

Shared engine orchestration. Wires `EngineController`, `StateStore`,
`PluginRegistry`, and session building into a single `EngineBackend`
implementation used by **both** the Tauri desktop app (`songbird-app`)
and the headless WebSocket server (`songbird-headless`).

Before this crate, `songbird-headless` depended on `songbird-app` to
reuse session build, device management, plugin swap, master-capture,
and plugin-editor-hosting code. That dependency is gone — both binaries
now depend on `songbird-orchestrator` instead, and the engine lifecycle
has a single canonical owner.

## What lives here

* **`RingBufferEngine`** — the `EngineBackend` implementation. Owns the
  engine controller, audio output, read pool, state store, transport,
  MIDI device manager, audio config, plugin registry, cached audio
  clips, and the `rebuilding` / `restarting` guards. Handles session
  builds, device open/close, plugin chain swaps, MIDI scheduler
  updates, and master-bus capture.
* **`TerminalProvider`** — trait for desktop-only terminal sessions
  (the headless server passes `None`).
* **`MasterCaptureState`** — global master-bus audio capture buffer used
  by the AI copilot to send audio context to Gemini.
* **`plugins/`** — plugin-editor lifecycle (`plugin_editors.rs`) and
  native editor windows (`editor_windows.rs`). Previously macOS-gated
  inside `songbird-app`; now cross-platform and shared.

## Swap modes

```rust theme={null}
pub enum SwapMode {
    Full,   // rebuild entire session (project open, sample rate change)
    Graph,  // hot-swap graph only (plugin add/remove, connection edit)
}
```

`Graph` swaps are preferred on the hot path — they skip transport and
scheduler re-init, and they don't interrupt playback.

## Dependencies

* `songbird-engine` — audio graph, transport, scheduler, ring buffer
* `songbird-state` / `songbird-sync` — project state + dispatch bridge
* `songbird-plugin-registry` — unified plugin registry
* `songbird-host-ffi` — VST3/AU hosting (feature-gated: `juce`, `vst3`)
* `songbird-plugins` — stock DSP plugins
* `songbird-session` — session-build primitives

No UI or IPC dependencies. Safe to use from headless contexts.