Recording, Egress and E2EE
Recording and streaming through LiveKit Egress, storage and access control, and how E2EE limits them.
Three different protections
| Protection | Protects | Who can see plaintext media | Lynkoria status |
|---|---|---|---|
| Transport encryption | Media and signaling on the network (DTLS-SRTP, TLS) | The SFU (LiveKit) and the endpoints | Always on |
| End-to-end encryption (E2EE) | Media between participants | Only participants holding the key; not LiveKit, not Egress | Clients encrypt with LiveKit E2EE and a product-managed key. Lynkoria records the e2ee flag; it does not distribute keys |
| Encryption at rest | Stored recording files | Anyone with storage access, plus the Egress worker while recording | Storage provider's server-side encryption (DigitalOcean Spaces encrypts at rest); private bucket, short presigned URLs |
A recording is never end-to-end encrypted. Egress must decode media to compose or store it, so it necessarily sees plaintext. Encrypting the stored file protects it at rest; it does not make the recording E2EE.
E2EE policy
- Create the call with
e2ee: truewhen participants will encrypt media. POST /v1/calls/{id}/recordingsreturns 409 for such calls, including RTMP streaming. Lynkoria never silently bypasses E2EE to make recording work.- If a product needs both, the only honest options are: record without E2EE (and say so), or have a participant client that holds the key record locally as a trusted, visible participant. That second option is not implemented.
Recording API (service key, calls:write)
| Call | Purpose |
|---|---|
POST /v1/calls/{id}/recordings | Start: kind room_composite (default), participant or audio_only; outputs mp4, ogg, hls; optional rtmpUrls (room composite only); layout |
GET /v1/calls/{id}/recordings | List a call's recordings |
GET /v1/recordings/{id} | Status: starting, active, ending, complete, failed, aborted, deleted |
POST /v1/recordings/{id}/stop | Stop |
GET /v1/recordings/{id}/download?file=… | 5-minute presigned URL for one output file of a completed recording |
DELETE /v1/recordings/{id} | Delete every stored file |
The product backend decides which of its users may watch and hands them the short-lived URL; recordings are never public. Files live under recordings/<environment>/<call>/<recording>/ in the private Spaces bucket. HLS output writes hls/playlist.m3u8 and 4-second segments; serving HLS to large audiences needs a CDN in front of short-lived signed URLs, which is not set up.
Lifecycle
LiveKit sends egress_started, egress_updated and egress_ended webhooks; Lynkoria updates the ledger, records output files, sizes and durations, and ignores out-of-order transitions out of a finished state. If Egress cannot start, the recording is marked failed and the API returns 503. Finished recordings expire after RECORDING_RETENTION_DAYS (default 30); a worker deletes their files. Metrics: lynkoria_recording_events_total{status}.
Deploying Egress
Egress is a separate LiveKit service (Chrome-based for room composite) that needs its own CPU budget, typically 2–4 vCPU per concurrent 720p composite. It connects to Redis and the LiveKit server and uploads to S3-compatible storage (DigitalOcean Spaces works with path-style off; local RustFS works with path-style on). Set EGRESS_S3_ENDPOINT if Egress reaches storage on a different address.
Verification status
The lifecycle (start, webhook state changes, out-of-order protection, authorized download, deletion, retention, E2EE refusal) is tested with a stubbed Egress client against real PostgreSQL, S3-compatible storage and signed webhooks. No real Egress service has run, and no recording or HLS output has been produced. Egress resource use under load is unmeasured.