​

Realtime Collaboration

​

How It Works

1. Collab Server — A lightweight Node.js WebSocket server that manages project rooms, syncs file changes, and merges concurrent edits
2. React Client — A WebSocket client in the React UI that auto-pushes changes on every commit and applies remote changes
3. Rust State Sync — The songbird-state collab modules (collab.rs, collab_state_sync.rs, collab_mixer_sync.rs) handle file reading for push, and write + reload remote files with echo suppression via the sync engine’s guard flags

┌──────────────┐         ┌──────────────┐
│  Songbird A  │         │  Songbird B  │
│  (User 1)    │         │  (User 2)    │
└──────┬───────┘         └──────┬───────┘
       │  WebSocket              │  WebSocket
       ▼                         ▼
┌─────────────────────────────────────────┐
│         Collaboration Server            │
│                                         │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  Room Mgmt  │  │  Merge Engine    │  │
│  │  (invite    │  │  (.bird-aware)   │  │
│  │   codes)    │  │  (.json-aware)   │  │
│  └─────────────┘  └──────────────────┘  │
│                                         │
│  ┌─────────────┐  ┌──────────────────┐  │
│  │  Presence   │  │  File State      │  │
│  │  & Cursors  │  │  (per-project)   │  │
│  └─────────────┘  └──────────────────┘  │
└─────────────────────────────────────────┘

​

Quick Start

​

1. Start the Server

# On your server (or locally for testing)
./utils/collab-server.sh

# Custom port
PORT=9000 ./utils/collab-server.sh --port 9000

​

2. Create a Room

​

3. Invite a Collaborator

​

4. Collaborate

• Edit notes, arrangements, or structure in .bird → auto-synced
• Move faders, pan knobs, toggle mute/solo → auto-synced
• Tweak plugin parameters → auto-synced

​

Sync Protocol

​

Message Types

​

Sync Flow

User A edits kick pattern in verse
  → commitAndNotify("[mixer] kick pattern")
  → historyChanged event fires in React
  → collabSocket auto-push (100ms delay)
  → collabGetProjectFiles (reads .bird + .state.json + .edit.json from Rust)
  → WebSocket send → server

Server receives push:
  → Three-way merge (base vs current state vs incoming)
  → .bird: track/section-level merge
  → .json: per-property deep merge
  → Broadcast merged result to User B

User B receives update:
  → collabApplyRemoteFiles (writes files via Rust backend)
  → Rust reloads changed files (same path as undo/redo)
  → undo_redo_in_progress guard prevents echo commits
  → Local git commit records the remote change
  → historyChanged updates the UI

​

Intelligent Merge

​

.bird File Merge

bird file
├── sig (bpm, key, scale)
├── tracks (global definitions)
├── arr (section order + bar counts)
└── sections
    ├── sec intro
    │   ├── trk 1 kick: {p, v, n, t, sw, ...}
    │   └── trk 2 bass: {p, v, n, t, sw, ...}
    └── sec verse
        ├── trk 1 kick: {p, v, n, t, sw, ...}
        └── trk 2 bass: {p, v, n, t, sw, ...}

​

JSON File Merge (daw.state.json, daw.edit.json)

​

Conflict Resolution

​

Presence

• Who’s online — list of connected peers
• Cursor position — which section/track/tool each user is working with
• Activity feed — human-readable log of remote changes

​

Tunnel (Share Session)

1. Click Share Session (Public Tunnel) in the Collaboration panel
2. The server spawns a Cloudflare Tunnel on the collab port (default 8765)
3. A public https:// URL is generated and displayed — share it with collaborators
4. Remote peers connect to the tunnel URL instead of localhost
5. Click Stop tunnel when done

​

Optimistic Mixer Sync

• Outbound: Local changes are throttled to ~30Hz and sent as mixerUpdate messages
• Inbound: Remote changes are applied directly to the Zustand store
• Local lock: While the user is dragging a slider, remote updates for that control are ignored to prevent jitter
• Source of truth: The git commit layer remains authoritative. Optimistic updates are just a fast preview.

​

Deployment

​

Local Development

./utils/collab-server.sh

​

Production (Ubuntu Server)

# Install Node.js if needed
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Clone and install
cd /opt/songbird-collab
npm install

# Run with systemd or pm2
PORT=8765 node server.js

​

Audio Assets

​

Key Files

​

Design Decisions

• WebSocket from React — JavaScript has native WebSocket support. Running the WebSocket client in React reuses the existing Tauri IPC bridge for file I/O.
• File-level sync, not git-object sync — Sending full file contents (not git objects/patches) is simpler and the files are small text. Each client maintains its own local git history for undo/redo independently.
• Server-side merge — The server runs the structured merge engine. This is simpler than client-side merge and ensures a single source of truth. The tradeoff is offline editing doesn’t auto-merge (but local git undo/redo still works fine).
• Last-write-wins — Simple, predictable, and users rarely conflict at the track/section level in practice. No complex conflict resolution UI needed.
• Echo suppression on apply — When applying remote files, the undo_redo_in_progress guard flag is set (same mechanism as undo/redo) to prevent echo-pushing the same changes back to the server.