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

# songbird-collab

Real-time collaboration infrastructure for multi-user DAW sessions.

## What it owns

* Peer management and operation logs.
* WebSocket transport to the Node.js collab server (`server/server.js`).
* Throttled mixer broadcasting.
* State, session, and transport synchronization across peers.

## Public API

Modules:

* `collab` — top-level session lifecycle, peer management, room join/leave.
* `collab_transport` — WebSocket connection to `server/server.js`.
* `collab_mixer_sync` — debounced/throttled mixer-parameter broadcast and apply.
* `collab_state_sync` — full project state push/pull and merge integration.

## How it fits

Sits between `songbird-state` (source of truth being synced) and the network. Consumed by `songbird-state`, `songbird-app`, `songbird-engine`.

```
React UI                                     Other Peer
  ├─ services/collabSocket.ts                  ↑
  ├─ services/collabMixerSync.ts               │
  └─ data/slices/collab.ts                     │
       │ sync engine (collab.* commands)       │
       ▼                                       │
  songbird-sync::channels::collab               │
       │                                       │
       ▼                                       │
  songbird-collab    ───WebSocket───►   server/server.js
  (this crate)                          (Node.js)
                                          │
                                          ▼
                                        merge/{bird-merge.js,json-merge.js}
```

All UI ↔ Rust traffic goes through the sync engine — see AGENTS.md §3 and the
`collab` channel at
`rust/crates/data/songbird-sync/src/channels/collab/`. There is no direct
Tauri command path for collab; everything is a `collab.*` command or
`collab:*` event.

## Sync Protocol

Wire messages between the Rust client and `server/server.js`:

| Direction       | Type         | Description                            |
| --------------- | ------------ | -------------------------------------- |
| Client → Server | `create`     | Create room, returns invite code       |
| Client → Server | `join`       | Join room with invite code             |
| Client → Server | `push`       | Push file changes after a local commit |
| Client → Server | `pull`       | Request current file state             |
| Client → Server | `presence`   | Cursor / tool position                 |
| Server → Client | `created`    | Room created + invite code             |
| Server → Client | `joined`     | Joined + files + peer list             |
| Server → Client | `update`     | Remote changes (post-merge)            |
| Server → Client | `pushAck`    | Push acknowledged                      |
| Server → Client | `presence`   | Remote cursor update                   |
| Server → Client | `peerJoined` | Peer connectivity                      |
| Server → Client | `peerLeft`   | Peer disconnect                        |

The `collab` sync-engine channel translates these into typed events
consumed by React (see `defs.rs` for the full enum).

## Merge Strategy

Performed by the Node.js server, not by this crate — but consumers should
understand the contract:

* **`.bird` files**: parsed into a structured tree (sig → tracks → arr →
  sections → tracks). Merged at **track-per-section** granularity. Two users
  editing different tracks in the same section auto-merge.
* **`.mixer.json`**, **`.plugins.json`**: recursive deep merge at the
  per-track-property level. Different controls auto-merge.
* **Conflicts**: last-write-wins (the incoming push takes precedence).

Server-side merge code lives in `server/merge/{bird-merge.js,json-merge.js}`.

## Echo Prevention (critical)

When applying remote files, the client must set the `undoRedoInProgress`
guard so the local commit loop does not echo the changes back to the
server. This reuses the same guard mechanism as undo/redo. Skipping this
causes infinite sync loops between two peers.

Full guard semantics: `rust/crates/data/songbird-state/SPEC.md`.

## Running the collab server locally

```bash theme={null}
./utils/collab-server.sh           # default port 8765
PORT=9000 ./utils/collab-server.sh # custom port
```

## Tests

```bash theme={null}
cargo test -p songbird-collab            # Rust client tests
node server/test-merge.js                # 7 server-side merge tests
```

For multi-peer browser testing, follow the `e2e-headless` skill — open
two browser sessions and exercise create/join/push/pull through the UI.
See AGENTS.md §6 for the mandatory browser-testing rule that applies here.