A platform for community discussion. Free, open, simple.
Live Plugin Architecture
Live adds lightweight WebRTC live rooms to Discourse without proxying audio/video through the server. Media runs over one of two transports — the default peer-to-peer mesh, or an optional self-hosted LiveKit SFU (see livekit.md) — while everything else (presence, sessions, roster, moderation) is transport-independent. It consists of the following layers:
Backend
- Models
Live::Room: describes each live space and keeps ownership, slug, visibility, and capacity metadata. Creator is automatically promoted to room moderator. Rooms flaggedephemeralare short-lived rooms created programmatically by other features and are excluded from every discovery surface (see ephemeral-rooms.md).Live::RoomMembership: links users to rooms while storing participant/moderator roles.
- Services
Live::ParticipantTracker: stores the list of actively connected users per room in Redis with a short TTL. Join/leave actions refresh MessageBus subscribers. Also pins each live call's transport (meshorlivekit) so every participant of a call is on the same one; the pin clears when the room empties.Live::RoomBroadcaster: emits participant snapshots to/live/rooms/:idMessageBus channels so Ember clients can update sidebars in real time.Live::DirectoryBroadcaster: keeps the sidebar list in sync across clients by broadcasting CRUD events to/live/rooms/index. Skips ephemeral rooms, which never appear in the directory.Live::EphemeralRoomManager: the only entry point for creating ephemeral rooms, plus their TTL-based reaping (driven by a scheduled job). Contract in ephemeral-rooms.md.Live::SignalRelay: relays raw WebRTC SDP/ICE payloads between peers via MessageBus without touching media data (mesh rooms only).Live::Livekit: mints short-lived, least-privilege LiveKit access tokens (HS256 JWT) and resolves whether a room is eligible for the SFU perlive_livekit_room_policy.Live::Livekit::RoomServiceClientmirrors kicks, role changes, and room deletion to the LiveKit server best-effort via Twirp-JSON.
- Controllers
RoomsControllerexposes CRUD, join/leave, participant, and signaling endpoints.RoomMembershipsControllerlets moderators manage explicit memberships.
- Authorization
- Guardian extensions gate room visibility, membership, and management. Site settings define who can create/manage rooms and cap per-user ownership tallies.
- Camera and screen sharing are separate group-gated capabilities, resolved per user against the room's own media flag and their speaking rights. Publishing is enforced at the state endpoint and, on LiveKit rooms, by the token's track-source grants. Each room's serialization carries the viewer's own two rights for the UI, and every roster entry carries that sender's entitlements — mesh peers exchange media directly, so receivers gate video and screen audio on the sender's server-attested entitlement plus their published state.
Frontend
- Services
live-rooms: fetches initial room data, subscribes to MessageBus channels, updates tracked sidebar state, and forwards participant events to the UI.live-webrtc: managesnavigator.mediaDevicescapture, maintains oneRTCPeerConnectionper peer (mesh) or oneLivekitRoomSessionper room (LiveKit), exchanges offers/answers/candidates through thesignalendpoint on mesh rooms, and keeps remote audio elements synced. Both transports feed the same remote-media registry, so every component downstream is transport-agnostic; the vendoredlivekit-clientbundle is dynamically imported only when a LiveKit room is joined.
- Sidebar Integration
live-sidebarinitializer registers a sidebar section with custom links for each room. Each link swaps its label with inline avatar thumbnails (plus a counter) so active participants are visible without modifying core sidebar components.
- Room UI
live-roomroute/controller fetch full room metadata, render participant lists, and command the WebRTC service to join/leave rooms.Live::VoiceCanvasmounts<audio>sinks for local and remote streams during active calls.- Presentation layout automatically features the first screen share or active camera. A viewer can locally override that choice from a participant's video-tile menu; selecting a layout through the standard control restores automatic selection.
Message Flow
- User joins a room →
POST /live/rooms/:id/joinresolves the call's transport (pinned in Redis for the call's lifetime), adds them to Redis, and broadcasts the participants list. For LiveKit calls the response also carries the server URL and a short-lived access token. - Clients refresh presence with
POST /live/rooms/:id/heartbeatevery 10 seconds (TTL is 30 seconds) without re-broadcasting participants. - On mesh calls, each participant receiving the broadcast spins up
RTCPeerConnectionobjects (only lower user IDs send offers to avoid glare) and relays SDP/ICE payloads viaPOST /live/rooms/:id/signal. On LiveKit calls the client instead opens a single connection to the SFU and publishes/subscribes there; thesignalendpoint rejects payloads for those rooms. - Audio flows directly peer-to-peer (or through the site's own LiveKit server); Discourse only transports JSON signaling events.
- Sidebar avatars and the room screen update automatically as MessageBus notifications arrive — the roster is driven by Redis presence on both transports, never by media state.