A platform for community discussion. Free, open, simple.
Optional LiveKit SFU support
For the scoped extension that lets administrators authorize external bot accounts, see External agent participation. That design preserves the human presence path described here and adds provider-maintained presence only for authorized agent sessions.
This is the "SFU integration (future, separate effort)" scoped out of
video-screenshare.md. It is written to be executed by
a coding agent, PR by PR (§9). Line references are against plugin commit
123a826 (2026-07-08) — re-verify before editing; treat method names as the
stable anchors.
Goal: enterprise customers who need many simultaneous video calls can deploy their own LiveKit server and point the plugin at it. Everyone else keeps the current pure-P2P mesh, byte-for-byte.
Non-goals: mid-call mesh↔SFU migration, LiveKit Cloud billing integration, recording/egress (the token/room-name plumbing here is its prerequisite, nothing more), replacing mesh as the default.
1. Design summary
LiveKit is added beside the mesh as a per-room transport branch inside
live-webrtc.js — not as a formal transport-interface refactor. The mesh
path (glare handling, offer retries, ICE-restart detection, transceiver
pre-allocation, join-race buffering in peer-manager.js / signaling.js) is
battle-tested and is not extracted, rewritten, or adapterized. The service
already has a natural seam, proven at three points:
- Outbound: media reaches the transport at exactly three places —
peer creation (
peer-manager.js:209–250),#replaceTrackOnAllPeers(service:2630), and:1414).#syncVideoSenders( - Inbound: all remote media enters through
#registerRemoteTrack(roomId, userId, track, streams)(:2395) and leaves through:2454). Everything downstream (per-user MediaStream registry,#removeRemoteStream(attachStream, volume/deafen,AudioMonitorspeaking detection) operates on plain MediaStreams. - Control: UI components consume only the service's public API; nothing
touches
RTCPeerConnection.
So:
- Each active room instance is tagged with a transport (
"mesh"|"livekit"), decided by the server in the join response and pinned in Redis for the life of the room instance. - Mesh-specific call sites get
if (this.#isMeshRoom(roomId))guards — pure additive guards that are tautologies for default installs. - One new class,
LivekitRoomSession, connectslivekit-clientto the same callbacksPeerManageralready uses (#registerRemoteTrack,#removeRemoteStream), so the remote-media registry and every UI component are untouched.
Presence, sessions, badges, co-presence, user status, admin stats, sound effects, idle/AFK, and the roster UI all ride the existing REST join/heartbeat/leave/state + Redis + MessageBus stack, which never touches media — they are identical on both transports by construction.
2. Key decisions
| Decision | Choice | Why |
|---|---|---|
| Presence/sessions | Keep REST heartbeat + Redis + MessageBus for both transports; LiveKit webhooks are an optional reconcile-only backstop (PR 8) | Sessions, badges, co-presence, user status, admin stats, anon directory all key off ParticipantTracker + Live::Session. Webhooks-as-authority would fork every consumer and break anon directory viewing. Heartbeats guarantee identical analytics on both transports with zero change. |
| LiveKit JS delivery | Vendored ESM bundle under public/javascripts/livekit/, dynamic import() at join time |
Matches the mediapipe precedent (background-blur.js:39–51 dynamically imports vendored assets by URL). Zero LiveKit bytes shipped/parsed on the P2P path; no coupling to core's build. Pinned + checked in, rebuilt via a script like scripts/build-dtln-worklet.sh. |
| Ruby dependency | No gem. Mint JWTs with core's jwt gem; hand-roll three Twirp-JSON RoomService calls (~60 lines) |
The token is a stable, documented HS256 JWT; RoomService accepts plain JSON POSTs to /twirp/livekit.RoomService/* with a roomAdmin JWT bearer. Avoids plugin gem pinning/boot friction. |
| Transport policy | Server-decided at join; pinned per live room instance; policy enum disabled | per_room | all_rooms. No threshold-based auto-cascade |
Mid-call mesh→SFU migration requires dual-connection handoff — maximum risk, zero-regression antithesis. Static per-room-instance resolution covers the enterprise ask ("our town-hall room uses the SFU"). A static size-based variant is a 5-line resolver addition later if demand appears. |
| Mute/PTT semantics | Keep track.enabled flipping on LiveKit too (silence frames through SFU, DTX-suppressed); do not use LiveKit setMuted |
Identical code path on both transports (toggleMute ~:652, PTT ~:2767); zero divergence in PTT latency. Roster mute state already travels as presence metadata via POST /state, not media state. |
| SDK options | adaptiveStream: false, dynacast: true, audio auto-subscribe on |
adaptiveStream keys quality/pausing off attached-element visibility — incompatible with service-owned elements (would pause "invisible" video). autoSubscribe: false for audio risks a subscription bug meaning silence — the worst failure mode for a live product. |
| Client secrets | None of the new settings are client: true |
URL + token reach the client only through the join response of rooms actually resolved to LiveKit. (Deliberately not repeating the TURN-credential-to-every-client pattern of settings.yml:30–33.) |
3. Transport seam contract
The exact call sites in live-webrtc.js that branch on transport.
LivekitRoomSession must satisfy the right-hand column.
Service → transport (outbound)
| Call site (mesh today) | LiveKit branch |
|---|---|
Peer create/destroy diff in #handleParticipants (~:1960–2012) → #createAndOfferPeer |
None — SFU has no per-peer setup. Guard the block. But the roster diff still runs for livekit rooms to drop registry entries for identities absent from the roster (§5, ghost-participant rule). |
#replaceTrackOnAllPeers(newTrack) (~:2630) — NS toggle / mic switch / gate crossing |
session.replaceAudioTrack(newTrack) → LocalAudioTrack.replaceTrack() |
#syncVideoSenders (~:1414) — per-watcher replaceTrack |
session.syncLocalVideo(videoTrack, screenAudioTrack, kind) → publish/unpublish; receive gating moves to the subscriber side |
#applyVideoQuality / #applyScreenAudioQuality (~:1462, 1528) — mesh watcher-count bitrate ladder |
Replaced by publish options + subscriber layer selection (§5, quality rules) |
setWatching(roomId, watching) (~:1141) — POST /state + publisher-side gating |
Keep the POST (roster flags drive tiles on both transports) plus session.setVideoSubscriptionsEnabled(watching) |
#reconnectAllPeers() on role change (~:2248) |
session.refreshPublications() — publish/release mic per new can-speak |
leave() → #teardownRoom (~:1704) |
session.disconnect(), drop from session map. Existing peerManager/signaling teardown calls are no-ops for livekit rooms (empty maps) — no guards needed. |
iceServers / iceTransportPolicy getters (~:226–267) |
Unused — LiveKit brings its own ICE/TURN. Getters stay mesh-only, unguarded. |
Transport → service (inbound) — the same callbacks PeerManager receives
| LiveKit event | Service callback |
|---|---|
RoomEvent.TrackSubscribed(track, pub, participant) |
#registerRemoteTrack(roomId, userId, track.mediaStreamTrack, streamsArg) where streamsArg = [] when pub.source === ScreenShareAudio — preserves the "bare audio track = screen audio" convention (~:2414) with zero change to #registerRemoteTrack — else [participantStream] |
RoomEvent.TrackPublished |
Apply current watching state to the new publication: camera/screen/screen-audio publications created while setWatching(false) must start unsubscribed; microphone publications are always subscribed |
RoomEvent.TrackUnsubscribed / ParticipantDisconnected |
#removeRemoteStream(roomId, userId) (~:2454) |
RoomEvent.Disconnected(reason) |
DUPLICATE_IDENTITY → local-only teardown (§5); other terminal reasons → reconnect ladder (§7d), then leave(room) + toast |
Reconnecting / Reconnected |
Log + tick connectionRevision |
connect() rejection |
Client-unreachable-SFU failure path (§7f) |
userId mapping: LiveKit participant.identity = String(user.id). The
session parses it back to a number before invoking callbacks so registry keys
match roster participant ids — remoteStreamFor(roomId, userId)
(video-tile.gjs) works unchanged.
Explicitly unchanged
lib/live/peer-manager.js, lib/live/signaling.js,
room-message-queue.js, all pipeline libs (noise-suppression.js,
input-gate.js, background-blur.js, audio-monitor.js, media-devices.js,
ptt-manager.js, ptt-utils.js, sound-effects.js), every component
(call-controls, call-widget, room-page, video-tile, voice-canvas, chat-panel,
settings modals, sidebar), all initializers, live-rooms.js, and the whole
public service API consumed by the UI
(join/leave/toggleMute/toggleDeafen/toggleCamera/toggleScreenShare/attachStream/attachVideoStream/remoteStreams/remoteScreenAudioStreams/remoteStreamFor/connectionStateFor/setWatching/canPublishVideo/videoAllowedIn/setInputDevice/setOutputDevice/setVideoInputDevice/localStream/localVideoStream/localVideoKind/audioEnabled/deafened/ptt*).
4. Server changes
Settings (config/settings.yml, after the TURN block)
live_livekit_url: # wss://livekit.example.com — empty = unavailable
default: ""
live_livekit_api_key:
default: ""
live_livekit_api_secret:
default: ""
secret: true
live_livekit_room_policy:
default: "disabled"
type: enum
choices: [disabled, per_room, all_rooms]
validator: "LiveLivekitPolicyValidator"
live_livekit_room_prefix: # LiveKit room-name namespace override
default: ""
live_livekit_mesh_fallback: # opt-in: empty room + mint failure → pin mesh
default: false
None are client: true. LiveLivekitPolicyValidator follows core's
lib/validators/*_validator.rb convention: refuses any policy other than
disabled unless live_livekit_url (must be ws:// or wss://),
live_livekit_api_key, and live_livekit_api_secret are all present,
with a specific translated error per missing field (server.en.yml). Admins
get config-time failure, not first-join failure.
plugin.rb serializes one Site attribute next to live_public_access
(plugin.rb:90): live_livekit_per_room_available = configured and
policy == per_room. It exists solely to gate the room-form checkbox — the
client never needs the policy enum itself.
New: lib/live/livekit.rb
module Live::Livekit
def self.configured? # url + key + secret all present
def self.available_for?(room) # configured? && (all_rooms || (per_room && room.livekit_enabled))
def self.room_name(room)
# default: "#{RailsMultisite::ConnectionManagement.current_db}-r#{room.id}"
# (room id, not slug — slugs are mutable); live_livekit_room_prefix overrides the db prefix
end
def self.mint_token(user:, room:, guardian:) # HS256 JWT via core's `jwt` gem
end
Token claims — least privilege, explicit:
iss: api key,sub:user.id.to_s,name: username,exp: now + 10 minvideo:room= room_name,roomJoin: true,canSubscribe: true,canPublish=guardian.can_speak_in_live_room?(room)(guardian_extension.rb:86–91),canPublishSources= mic always (when canPublish) +camera/screen_share/screen_share_audioiffroom.video_allowed?,canPublishData: false,canUpdateOwnMetadata: false, and explicitlyroomCreate: false,roomList: false,roomAdmin: false,roomRecord: false,recorder: false,hidden: false.
A leaked token can only join one room, as one user, for ≤10 minutes. Guardian
remains the sole authority: tokens exist only for users who passed
ensure_can_join_live_room!. live_video_max_publishers stays enforced
where it is today (rooms_controller#state, rooms_controller.rb:207–210) —
it's a roster-flag gate, transport-independent.
Transport pin: app/services/live/participant_tracker.rb
(NOT lib/live/ — the class lives in app/services, KEY_NAMESPACE = "live:room", SAFETY_TTL = 30.minutes at :5–7.)
- New Redis key
live:room:{id}:transport;pin_transport!(room_id, transport)usesSET NX;pinned_transport(room_id);clear_transport_pin(room_id). - TTL =
2 × SiteSetting.live_participant_ttl_seconds(settings.yml:19, default 30 s), refreshed on every join/heartbeat — a crashed room self-heals in ~60 s instead of holding a stale transport. - Cleared explicitly when the room empties: on last leave in
rooms_controller#leave, with a backstop inJobs::PublishRoomParticipants(app/jobs/scheduled/publish_room_participants.rb), which already sweeps recently-active rooms and can detect emptied ones. Room-emptied cleanup also fires best-effortdelete_room(below).
app/controllers/live/rooms_controller.rb
#join(:95–128): before the presence add —transport = pinned || (Livekit.available_for?(room) ? "livekit" : "mesh"); pin it. Response gainstransport:and, for livekit,livekit: { url:, token: }. Mint failure handling per the §7 table.- New
#livekit_token(POST rooms/:id/livekit_tokeninconfig/routes.rb):ensure_can_join_live_room!+RateLimiter.new(current_user, "live-livekit-token", 10, 1.minute)(network-flap rejoins are the legitimate burst case). The endpoint re-adds presence + refreshes metadata itself (same authz as heartbeat) — it must not require existing Redis presence, because its one consumer is the reconnect ladder that runs precisely when the 30 s presence TTL has lapsed. If the pin is gone or re-resolved to mesh, return a distinct410 Gone("room instance ended") — the client stops the ladder, leaves cleanly, and shows a rejoin toast. #signal(:254): 422 when the room's pinned transport is livekit (defense in depth).#leave: clear the transport pin when the leaver was the last participant.#kick(:228): after the existing broadcasts, best-effortRoomServiceClient.remove_participant(rescued + logged) — the client-sidekickedhandler (~:2047) already forces leave; this evicts the media session too.#destroy: best-effortdelete_room.
app/controllers/live/room_memberships_controller.rb
On role change in a livekit-pinned room, best-effort
RoomServiceClient.update_participant(permission: { can_publish: ... }) so a
promoted stage listener can publish without reconnecting (client sees
ParticipantPermissionsChanged → refreshPublications()). Fallback if the
call fails: client re-mints via livekit_token and reconnects.
New: lib/live/livekit/room_service_client.rb (~60 lines)
Twirp-JSON POSTs — RemoveParticipant, UpdateParticipant, DeleteRoom — to
/twirp/livekit.RoomService/* with a short-lived roomAdmin JWT bearer, via
core HTTP conventions (FinalDestination/Excon). Timeout 2 s, always rescued:
LiveKit being down must never fail a Discourse request. Every failure log
prefixed [live-livekit].
Admin: emergency "End live call"
Admin action (status panel or admin room list) that: calls delete_room,
clears the transport pin, and iterates current participant ids publishing the
existing per-user kicked message (RoomBroadcaster#publish_kick,
room_broadcaster.rb:69–75) to each — zero client changes, #handleKicked
already forces leave. Rejoining users re-resolve the transport. Also ship
rake live:clear_transport_pins for emergencies.
Admin health/diagnostics (own PR)
- Flipping LiveKit config enqueues a one-shot connectivity-probe job whose result surfaces to the admin within seconds, not at first user join.
GET /admin/plugins/live/livekit/status(AdminConstraint) returns: settings-present booleans (never values), a token self-mint check, a RoomServicelist_roomsprobe with latency + error string,last_webhook_at, and currently pinned livekit rooms with a Redis-presence vs LiveKitlist_participantsdiff — the triage view for "connects but no media" / ghost-participant support cases.- Rendered as a card in
admin/assets/javascripts/admin/components/live-dashboard.gjs. - A request spec asserts the API secret never appears in any serializer or status payload.
Per-room policy surface
- Migration:
add_column :live_rooms, :livekit_enabled, :boolean, default: false, null: false(load.skills/discourse-migrationfirst). - Permit
livekit_enabledin both room param lists; expose onroom_serializer.rbto managers only. The live instance's transport is never serialized — clients learn it at join. components/live-room-form.gjs: one FormKit checkbox ("Use media server (SFU)") gated onSite.live_livekit_per_room_available. Stale-form edge: a form loaded before an admin flips policy can still submitlivekit_enabled— harmless (resolver re-checks policy at join); pin with a request spec that the attribute is accepted-but-inert when policy no longer allows it.
Webhooks (optional, PR 8 — reconcile-only)
POST /live/livekit/webhook (engine-scoped, skips CSRF + login), verifies
the Authorization JWT (HS256, api key/secret) + SHA256 body hash. Handles
participant_left and participant_connection_aborted by early-expiring
Redis presence that LiveKit knows is gone (same removal path heartbeat-TTL
uses); room_finished clears the transport pin. Every verified webhook
SETEXes live:livekit:last_webhook_at for the status panel (stale = warning,
never error). Never creates presence; never touches Session rows —
CloseOrphanedSessions remains the correctness backstop on both transports.
5. Client changes
New: lib/live/livekit-session.js (~350 lines)
One instance per active LiveKit room, owned by the service, callback-injected
in the same style as PeerManager (which is what makes it unit-testable):
export default class LivekitRoomSession {
constructor({ roomId, currentUserId,
loadSdk, // async () => livekit-client module (injectable for tests)
getLocalStream, getLocalVideoTrack, getLocalScreenAudioTrack,
onTrack, // → #registerRemoteTrack
onParticipantGone, // → #removeRemoteStream
onDisconnected, // (reason)
onConnectionChange, // ticks connectionRevision
mintToken, // async () => ({ url, token }) — POST livekit_token
}) {}
async connect(wsUrl, token) // import SDK, new Room({ adaptiveStream: false, dynacast: true }), connect, publish current tracks
async disconnect()
async replaceAudioTrack(track)
async syncLocalVideo(videoTrack, screenAudioTrack, kind)
setVideoSubscriptionsEnabled(bool) // + TrackPublished handler applies it to late publications
async refreshPublications() // re-evaluate mic publish after role change
async reconnectWithToken() // ladder: 3 attempts, backoff, mintToken() each round
static isBrowserSupported() // SDK support check; unsupported → translated toast, not an opaque SDK error
}
Default loadSdk:
import(getURL("/plugins/live/javascripts/livekit/livekit-client.mjs")) —
never evaluated for mesh rooms.
Publish rules
- Mic:
publishTrack(localStream.getAudioTracks()[0], { source: Microphone, dtx: true, red: true }). The pipeline's AudioWorklet-destination tracks publish cleanly — LiveKit accepts arbitraryMediaStreamTracks. Mute/PTT keep flippingtrack.enabled, untouched. - Camera:
{ source: Camera, simulcast: true, videoEncoding: <720p preset, maxFramerate 24> }; screen:{ source: ScreenShare, simulcast: true, screenShareEncoding: <maxFramerate 15> }— mirror the capture-time caps and contentHints currently set around ~:1279–1287, else SDK defaults apply. Screen audio:{ source: ScreenShareAudio }+ 128 kbps. - Publish mic only when the user can speak (stage rooms) — mirrors
#canSpeakInRoom(~:335); token grants enforce it server-side regardless.
Subscribe/quality rules (replaces the mesh bitrate ladder — do not skip;
with adaptiveStream: false the SDK defaults every subscription to the HIGH
simulcast layer, which would regress downlink vs the mesh's 400 kbps ladder in
big rooms):
- Screenshare subscriptions:
setVideoQuality(HIGH). - Camera subscriptions: MEDIUM by default; LOW when the room has more than ~6
active video publishers (same threshold the mesh ladder uses at ~:1462).
Re-evaluate on publisher-count changes; the service already tracks
videoPublisherCount(roomId). setWatching(false)unsubscribes camera/screen/screen-audio publications; mic publications are always subscribed. Late publications (published while not watching) must be created unsubscribed via theTrackPublishedhandler.
Disconnect handling
DUPLICATE_IDENTITY(same user joined from a newer tab): local-only teardown — session disconnect + client state cleanup that explicitly skipsDELETE /leave. A normalleave()here would close the new tab'sSessionrow (its id just overwrotemetadata[:session_id]— rooms_controller.rb:377–384), drop the user from the roster until the next heartbeat, and clear their user status. Implement as an option onleave(e.g.leave(room, { skipServer: true })) or a dedicated local teardown. Unit test must assert no DELETE is issued.- Other terminal reasons / mid-call hard-down: reconnect ladder — up to 3
attempts with backoff, each awaiting a fresh
mintToken(); on410 Gonestop immediately, local teardown + rejoin toast; after exhaustion,leave(room)+ toast.
Modified: app/services/live-webrtc.js (~200-line diff, all additive/guarded)
- State:
#roomTransports = new Map()(roomId → transport, default"mesh"when untagged so pre-tag messages/tests/old servers behave identically),#livekitSessions = new Map(), helper#isMeshRoom(roomId). join(room)(:357): read:463), for livekit:data.transport ?? "mesh"anddata.livekitfrom the join response. After mic acquisition and the active-mark (LivekitRoomSession.isBrowserSupported()check, construct +connect(url, token). On connect failure: fireajax(.../leave, { type: "DELETE" })before#handleJoinFailure(room.id)— the exact precedent of the mic-failure path at ~:431–437; otherwise the user ghosts in the roster for the presence TTL and the Session row dangles. Distinct translated toast ("your network cannot reach the live server" — different from the server-side mint-failure copy) +[live-livekit]console log. No mesh fallback client-side ever — other clients may reach the SFU fine; falling back would split future joins.#processRoomMessage(~:1735):signalcase early-returns for livekit rooms.#handleParticipants(~:1941): guard the peer create/destroy block and presence-pending machinery as mesh-only. Roster sync, join/leave sounds,#syncRemoteVideoTracks,#syncVideoSendersstay common. Livekit ghost-participant rule: for livekit rooms the roster diff additionally drops registry entries (calls#removeRemoteStreamand unsubscribes) for identities absent from the roster — mesh gets this for free by destroying the peer; without it, a participant expelled from the roster (heartbeat TTL expiry, kick with failedRemoveParticipant) stays audible forever because voice-canvas plays every stream inremoteStreams.#handleRoleChange(~:2090): mesh → existing#reconnectAllPeers; livekit → mic acquire/release per new role +session.refreshPublications().#replaceTrackOnAllPeers(~:2630): prepend fan-out to#livekitSessions; the existing sender loop is a natural no-op for livekit rooms.#syncVideoSenders(:1414) /:1542): livekit rooms delegate to#broadcastVideoState(session.syncLocalVideo(...); thePOST /statebroadcast stays identical on both transports.setWatching(~:1141): after the existing POST, callsession.setVideoSubscriptionsEnabled(watching)for livekit rooms.leave(:512) /:1704): disconnect + delete session; support the#teardownRoom(skipServerlocal-only variant.- Inbound wiring: bind session callbacks to
#registerRemoteTrack/#removeRemoteStreamexactly as PeerManager is bound (~:137–141); add the disconnect-reason handler.
Not touched: #handleSignal, glare/ufrag logic, #createAndOfferPeer,
#shouldEngagePeer, iceServers, PeerManager/SignalingManager construction,
the entire local audio/video pipeline, remote registry internals,
attach/volume/deafen/PTT/idle/audio-monitor code.
New: vendored SDK + build script
public/javascripts/livekit/livekit-client.mjs— single-file ESM bundle of pinnedlivekit-clientv2.x, built by newscripts/build-livekit-bundle.sh(esbuild or webpack — webpack is already a devDependency) and checked in, exactly likedtln-worklet.js.package.json:livekit-clientas devDependency only (build-time input, never in the app graph) + abuild:livekitscript.- CI grep guard: no static import of
public/javascripts/livekit/anywhere underassets/— converts "zero LiveKit bytes on the P2P path" from a review-time promise into a regression-tested invariant.
6. Transport resolution
Server-only, at join:
pinned = redis GET live:room:{id}:transport
if pinned → use pinned
elsif Livekit.available_for?(room) → "livekit", pin
else → "mesh", pin
- All participants share one transport — guaranteed by the pin; joiners after the first ignore current settings. No client-side choice, no mixed room, ever.
- Config changes affect only the next room instance (first join after the
room empties / pin expires). Live calls are never migrated or split. Setting
descriptions state this explicitly. Emergency levers: admin "End live call",
rake live:clear_transport_pins.
7. Failure-mode policy
| # | Failure | Behavior |
|---|---|---|
| a | Token mint fails, room EMPTY | Join fails: specific translated toast ("Live server unavailable — contact your administrator"), [live-livekit] log, status panel red. If live_livekit_mesh_fallback is on (opt-in — silent degradation hides outages from ops) and the room is empty, pin mesh for this call and proceed. |
| b | Token mint fails, room OCCUPIED on livekit | Join fails with the same toast. Never fall back — would split the call. |
| c | Mid-call SFU blip | SDK auto-resume; heartbeats keep presence/sessions/badges unaffected throughout. |
| d | Mid-call SFU hard-down | Reconnect ladder: 3 token-refetch attempts with backoff via livekit_token; then leave() + toast. |
| e | Webhooks undeliverable | Zero correctness impact; status panel shows stale last_webhook_at as a warning. |
| f | Mint succeeds but the CLIENT can't reach the SFU (corporate firewall blocking WSS/UDP — the most common enterprise failure) | Distinct toast ("your network cannot reach the live server"), immediate DELETE /leave cleanup, [live-livekit] console log. No mesh fallback even under (a)'s setting — other clients may reach the SFU fine. |
| g | Pin says livekit, config half-deleted | Same as (a)/(b) — 503 with clear error; validator (§4) makes this hard to reach. |
| h | Reconnect ladder finds pin gone/re-resolved (room instance ended while client slept) | livekit_token returns 410 Gone; client stops the ladder, local teardown, rejoin toast. |
8. Feature preservation matrix
| Feature | Mesh mechanism | On LiveKit | Change |
|---|---|---|---|
| Mute | track.enabled + /state metadata |
Identical (DTX silence through SFU) | None |
| Deafen | Element-level muted on all sinks + mic force-mute |
Identical — same service-owned elements | None |
| PTT / input gate | track.enabled flips (~:2767); WebAudio gate → #replaceTrackOnAllPeers |
Identical; fan-out extended | 1 branch |
| DTLN noise suppression | Worklet pipeline → new track → #replaceTrackOnAllPeers |
Same pipeline; replaceAudioTrack |
Same branch |
| Mic/output device switch | New gUM → replaceTrack / setSinkId on elements |
Same; output path untouched | Same branch |
| Background blur / camera switch | Canvas captureStream() → localVideoStream → #syncVideoSenders |
Same processed track via publishTrack |
syncLocalVideo |
| Video on/off + publisher cap | /state flag + controller cap |
Identical flag + cap; camera grant in token per video_allowed? |
syncLocalVideo |
| Screenshare + screen audio | Pre-negotiated 2nd transceiver; bare-track convention (~:2414) | ScreenShare(+Audio) sources; empty streams arg preserves the convention |
Session only |
setWatching receive gating |
Publisher-side per-peer replaceTrack + bitrate ladder | Subscriber-side setSubscribed + explicit layer selection (§5) |
setVideoSubscriptionsEnabled |
| Speaking indicators | AudioMonitor AnalyserNode on registry streams |
Identical (LiveKit ActiveSpeakersChanged deliberately unused — one code path) |
None |
| Per-participant volume/mute | Element volume/muted maps |
Identical | None |
| Sound effects / autoplay recovery | Roster-diff driven | Identical (roster from MessageBus on both) | None |
| Idle/AFK/auto-status | IdleTracker + heartbeat piggyback | Identical | None |
| Stage rooms | Peering rules + /state unmute enforcement |
Token canPublish + same /state enforcement; promotion → UpdateParticipant + refreshPublications |
Role branch |
| Kick | kicked MessageBus → client leave |
Same + best-effort RemoveParticipant |
Server call |
| Reconnection | PeerManager restarts/backoff/ICE-restart | SDK resume → ladder (§7d) | Session |
| Multi-tab | Undefined-ish (mesh peers keyed by userId collide) | Deterministic: DUPLICATE_IDENTITY drops the older tab via local-only teardown. Documented improvement, unit-tested |
Handler |
| Sessions/badges/co-presence/stats/user status | REST + jobs | Identical — transport never touches them | None |
| Anon directory viewing | MessageBus + serializers | Identical (anons never get tokens) | None |
9. Implementation phases (PR-sized, independently shippable)
Order: 1 → 2 → 3 strictly sequential; 4/5/6 parallelizable after 3; 7/8/9
last. Run bin/lint --fix on every change; JS tests run via CI.
PR 1 — P2P-only seam tagging (zero behavior change).
live-webrtc.js: #roomTransports/#isMeshRoom defaulting mesh; guard
the peer-build block in #handleParticipants, the signal dispatch, and
#handleRoleChange's rebuild; read data.transport ?? "mesh" in join.
rooms_controller.rb: join response gains transport: "mesh".
Acceptance: entire existing JS suite (live-webrtc-test.js,
peer-manager-test.js, signaling-test.js), integration .gjs tests, and
system specs pass unmodified; diff has no deletions of mesh logic.
PR 2 — Server: settings, validator, resolver, tokens, pin.
settings.yml + locales, lib/validators/live_livekit_policy_validator.rb,
lib/live/livekit.rb, pin helpers in
app/services/live/participant_tracker.rb, rooms_controller.rb
(resolution, join payload, livekit_token with presence re-add + rate limit +
410 semantics, signal guard, pin-clear on last leave),
Jobs::PublishRoomParticipants backstop, config/routes.rb, plugin.rb
Site attr, request specs.
Acceptance: LiveKit unconfigured → join responses byte-identical plus
transport: "mesh". Token decodes to the full §4 claim set across the
guardian × room_type × video matrix (stage listener → canPublish: false;
video-off room → no camera source; anon → no token path). Pin lifecycle spec:
set on first join (NX under race), held across config change, cleared on
empty, ~60 s expiry after crash, livekit_token works without presence and
410s when the pin is gone. Mint failure follows §7a/b including the
mesh-fallback setting. Secret never appears in any payload.
PR 3 — Client: vendored SDK + LivekitRoomSession, audio-only calls.
scripts/build-livekit-bundle.sh, checked-in bundle, package.json devDep,
lib/live/livekit-session.js, live-webrtc.js (join/connect path with
DELETE-/leave-on-failure, #replaceTrackOnAllPeers fan-out, leave/teardown +
skipServer, disconnect-reason handling, ghost-participant roster rule), unit
tests with a fake SDK injected via loadSdk.
Acceptance: mesh tests untouched and green. LiveKit unit tests prove: SDK
never loaded for mesh rooms (spy on loadSdk); mic published post-join; NS
toggle → replaceAudioTrack; TrackSubscribed populates
remoteStreams/remoteStreamFor with numeric userId keys; screen-audio
convention preserved; DUPLICATE_IDENTITY → local-only teardown with no
DELETE /leave issued; connect failure → DELETE /leave + join-failure path;
roster expulsion drops the participant's media; reconnect ladder stops on 410.
CI grep guard on static imports in place.
PR 4 — Client: video, screenshare, watching, quality, role change.
livekit-session.js (syncLocalVideo, setVideoSubscriptionsEnabled +
TrackPublished late-publication handling, subscriber layer selection,
publish encoding presets, refreshPublications), service branches
(#syncVideoSenders/#broadcastVideoState/setWatching/#handleRoleChange).
Acceptance: camera toggle publishes with simulcast + encoding preset and
POSTs /state identically to mesh; screenshare lands in
remoteScreenAudioStreams; setWatching(false) unsubscribes, and a camera
published afterwards starts unsubscribed until setWatching(true); layer
selection: >6 publishers → LOW tiles, screenshare stays HIGH; role promotion
publishes mic without reconnect. Mesh video tests untouched.
PR 5 — Server: moderation/lifecycle sync.
lib/live/livekit/room_service_client.rb (3 Twirp calls),
rooms_controller#kick/#destroy, room_memberships_controller.rb, "End
live call" admin action (per-user publish_kick loop + delete_room + pin
clear), rake live:clear_transport_pins, WebMock specs.
Acceptance: kick/role change/destroy fire Twirp calls on livekit-pinned
rooms; LiveKit downtime never fails a Discourse request; mesh rooms make zero
HTTP calls; End-live-call empties a room using only existing client message
types.
PR 6 — Per-room policy surface.
Migration (load .skills/discourse-migration first), room.rb, serializer,
both param permit lists, live-room-form.gjs FormKit checkbox gated on
Site.live_livekit_per_room_available, locales.
Acceptance: checkbox visible only when configured + policy per_room;
toggling mid-call doesn't affect the live instance (pin precedence spec);
stale-form submit is accepted-but-inert when policy changed; mesh-only
installs see no form change.
PR 7 — Real-LiveKit testing, docs, runbook.
spec/system/live_livekit_spec.rb (two-browser camera flow mirroring
live_live_rooms_spec.rb, gated on ENV["LIVE_LIVEKIT_TEST_URL"],
docs show docker run livekit/livekit-server --dev); verify
live_fake_media.rb fakes satisfy the SDK (expected no-op — livekit-client
uses navigator.mediaDevices and we publish our own tracks);
docs/local-fake-participants.md, README.md, ARCHITECTURE.md updates;
§10 runbook as an ops doc including CSP note; manual Safari + iOS/Android
checklist (join, hear audio, publish camera, receive screenshare, reconnect
after backgrounding — livekit-client has real platform nuances: H.264 vs VP8
simulcast on Safari, autoplay vs service-owned elements);
isBrowserSupported() guard wired to a translated toast; live-bots README
PR in the external repo (WSS/UDP egress; the "≥2 bots per room" mesh
workaround does not apply to livekit rooms).
Acceptance: gated system spec green against a dev container locally;
ungated CI unchanged.
PR 8 (optional) — Webhook reconciliation. Controller + route + verifier +
specs per §4. Acceptance: signature/body-hash rejection paths;
participant_left/participant_connection_aborted early-expire stale
presence; room_finished clears the pin; last_webhook_at freshness marker;
no effect on Session rows beyond existing TTL behavior.
PR 9 (optional) — Admin health panel. Probe job, status endpoint,
dashboard card, [live-livekit] log audit, secret-never-serialized spec,
per §4.
10. Enterprise deployment runbook (sketch — full version ships in PR 7)
- Provision: 2–4 cores is ample (audio ≈ hundreds of participants/core,
720p ≈ ~100 tracks/core). Run
livekit/livekit-server(Docker or binary) with onekey: secretAPI pair,use_external_ip: truebehind NAT,webhook.urls: [https://forum.example/live/livekit/webhook]if PR 8 is deployed. Single node — no Redis needed; each room must fit one node. - Network: reverse proxy (WebSocket upgrade + long timeouts) → 7880 as
wss://livekit.example.com; open 7881/TCP (ICE-TCP fallback) and the UDP range; optionally embedded TURN on 443/TLS with its own hostname + cert. Classic failure: "connects but no media" = missinguse_external_ip/firewalled UDP — check first. If a CSP is enforced at the proxy in front of Discourse,connect-srcmust include the LiveKit wss host (Discourse core currently emits no connect-src of its own — but see risk 8). - Discourse: set
live_livekit_url/_api_key/_api_secret; picklive_livekit_room_policy. Mesh rooms keep using the existing STUN/TURN settings. - Verify: PR 9's status panel, or join a livekit room from two networks and
confirm
transport: "livekit"in the join response + a single PC to the SFU inchrome://webrtc-internals. - Operations: settings changes apply to the next room instance; force-flip a
live room via "End live call" or
rake live:clear_transport_pins. If the SFU dies mid-call, clients run the reconnect ladder; presence/analytics keep working (heartbeats are Discourse-side). - Multisite / shared cluster: one API key pair per site; each site's webhook URL listed in the LiveKit config; room names are DB-prefixed by default as defense in depth.
- Upgrades: the client SDK bundle is pinned in-repo (
build:livekitbumps it); document the tested server version range in README.
11. Risks
- Vendored SDK ↔ server protocol drift — pin + document the tested server range; bumps are one-commit affairs via the build script.
track.enabledmute through SFU — silence frames still consume (tiny, DTX-suppressed) upstream. Accepted for path parity; SFU-sidesetMutedis a later optimization behind the same seam.- Watcher-gating semantics shift — mesh gates at the publisher
(non-watchers cost the publisher nothing); LiveKit publishes once
regardless. Publisher upstream is constant (the point of an SFU), but the
live_video_max_publisherscopy ("increases CPU for everyone") is wrong for livekit rooms — locale nuance in PR 7. - Role-change permission race — if
UpdateParticipantfails and the client publishes before re-mint, the SFU rejects the publish. Mitigation:refreshPublicationsretries afterreconnectWithToken; the/stateunmute rule still gates the roster flag. connectionStateForfidelity — LiveKitReconnectingdoesn't surface as"connecting"(mesh doesn't surface per-peer trouble either — parity, not regression). Candidate follow-up.- Pinned-livekit + broken config = room unjoinable by design — never split a room; validator + runbook + explicit error copy mitigate.
- Multi-tab behavior changes on livekit (older tab drops deterministically) — an improvement over mesh's undefined collision, but document it and keep the local-only-teardown unit test.
- Core CSP roadmap — core plans to promote
connect_srcto an extendable default directive (lib/content_security_policy/builder.rbcurrently no-ops plugin connect_src extensions). When that lands, the plugin must register a CSP extension for the configuredlive_livekit_urlhost or every LiveKit install breaks on a core upgrade. Track it; cheap now, expensive to discover later.
12. Open questions (product)
- Should
all_roomsalso cover audio-only rooms whilelive_video_enabledis off? Design says yes — audio-only is the cheapest LiveKit workload. - Adopt LiveKit
ActiveSpeakersChangedfor speaking indicators on livekit rooms eventually (saves N AudioContexts in large rooms)? Deferred — forks the indicator path. - Egress/HLS "broadcast stages" — confirm the room-name scheme now
(
{db}-r{id}) so egress can key off it later. - live-bots at SFU scale: a lone bot does transmit to an SFU (the mesh "≥2 bots" workaround is obsolete there) — downsize bot rosters for livekit demo rooms?