Skip to Content
LYNKORIADocs

Recording, Egress and E2EE

Recording and streaming through LiveKit Egress, storage and access control, and how E2EE limits them.

Three different protections

ProtectionProtectsWho can see plaintext mediaLynkoria status
Transport encryptionMedia and signaling on the network (DTLS-SRTP, TLS)The SFU (LiveKit) and the endpointsAlways on
End-to-end encryption (E2EE)Media between participantsOnly participants holding the key; not LiveKit, not EgressClients encrypt with LiveKit E2EE and a product-managed key. Lynkoria records the e2ee flag; it does not distribute keys
Encryption at restStored recording filesAnyone with storage access, plus the Egress worker while recordingStorage 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: true when participants will encrypt media.
  • POST /v1/calls/{id}/recordings returns 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)

CallPurpose
POST /v1/calls/{id}/recordingsStart: kind room_composite (default), participant or audio_only; outputs mp4, ogg, hls; optional rtmpUrls (room composite only); layout
GET /v1/calls/{id}/recordingsList a call's recordings
GET /v1/recordings/{id}Status: starting, active, ending, complete, failed, aborted, deleted
POST /v1/recordings/{id}/stopStop
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.

On this page