Overview
LiveKit Egress gives you a powerful and consistent set of APIs to export any room or individual tracks from a LiveKit session. It supports recording to an MP4 file or HLS segments, as well as exporting to live streaming services like YouTube Live, Twitch, and Facebook via RTMP.
For LiveKit Cloud customers, egress is available for your project without any additional configuration. If you're self-hosting LiveKit, egress must be deployed separately.
Egress sources
Start an egress with StartEgress and set one of three sources, which determines what gets captured. The five source-specific egress APIs they replace are deprecated.
| Source | Description | Use cases |
|---|---|---|
Export an entire room's video and/or audio using a web layout rendered by Chrome. Tied to a room's lifecycle and stops automatically when the room ends. Composition templates are customizable web pages that can be hosted anywhere. Replaces the | Recording meetings for team members to watch later, capturing all participants and interactions in a room. | |
Record and export any web page. Similar to a template source, but isn't tied to a LiveKit room and can record non-LiveKit content. Replaces the | Restreaming content from a third-party source to YouTube and Twitch, recording external web applications. | |
Capture tracks straight from a room through the SDK, with no browser. Select a participant's camera or screen share, or an individual track, and route each participant's audio to a specific channel with Replaces the | Recording individual participants in online classes, exporting specific tracks for post-production, recording an agent and a caller on separate channels. |
By default a media source decodes and re-encodes what it captures. To export a single track without transcoding, set the PASSTHROUGH encoding preset, which writes the track in its native container. It captures one track to one file, so it can't be combined with stream, segment, or image outputs. For a full list of constraints, see StartEgress.
Auto egress is a separate configuration path. It starts recording automatically when a room is created. Configure the egress field in CreateRoom to record the room as a composite and each published track separately, without any manual API call. To learn more, see Auto egress.
Audio-only recordings
Audio-only egress is billed at a lower rate than video, but requires using a source that supports audio-only processing.
There are two options:
- For a single mixed audio file from a room, use a
TemplateSourcewithaudio_only=true. Don't setlayoutorcustom_base_urlas these parameters force the recording through the video pipeline. - To capture participant audio directly (including routing each participant to a separate channel), use a
MediaSourcewithAudioConfigand no video selector.
Using the deprecated source-specific egress APIs, the equivalents are RoomComposite egress with audio_only=true, and Track egress started once per track.
Service architecture
Depending on your request type, the Egress service either launches a web template in Chrome and connects to the room (for example, for room composite requests), or it uses the SDK directly (for track and track composite requests). It uses GStreamer to encode, and can output to a file or to one or more streams.
Server-side subscription management
When egress runs, it joins the room as a participant with kind = EGRESS and subscribes only to the tracks it needs to fulfill the request. For example, a TrackEgress started for an audio track subscribes to that single track. Calling UpdateSubscriptions against an egress participant overrides those subscriptions, so the egress records whatever tracks the API call subscribes it to (for example, video) instead of what was originally requested (that is, audio).
If you have a server-side subscription manager that adjusts subscriptions for participants in a room, filter on ParticipantInfo.kind and skip EGRESS participants. The same applies to other non-human participant kinds your subscription logic doesn't model — typically INGRESS and AGENT.
Additional resources
The following topics provide more in-depth information about the various egress types.
Room composite and web egress
Composite recording using a web-based recorder. Export an entire room or any web page.
Participant and track composite egress
Record a participant's audio and video tracks. Use TrackComposite egress for fine-grained control over tracks.
Track egress
Export a single track without transcoding.
Auto egress
Automatically start recording when a room is created.
Output and stream types
Sync and export one audio and one video track together. Transcoding and multiplexing happen automatically.