live-platform
A browser call that shares screen, voice and camera from a link, served by one Go binary with its own WebRTC media server.
Overview
live-platform is a browser call for people who need to show something to someone right now: a pair-programming session, a quick look at a screen, a call with a friend who has no account anywhere. The room is the address, and whoever opens a free name owns that room. No account, nothing to install.
One Go process serves the page, the signalling and its own selective forwarding unit (SFU) built on Pion. Media is not routed through a hosted service and does not use a peer-to-peer mesh, where each person would upload one copy per listener.
It is deliberately narrow. It is not a recording or transcription product, and it has no end-to-end encryption yet. The security section lists what is and is not built.
| Fact | Value |
|---|---|
| Room size | Up to 10 people |
| Room release | 30 seconds after the last person leaves |
| Access | Public (link) or private (room code); either can be listed in the lobby |
| Media | Microphone, camera, screen with its sound, push to talk, background blur |
| Extras | Chat, raised hand, Excalidraw whiteboard, owner controls |
| Languages | English and Portuguese, from the browser |
Run it
Needs Go 1.27.4, Node.js 26 and a browser with WebRTC. Two terminals; the Vite dev server proxies /api to 127.0.0.1:8080 and /ws to 127.0.0.1:8081.
cd server
PUBLIC_ORIGIN=http://localhost:5173 go run ./cmd/live
cd web
npm ci
npm run dev # http://localhost:5173Open http://localhost:5173/any-name in two tabs to try a call. To serve everything from one binary:
cd web && npm ci && npm run build
cd ../server && CGO_ENABLED=0 go build -trimpath -o live ./cmd/live
WEB_DIR=../web/dist ./live # page and API on :8080; GET /up answers 200Without WEB_DIR the server answers the API only. The page and the signalling use different ports, so in front of a browser both must sit behind one origin. The Dockerfile builds a static binary on distroless, non-root, with PORT=3000, SIGNAL_PORT=3001 and WEB_DIR=/web.
mise install # pinned Go, golangci-lint, vlint, revive
lefthook install # fast lint on commit, changed-package lint on push
mise run check # lint-full, race tests, Semgrep
mise run test # go test -race -count=1 ./...
cd web && npx vitest run
cd web && npm run test:live # client against a real server| Variable | Default | Effect |
|---|---|---|
| PORT | 8080 (3000 in the image) | HTTP: page, API and /up |
| SIGNAL_PORT | 8081 (3001 in the image) | Signalling WebSocket at /ws |
| PUBLIC_ORIGIN | empty | Origins allowed to open the socket; empty allows only the request's own host |
| WEB_DIR | empty (/web in the image) | Built client; empty serves the API only |
| WEB_LIVE_DIR | empty | Directory laid over WEB_DIR so a newer client can be served without a restart |
| MEDIA | on | off runs presence and chat without the SFU |
| MEDIA_UDP_PORT | 0 | One shared UDP port for all media; 0 lets each connection pick its own |
| MEDIA_PUBLIC_IP | empty | Address announced to browsers behind NAT |
| HANDOVER_DIR | empty | Directory shared with the next process for planned restarts |
| AUDIT_DIR | empty | Audit trail directory; empty turns it off |
| AUDIT_RETENTION_DAYS | 183 | Days of audit files kept |
| OTEL_EXPORTER_OTLP_ENDPOINT | empty | OTLP/HTTP collector; empty turns tracing off |
Everything is read from the environment once, at start. A value that cannot be parsed stops the server and names the setting.
Architecture
One binary, three listeners. HTTP serves the built client and a small JSON API. A gnet event loop carries the lv.1 WebSocket. Pion carries media over UDP with DTLS-SRTP, straight between browser and server.
Browser (React 19) live (one Go process)
+----------------------+ HTTPS +---------------------------+
| pages and stores |-------------->| net/http page, /api |
| | WSS /ws +---------------------------+
| |-------------->| gnet + gobwas/ws lv.1 |
| | | | |
| | | presence hub |
| | | one actor per room |
| | | | |
| publish PeerConn | UDP, DTLS | Pion SFU |
| subscribe PeerConn |<=============>| |
+----------------------+ SRTP +---------------------------+| Listener | Library | Carries |
|---|---|---|
| HTTP (PORT) | net/http | client, GET /api/rooms/{slug}, /api/lobby, /api/project, /api/pass/{id}, /up |
| Signalling (SIGNAL_PORT) | gnet + gobwas/ws | lv.1: presence, chat, whiteboard, owner actions, SDP and ICE |
| Media (MEDIA_UDP_PORT) | Pion WebRTC | RTP over DTLS-SRTP |
The server follows ports and adapters, with dependencies pointing inward.
server/
cmd/live/ binary; `live audit` reads the audit trail
app/ composition root: env read and checked once
core/room/ Room aggregate. Pure: no clock, no I/O
port/inbound|outbound/
service/presence/ hub + one goroutine per room
signal/ lv.1 over WebSocket on gnet
httpapi/ page/ JSON routes; client with security headers
sfu/ Pion media engine
handoff/ audit/ guestpass/ clientinfo/ github/The client lives in web/src, one folder per concern: room, media, signal, session, lobby, board, domain, ui, i18n. It uses no router and no state library; three pages and one store per concern do not need them.
Join flow
- 1Open the socketThe browser opens the lv.1 WebSocket and sends join. The socket accepts only the configured origins.
- 2Claim a seatThe signalling server hands the frame to the presence hub. The room's actor claims a seat.
- 3Receive stateThe browser gets joined with its seat, generation and resume secret, then the whole roster with a version number.
- 4Negotiate publishThe browser sends its SDP offer over the same socket in an rtc frame. The hub negotiates the publish connection with the SFU.
- 5Send mediaMedia goes straight to the SFU over UDP. The SFU forwards packets, undecoded, to everyone else.
- 6Broadcast changesEach change in the room sends everyone a new whole roster.
Each participant keeps two peer connections: one publishes, one receives everyone else. Forwarded tracks are named by who sent them and what they are (microphone, camera, screen, screen sound), from the sources the publisher declared.
Presence
The server is the only authority on who is in a room. Browsers only report. It watches three signals: the socket, a heartbeat and the media path.
- 1First missed signalOthers see the participant as unstable.
- 2After a 4 second graceThe participant shows as reconnecting.
- 3No returnThe participant is removed. Leaving on purpose is immediate.
A reload keeps the seat. The browser holds a per-room secret for the tab's lifetime and presents it to resume. The secret rotates on every resume and the old one is refused.
On a planned restart the stopping server can write its rooms to HANDOVER_DIR. The new process adopts them and holds each seat for 12 seconds while browsers reconnect. A crash loses the rooms.
Room model
Every change to a room goes through its actor, in order, so there are no locks around room state. The Room aggregate in core/room is told the time and answers with what changed. It has no clock and no I/O, so every presence rule is a plain unit test.
- Seats are a uint64 bitmap.
- What a participant has on (microphone, camera, screen, screen audio, hand, owner, unstable) is a uint16 of flags.
- Rosters are sent whole, with a version number, never as a diff. A browser that missed a message is right again at the next one.
- Each room publishes an atomic summary, so listing the lobby never blocks on a room's goroutine.
Room code derivation in private rooms is covered under Security. The room aggregate keeps the owner rules: transfer, remove, ban, mute all, speak by raised hand, access and listing changes.
Protocol lv.1
JSON text frames over one WebSocket, each with its type in t.
| Direction | Frames |
|---|---|
| Browser to server | join, resume, hb, leave, media, rtc, look, photo, chat, board, owner, remove, ban, transfer, listed, password |
| Server to browser | joined, roster (versioned, whole), rtc, chat, photo, board, error |
Application close codes tell the browser why a socket ended.
| Code | Meaning |
|---|---|
| 4001 | Superseded by another tab |
| 4012 | Server restarting |
| 4400 | Bad frame |
| 4401 | No hello |
| 4403 | Removed |
| 4404 | Banned |
| 4408 | Silent |
| 4409 | Too slow to read |
| 4429 | Flooding |
Signalling limits: 128 KiB per frame, 2 MiB of unsent data, 20 frames per second with a burst of 80. A client past them is disconnected with a code that says why.
Media path
- The SFU forwards RTP without decoding it.
- Codecs are Pion's defaults. The server asks publishers for a keyframe every 2 seconds so late joiners get a picture quickly.
- No simulcast and no forwarding on demand: every stream goes to everyone at the quality it was sent.
- Audio processing runs in the browser only: RNNoise for the strongest voice filter, plus gain, a noise gate and echo cancellation. Background blur runs MediaPipe in the browser.
- One UDP port for all media when MEDIA_UDP_PORT is set, announced at MEDIA_PUBLIC_IP.
- There is no TURN relay, so a network that blocks UDP cannot carry media.
Because every stream is forwarded to every other participant, the server's upload grows with the square of a room's size. The room cap of 10 bounds it.
The whiteboard is Excalidraw, pinned and loaded only when opened. It lives in the browsers; the server relays its pieces without reading them and keeps nothing.
Security model
In a private room the browser derives 64 bytes from the room code with PBKDF2-SHA-256 at 600,000 iterations, salted with the room's address. The first 32 bytes are a verifier sent to the server, which stores only its SHA-256. The other 32 are reserved as a media key and never leave the browser. A shared link carries the code after #, which browsers do not send. Ten wrong attempts lock the door for five minutes.
- CSP: default-src 'none', own-origin scripts, styles, fonts and connections, no inline script or style. 'wasm-unsafe-eval' is allowed for the voice filter and blur.
- Supply chain: exact versions, committed lockfiles, npm install scripts disabled, base images and CI actions pinned by digest, Dependabot, govulncheck, go mod verify, npm audit, and a CycloneDX SBOM for server and client.
- Image: distroless, static, non-root.
- Audit: without AUDIT_DIR the server records nothing. With it, one JSON line per fact goes to a daily file, deleted after AUDIT_RETENTION_DAYS. A public room's chat text is recorded; a private room's chat keeps who, when and length only.
- Tracing spans carry the room name and flags, never an address, a name or chat text.
No end-to-end encryption. Media is encrypted between each browser and the server (DTLS-SRTP) and the server could read it. Chat, private messages and the whiteboard pass through the server in clear.
Decisions
| Decision | Chosen | Rejected | Why |
|---|---|---|---|
| Media topology | Own SFU on Pion for every room | Mesh; hosted SFU | A mesh costs each person one upload per listener; a hosted SFU puts media on someone else's server. |
| Signalling | gnet event loop | Plain net/http WebSocket | Holds many idle sockets cheaply. It carries signalling only. |
| Page and API | net/http | A framework | Nothing here needs more. |
| Client state | No router, no state library | Router and global store | Three pages and one store per concern do not need them. |
| Room state | One actor per room | Shared state with locks | Ordered changes, pure aggregate, simple unit tests. |
| Roster sync | Whole roster, versioned | Diffs | A missed message heals at the next one. |
- No end-to-end encryption yet; the derived media key is reserved for it.
- No TURN relay: networks that block UDP get no media.
- No simulcast or forwarding on demand: hidden streams still reach the client.
- Rooms survive a planned handover only, not a crash.
- Not built: recording, transcription, extensions.
Files
- README.mdOverview, install, usage, configuration summary
- docs/architecture.mdComponents, server layout, lv.1, presence, media
- docs/security.mdRoom codes, hardening, what is not built, privacy
- docs/configuration.mdEvery environment variable and the audit CLI
- docs/self-hosting.mdProxy, UDP, handover, sizing
- server/cmd/live/main.goThe binary entry point
- server/app/config.goEnvironment parsing and validation
- server/core/room/room.goThe Room aggregate
- server/service/presence/hub.goThe presence hub
- server/service/presence/actor.goOne goroutine per room
- server/sfuThe Pion media engine
- server/signallv.1 frames, close codes, rate limits
- web/DESIGN.mdClient design rules
- mise.tomlPinned toolchain and the lint, test and check tasks