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

# songbird-headless

Headless WebSocket server — runs the Songbird audio engine as a pure backend service
without a GUI. Serves the same protocol as the Tauri app, so the React UI (or any
WebSocket client) can connect and control playback, mixing, and rendering remotely.

## Architecture

```
WebSocket clients (React UI, scripts, tests)
        │
        ▼  ws://host:port
┌──────────────────────────────────────────┐
│  main.rs — WebSocket listener            │
│  ├─ ServerState (Arc<Mutex<>>)           │
│  │   ├─ StateStore (project model)       │
│  │   └─ EngineSession                    │
│  ├─ command_handler.rs — text frames     │
│  ├─ rt_frame.rs — binary RT broadcast    │
│  └─ broadcast channel → all clients      │
│                                          │
│  audio_engine.rs                         │
│  ├─ cpal audio I/O                       │
│  ├─ ring buffers ↔ engine                │
│  └─ meter polling (~30fps)               │
│                                          │
│  recording.rs — mic input → WAV          │
│  ffi_bridge.rs — VST3/AU plugin stub     │
│  link.rs — Ableton Link stub             │
└──────────────────────────────────────────┘
```

## Protocol

### Text frames

JSON messages mirroring the Tauri IPC protocol:

```json theme={null}
{ "eventId": "transport_play", "payload": {} }
{ "eventId": "set_track_volume", "payload": { "track": 0, "volume": 95 } }
```

### Binary frames

Tag-based, little-endian encoding:

| Tag    | Name                 | Content                                                       |
| ------ | -------------------- | ------------------------------------------------------------- |
| `0x01` | RT frame             | Meters, transport position, spectrum data (\~30fps broadcast) |
| `0x02` | Audio clip peaks     | Waveform peak data for display                                |
| `0x03` | Bird mutation result | Result of a `.bird` file edit                                 |

## Modules

| File                 | Purpose                                                                  |
| -------------------- | ------------------------------------------------------------------------ |
| `main.rs`            | Server entry point, WebSocket listener, shared `ServerState`             |
| `command_handler.rs` | Processes text-frame commands (transport, tracks, plugins, etc.)         |
| `rt_frame.rs`        | Binary RT frame encoding and \~30fps broadcast to all clients            |
| `audio_engine.rs`    | cpal audio I/O, ring buffers for engine communication, meter polling     |
| `recording.rs`       | Audio recording — mic input → WAV file with live peak monitoring         |
| `ffi_bridge.rs`      | Stub for C++ plugin hosting (VST3/AU via JUCE FFI — not yet implemented) |
| `link.rs`            | Stub for Ableton Link integration (BPM sync, peer detection)             |

## Dependencies

* **Internal**: `songbird-engine`, `songbird-plugins`, `songbird-state`, `songbird-export`
* **Async**: `tokio` (runtime), `tokio-tungstenite` (WebSocket), `futures-util`
* **Serialization**: `serde`, `serde_json`

## Usage

```bash theme={null}
cd rust
cargo run -p songbird-headless
# Listens on ws://localhost:<port>
```

## Status

Production-ready for basic WebSocket DAW control (transport, mixing, rendering).
Plugin hosting (`ffi_bridge.rs`) and Ableton Link (`link.rs`) are infrastructure
stubs — not yet functional.