Leader/member model
A session has one leading device and up to forty-nine following ones. The leader decides what is played and where everyone is in it.
Session roles
| Role | How it happens | What it does |
|---|---|---|
| Leader | Starts a session on the sync screen | Announces itself, runs the server, broadcasts commands |
| Member | Joins a discovered session | Receives commands and executes them |
Even after members join, the leader stays in the "advertising" state — it keeps listening for more arrivals. Only members show "connected".
What the leader controls
| Action | What happens on members |
|---|---|
| Song change | Members move to the same song |
| Forced song change | The same, but also for members who turned following off |
| Scroll position | Scroll positions line up |
| Start auto-scroll | Members start scrolling from the same position at the same speed |
| Pause auto-scroll | Everyone stops at a shared position |
| Auto-scroll speed change | The new speed propagates to everyone |
| Transposition | Members get the same semitone shift applied |
| Section change | A jump to a section is forwarded |
| Metronome start and stop | Members' metronomes start at the same tempo and on the same beat |
| Stage cue | An overlay appears on everyone else's screen — "SOLO", "LAST CHORUS", "END" |
Members who turn following off stay put and can browse on their own. A forced song change is the leader's tool for pulling them back.
Catching up
When a member receives a position that differs from its own, it does not snap there — the position is closed with a smooth glide over roughly two tenths of a second. On a projector or a tablet it does not read as a jerk.
The band metronome
The practical upshot: anyone joining mid-song receives the same anchor and comes in on the right beat. No waiting for the next bar, no catching up by ear.
Stage cues
During a song the leader can send a short cue that appears on everyone else's screen as an overlay across the lyrics — "SOLO", "LAST CHORUS", "END".
Only the leader can send them.
What does not sync
- PDF page turns. The session carries a scroll position, not a page number. On top of that, a horizontal swipe in stage mode changes the song, not the page.
- Song MIDI commands. Everyone has their own rig, so MIDI stays on the device.
Join sequence
A joining member does not receive one big state message, but a series of them:
welcome— identity assignmentsessionInfo— session and member information- Once the new member is announced, the leader sends the current song, any running auto-scroll, the active setlist and an offer of the songs in it
A member can also ask for the full state at any time.
Command timing
Every broadcast command carries:
| Field | Meaning |
|---|---|
leaderEpochMs | The leader's clock at the moment of sending |
executeAt | When to perform the action — 300 ms later by default |
v | Protocol version |
id | Unique message identifier |
executeAt means the same instant everywhere. That also evens out devices with different latency.A member that wants to reach the others does not send directly — it sends to the leader with a "relay" flag. The leader re-stamps the message with its own clock and broadcasts it. That keeps a single timeline.
Requesting content
Beyond control commands, the protocol also carries content itself. The one missing something always initiates:
| What | How it works |
|---|---|
| Song | A member requests a song by identifier, the leader sends its shared fields |
| Setlist | A member requests the active setlist with its song list |
| Bulk transfer | The leader offers metadata for every song in the setlist, the member asks only for what it lacks and receives them one by one with an index |
| PDF, MusicXML, images | Transferred on request, never automatically |
Transfer limits
| Type | Limit |
|---|---|
| Downscaled automatically above 3 MB, refused above 10 MB | |
| MusicXML | 10 MB |
| Image bundle | 25 MB |
Every binary transfer is checksummed with SHA-256 so a corrupted file is detected.
Sharing between members
When the leader does not have a requested attachment, the session does not stall. Brokered member-to-member sharing kicks in:
- The leader asks the others who has the file.
- Those who do announce themselves.
- The requester picks a source.
- The file travels from the chosen member through the leader.
Pre-gig check
Before you start playing, the leader can ask once and the whole band answers. The result is a list of what is about to go wrong:
| Finding | What it means |
|---|---|
| Missing songs | Somebody lacks a song from the active setlist |
| Missing attachments | They have the song but no sheet music or PDF |
| Different setlist | Somebody has a different setlist active than the leader |
| No setlist | Somebody has none active |
| Low battery | The device will not last the gig |
| High latency | A weak connection |
| No reply | The device did not answer |
Worth running when you arrive at the venue, not five minutes before the first song. Missing attachments can only be filled in while everyone is still on the same network.
Limits of the model
Other things worth knowing:
- A session cannot be split or merged; one band = one session = one leader.
- If the leader disappears, members do not elect a replacement — they switch to reconnecting to the same leader.
- Members do not talk to each other directly; even attachment sharing goes through the leader.