Connecting devices

What a room is

A room is one live teleprompter session, owned by one account. It holds a snapshot of a script, the current playback state, and the list of devices attached to it.

Access to a room is not granted by a link. Every device that wants in has to be signed in to the account that opened it. The server checks ownership on every request, and the secret that names the realtime channel (a 256-bit value) is only ever returned to a signed-in device on that account.

Join codes

A code looks like K7M-2QF: six characters in two groups. The alphabet leaves out every character that gets misread when someone reads it off one screen and types it into another: no O or 0, no I or 1, no S or 5, no B or 8.

Codes are unique among live rooms only. Once a room ends its code goes back into circulation, which is why a code from an earlier session will not resolve.

Roles

Each device takes one of two roles when it joins.

• Display: the screen your audience is behind. Full bleed, edge fades, a reading line, optional mirroring, and a screen wake lock. Chrome fades out a couple of seconds after the text starts moving.
• Remote: the device in your hand. Shows the same words at its own type size, plus the transport controls.

A device can change role by going back to the room page and picking the other one; nothing is locked in.

More than two devices

Rooms are not limited to a pair. You can add a second display for a co-host reading the same script, or a second remote so a producer can take over.

Exactly one device drives playback: the display that has been connected the longest. Every other device, extra displays included, follows it. Both sides work that rule out independently from the presence list, so there is no negotiation round trip and no moment where two devices think they are in charge.

Controls on a following device still work. They are sent to the driver as commands, applied there, and broadcast back out.

Direct or relay

Devices always meet on a realtime channel first, because that works everywhere and needs no luck with NAT. As soon as two devices can see each other, they exchange WebRTC offers over that channel and try to open a direct data channel.

If it opens, position updates move onto it and the badge reads Direct. If it does not (symmetric NAT, a corporate network that blocks UDP, no STUN reachability), the badge reads Relay and the same messages keep flowing through the relay. There is no degraded mode; the only difference is a few tens of milliseconds.

Signalling always goes over the relay, even after the direct channel is open, because it is what bootstraps the direct path in the first place.

How long a room lives

A room stays live while something is on it. Five quiet minutes after the last activity it closes itself, releasing its join code. You can also end one deliberately from the room page or from the display’s settings drawer.

Three things count as activity:

• A display or a remote attached to the room. Each checks in every forty-five seconds, and again the moment it comes back to the foreground.
• The room page open and visible, which is why walking to the other device does not cost you the room. The page you left the code on counts while you can see it, and stops counting when you switch away.
• Saving an edit to the script behind the room, since that writes new text into the room itself.

What does not count is a device that has gone to sleep. A phone that locks or a laptop whose lid is shut stops checking in (browsers freeze a hidden tab’s timers, and a suspended one sends nothing at all), so a room left on one closes like any other.

Playback position is written back to the database every few seconds, so a device that reloads (or one that drops off the network and comes back) picks up within a sentence of where it stopped.

Editing the script behind a live room is safe. The new text is written into the room as part of the save, and every device picks it up within a few seconds, keeping the reading position. You do not have to close the room and open another one.

The message formats and the exact state model are written up in Architecture, over in the developer documentation.