Socket.IO events
Real-time communication uses Socket.IO on the same port as the web server. Clients declare a role in the handshake query:
io({ query: { role: "display", displayId: "display-1" } });
| Role | Requirement |
|---|---|
display | None. Receive-only. |
admin | Session cookie of an admin user. |
streamer | Session cookie of any user. |
Connections with any other role, a missing or invalid session, or a foreign Origin header are rejected with a connect error.
Display clients
Displays join the room for their display ID and receive:
| Event | Payload | Description |
|---|---|---|
slide:show | { bundle, slide, duration, json, bundleMeta, transition } | Show a slide. json is the Fabric.js data for editor slides. |
slide:clear | — | Blackout. |
display:state:sync | display state | Current state for this display. |
bundle:meta | { bundle, meta } | Bundle settings changed. |
announce:show | { line1, line2, color } | Show a lower-third announcement. |
announce:clear | — | Remove the announcement. |
streams:assigned | { streams: [{ streamId, streamName, streamSocketId }] } | The live streams to show, in grid order. Sent on connect and whenever the list changes. An empty list means no stream. |
stream:ended | { streamId } | The sender stopped. |
Admin clients
Admins join the admins room.
Client → server
| Event | Payload |
|---|---|
slide:show | { displayId, bundle, slide, duration } |
slide:clear | { displayId } |
cycle:stop | { displayId } |
cycle:queueNext | { displayId, slideId \| null } |
bundle:activate | { displayId, bundle } |
bundle:meta | { bundle, meta, displayId? } |
display:config | { configs: [{ id, name, autoShowStreams?, streamMultiview? }] } |
announce:show | { displayId, line1, line2, color } |
announce:showAll | { line1, line2, color } |
announce:clearAll | — |
stream:show | { streamId, displayId } |
stream:clear | { displayId, streamId? }: without streamId, removes every stream from the display |
Server → client
| Event | Description |
|---|---|
state:sync | Full server state: displays, per-display slide, cycling, queued slide, announcements, connection counts, streams and the stream each display shows. |
streams:update | List of active streams. |
content:changed | Bundles or slides changed on disk; reload lists. |
Streaming (WebRTC signaling)
Admins may watch any stream. A display may only watch the streams assigned to it, with stream:show or because the display auto-shows new streams. One connection may watch several streams at once. stream:signal is only relayed between a streamer and the viewers of its stream.
| Event | Direction | Payload |
|---|---|---|
stream:register | streamer → server | { streamId, name } |
stream:unregister | streamer → server | { streamId } |
stream:watch / stream:unwatch | viewer → server | { streamId } |
stream:viewer:joined / stream:viewer:left | server → streamer | { viewerSocketId } |
stream:signal | both ways | { to, data } sent, { from, data } received |