Skip to main content

​
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: 
{ "eventId": "transport_play", "payload": {} }
{ "eventId": "set_track_volume", "payload": { "track": 0, "volume": 95 } }

​
Binary frames

Tag-based, little-endian encoding:
TagNameContent
0x01RT frameMeters, transport position, spectrum data (~30fps broadcast)
0x02Audio clip peaksWaveform peak data for display
0x03Bird mutation resultResult of a .bird file edit

​
Modules

FilePurpose
main.rsServer entry point, WebSocket listener, shared ServerState
command_handler.rsProcesses text-frame commands (transport, tracks, plugins, etc.)
rt_frame.rsBinary RT frame encoding and ~30fps broadcast to all clients
audio_engine.rscpal audio I/O, ring buffers for engine communication, meter polling
recording.rsAudio recording — mic input → WAV file with live peak monitoring
ffi_bridge.rsStub for C++ plugin hosting (VST3/AU via JUCE FFI — not yet implemented)
link.rsStub 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

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.