​

Sync Engine

For humans and LLMs contributing to Songbird.

​

Overview

​

UI Client Modes

​

Tauri WebView (Desktop)

• Transport: Tauri IPC (window.__SONGBIRD__.invoke())
• Real-time data: Tauri events at ~30Hz (metering, transport position)
• Use case: Day-to-day music production

​

WebSocket Headless (Server / VM)

• Transport: WebSocket text frames (JSON commands) + binary frames (RT data)
• Binary frame tags: 0x01 RT frame, 0x02 audio clip peaks, 0x03 bird mutation
• Protocol: Same command/event schema as Tauri IPC — the React UI is backend-agnostic
• Use case: Running on cloud VMs, remote collaboration servers, CI/CD render farms, headless recording rigs

WebSocket clients (React UI, scripts, tests)
        │
        ▼  ws://host:port
┌──────────────────────────────────────────┐
│  songbird-headless                       │
│  ├─ 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)               │
└──────────────────────────────────────────┘

​

CLI (Scripted Operations)

• Transport: Direct Rust function calls (no IPC overhead)
• Use case: ./songbird-cli render project.bird -o output.wav, CI pipelines, automated stem exports

​

Sync Engine Architecture

​

SyncEngineCore — songbird-sync/src/engine_core.rs

​

Channels — songbird-sync/src/channels/

​

Naming Conventions

​

Per-Channel Reference

​

mixer — Track Audio Parameters

​

transport — Playback & Timing

​

recording — Track Management & Recording (+ sub-domains: clip, take_lane)

Renamed from track. The standalone clip, take_lane, and recording namespaces now route through this channel. The legacy track:* event names have moved under recording:*.

​

project — Project Settings & Sections (+ sub-domain: section)

​

clip — Clip Content (replaces the old bird channel)

​

ml — ML / AI Generation (replaces the old ai channel)

​

plugin — Plugin State

​

chat — AI Chat State

​

settings — App Settings

​

notifications — Ephemeral Engine Notifications (fire-and-forget)

​

meters — Real-Time Audio Metering

​

GuardFlags — songbird-sync/src/guards.rs

​

UpdateSource

​

Transport Layer

​

Transport Trait

pub trait Transport: Send + Sync {
    fn id(&self) -> &str;
    fn send_event(&self, channel: &str, payload: &serde_json::Value);
    fn on_receive(&self, channel: &str, handler: ...) -> SubscriptionId;
    fn unsubscribe(&self, id: SubscriptionId);
}

// Extended for binary frames (RT data, waveform peaks)
pub trait BinaryTransport: Transport {
    fn send_binary(&self, channel: &str, buffer: &[u8]);
    fn on_receive_binary(&self, channel: &str, handler: ...) -> SubscriptionId;
}

​

Transport Implementations

​

Binary Frame Protocol

​

Files on Disk

​

Bridge Layer — songbird-state/src/bridge_layer.rs

​

BridgeMode

​

PersistGate

1. Hydration gate — During initial load, don’t persist back (data just came from backend)
2. Slider drag gate — During mixer slider drags, suppress mixer persist (audio feedback via RT bypass)
3. Streaming gate — During AI chat streaming, suppress chat persist (flush at end)

​

SliderDragGuard

• begin_drag() → increments counter
• end_drag() → decrements counter, returns true when all drags ended
• is_dragging() → true while any slider is active

​

Zustand Stores (React)

​

Persist Flow

React setState → Zustand persist middleware → Bridge Layer
  → PersistGate check → Sync Engine → guard check → echo check → subscribers → persist

​

Hydration Flow (Load)

Rust loads state files from disk
  → Zustand persist getItem → IPC → Rust returns cached JSON
  → Store hydrates synchronously
  → onRehydrateStorage callback → counter++ → all stores done → reactReady()

​

Real-Time Events (Engine → React)

1. Batched Rust to JS: Real-time telemetry is grouped into a single payload and emitted at ~30Hz.
2. Direct-DOM Buffer (rtBuffer): Data is written directly to a shared mutable object (getRtBuffer()). This avoids React re-renders completely.
3. Ballistic Smoothing: A single requestAnimationFrame loop handles smoothing (e.g. meter decay) and notifies direct subscribers (canvas, plain DOM nodes).
4. Zustand Throttling: The full Zustand store (useMeterStore) is only updated every N frames (~20Hz) for React components that need reactive bindings.
5. DirectEngineTransport: Slider drags use a real-time bypass path that skips guards and persistence, writing directly to the engine.

​

Smoothing Constants

​

Loading Sequence

1. App launches (Tauri or headless WebSocket server)
2. uiReady() from React → start background loading
3. Scan for plugins (stock + VST3/AU via FFI)
4. Load .bird file
   - bird_tokenizer → bird_parser → bird_populator → EngineSession
   - Load plugins, build mixer state
   - Apply mixer state to engine
5. Push track state to React via events
6. Save state cache → defer commit until plugins settle
7. [Meanwhile] React hydrates stores → reactReady() → sets store_hydrated
8. Plugins settle
9. Commit "Project loaded" → commits now enabled

​

GuardFlags During Load

​

Undo/Redo System — songbird-state/src/undo_redo.rs

​

Branch Structure

• refs/heads/main — current position (HEAD), moves on undo/redo
• refs/redo-tip — created on first undo, points to the “newest” undone commit

​

Operations

1. Check for uncommitted changes — skip if working tree is clean
2. Delete refs/redo-tip (new change invalidates redo)
3. Create commit on main
4. Emit clip:history_changed to React

1. Block if HEAD message contains “Project loaded” or “Initial project state”
2. If no refs/redo-tip, create it pointing to current HEAD
3. Get HEAD’s parent commit
4. Diff HEAD vs parent → get changed files
5. Restore working directory from parent
6. Move refs/heads/main to parent

1. Look up refs/redo-tip — if absent, nothing to redo
2. Walk backward from redo-tip to find the child of current HEAD
3. Diff HEAD vs child → get changed files
4. Restore working directory from child
5. Move refs/heads/main to child
6. If HEAD now equals redo-tip, delete the ref

​

Undo/Redo Orchestration

1. Set undo_redo_in_progress guard flag
2. Flush pending state to disk
3. Perform undo/redo via git2
4. Reload changed files:
   • .bird → re-parse via songbird-clips pipeline
   • .plugins.json → restore plugin state
   • .mixer.json → reload mixer and apply to engine + push to React
5. Emit clip:history_changed to update UI
6. Clear undo_redo_in_progress guard (blocks React persist echoes)

​

Commit Sources

​

Echo Prevention (Critical)

1. Version counter echo — Each channel tracks a monotonic version; subscribers skip updates they’ve already seen
2. JSON compare echo — For channels using JsonCompare strategy, incoming JSON is compared against cached state (with configurable field rounding for floats like volume/pan)
3. undo_redo_in_progress guard — Blocks all channel commits during undo/redo
4. store_hydrated guard — Blocks ALL commits until initial hydration completes
5. slider_dragging guard — Blocks persistence while user is dragging (uses SliderDragGuard atomic counter)
6. UpdateSource tagging — Each change carries its origin (React, Engine, Collab); subscribers can filter by source
7. PersistGate — Centralized check that gates disk writes on hydration, slider drag, and streaming state

​

History Panel — React

• Fetches via getHistory IPC command (reads git via git2 revwalk)
• Auto-refreshes on clip:history_changed events
• Expandable toggle at bottom of app

​

Key Files

​

Sync Engine (Rust — songbird-sync)

​

State Management (Rust — songbird-state)

​

Headless & CLI (Rust)

​

React UI

​

Tauri App (Rust)