Running a session
A session has one leading device and the members that follow it. 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.
Personal fields do not sync either — transposition can be broadcast as a command, but the value stored with your song stays yours.
What happens when you join
On joining, a member gets everything they need to play: an identity in the session, the roster, the current song, the active setlist, and an offer of the songs from it they are missing. If auto-scroll or the metronome happens to be running, those come across too — and land in the right place, not back at the start.
If something falls out of step, the full state can be asked for again.
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 |
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 |
| Muted audio | The device's volume is down, so it will not hear the metronome or backing tracks |
| Empty setlist | The active setlist has no songs in it |
| Song count mismatch | The setlists share a name but not a length |
| Unplayable songs | A song has neither lyrics nor an attachment — there will be nothing on stage |
| Songs without a duration | Without durations there is no estimate of when the set ends |
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.
A locked session
| Open session | Password-locked | |
|---|---|---|
| Who can join | anyone on the same network | only those who know the password |
| Transferred content | not encrypted | encrypted (AES-256-GCM) |
The key is derived from the password and is never sent anywhere — only your band knows it.
When the leader drops out
If no backup member was nominated, the others switch to reconnecting to the same leader.
Limits of the model
Things worth knowing:
- A session cannot be split or merged; one band = one session = one leader.
- Taking over is not a seamless automatic failover — there is a moment with nobody leading, and a person confirms it.
- Members do not talk to each other directly; even attachment sharing goes through the leader.