Egress API

API

The Egress API is available within our server SDKs and CLI:

• Go Egress Client 
• JS Egress Client
• Ruby Egress Client 
• Python Egress Client
• Java Egress Client 
• CLI 

Start every new egress with StartEgress, which takes one source (a layout template, a web page, or tracks from a room) and one or more outputs. The five source-specific egress APIs it replaces are deprecated.

You can also use curl to interact with the Egress APIs. To do so, POST the arguments in JSON format to:

https://<your-livekit-host>/twirp/livekit.Egress/<MethodName>

For example:

% curl -X POST https://<your-livekit-host>/twirp/livekit.Egress/StartEgress \
        -H 'Authorization: Bearer <livekit-access-token>' \
        -H 'Content-Type: application/json' \
        -d '{"room_name": "your-room", "template": {"layout": "grid"}, "outputs": [{"segments": {"filename_prefix": "your-hls-playlist", "playlist_name": "your-hls-playlist.m3u8"}}], "storage": {"s3": {"access_key": "<key>", "secret": "<secret>", "bucket": "<bucket>", "region": "<bucket-region>"}}}'

{"egress_id":"EG_MU4QwhXUhWf9","room_id":"<room-id>","room_name":"your-room","status":"EGRESS_STARTING"...}

StartEgress

Starts an egress. Configure a source and one or more outputs: the source determines what is captured, and the outputs determine where it is sent. It replaces the five source-specific egress APIs below.

Each deprecated API can be replaced with StartEgress using a specific source type:

By default a MediaSource decodes and re-encodes what it captures. To export a track without transcoding, as StartTrackEgress did, set preset to PASSTHROUGH. Egress then writes the track in its native container and skips codec negotiation entirely.

Passthrough captures exactly one track to one file, so it has its own constraints:

• The source must be a MediaSource. Template and web sources are rejected.
• Select exactly one track by ID: either video_track_id or a single AudioRoute matching on track_id. Selecting both or neither is rejected, as are participant_video, capture_all, more than one route, and routes matching on identity or kind.
• Give exactly one output, and it must be a FileOutput. Stream, segment, and image outputs are rejected.
• Leave file_type unset. Egress picks the container from the codec of the track, and an explicit type is rejected.

The StartTrackEgress API also streams raw audio to a websocket_url. To do this with StartEgress, use a StreamOutput with the WEBSOCKET protocol. Note that this transcodes, since passthrough and stream outputs can't be combined.

StartRoomCompositeEgress (deprecated)

Starts a new Composite Recording using a web browser as the rendering engine.

StartParticipantEgress (deprecated)

Starts a new Participant Egress.

StartTrackCompositeEgress (deprecated)

Starts a new Track Composite.

StartTrackEgress (deprecated)

Starts a new Track Egress.

StartWebEgress (deprecated)

Starts a new Web Egress.

UpdateLayout

Used to change the web layout on an active RoomCompositeEgress.

lk egress update-layout --id <EGRESS_ID> --layout speaker

import { LiveKitAPI } from 'livekit-server-sdk';

const api = new LiveKitAPI();
const info = await api.egress.updateLayout(egressId, 'grid-light');

from livekit import api

async with api.LiveKitAPI() as lkapi:
    info = await lkapi.egress.update_layout(
        api.UpdateLayoutRequest(egress_id=egress_id, layout="grid-light")
    )

require 'livekit'

lkapi = LiveKit::LiveKitAPI.new
lkapi.egress.update_layout(egress_id, 'grid-light')

import lksdk "github.com/livekit/server-sdk-go/v2"

api, err := lksdk.NewLiveKitAPI()
info, err := api.Egress().UpdateLayout(ctx, &livekit.UpdateLayoutRequest{
    EgressId: egressID,
    Layout:   "grid-light",
})

import io.livekit.server.LiveKitAPI

val api = LiveKitAPI.createClient(host, apiKey, secret)
val info = api.egress.updateLayout(egressId, "grid-light").execute().body()

use livekit_api::services::LiveKitApi;

let api = LiveKitApi::with_api_key(host, api_key, api_secret);
let info = api.egress().update_layout(egress_id, "grid-light").await?;

UpdateStream

Used to add or remove stream URLs from an active stream.

Note: you can only add outputs to an Egress that was started with stream_outputs set.

lk egress update-stream \
  --id <EGRESS_ID> \
  --add-urls "rtmp://a.rtmp.youtube.com/live2/stream-key"

import { LiveKitAPI, StreamOutput, StreamProtocol } from 'livekit-server-sdk';

const api = new LiveKitAPI();
const streamOutput = new StreamOutput({
  protocol: StreamProtocol.RTMP,
  urls: ['rtmp://live.twitch.tv/app/<stream-key>'],
});
let info = await api.egress.startRoomCompositeEgress('my-room', { stream: streamOutput });
const streamEgressId = info.egressId;

info = await api.egress.updateStream(streamEgressId, [
  'rtmp://a.rtmp.youtube.com/live2/stream-key',
]);

from livekit import api

async with api.LiveKitAPI() as lkapi:
    info = await lkapi.egress.start_room_composite_egress(
        api.RoomCompositeEgressRequest(
            room_name="my-room",
            layout="speaker",
            stream_outputs=[api.StreamOutput(
                protocol=api.StreamProtocol.RTMP,
                urls=["rtmp://live.twitch.tv/app/<stream-key>"],
            )],
        )
    )

    info = await lkapi.egress.update_stream(
        api.UpdateStreamRequest(
            egress_id=info.egress_id,
            add_output_urls=["rtmp://a.rtmp.youtube.com/live2/stream-key"],
        )
    )

require 'livekit'

lkapi = LiveKit::LiveKitAPI.new

# to add and remove streams
lkapi.egress.update_stream(
  'egress-id',
  add_output_urls: ['rtmp://new-url'],
  remove_output_urls: ['rtmp://old-url']
)

import lksdk "github.com/livekit/server-sdk-go/v2"

api, err := lksdk.NewLiveKitAPI()

streamRequest := &livekit.RoomCompositeEgressRequest{
    RoomName: "my-room",
    Layout:   "speaker",
    StreamOutputs: []*livekit.StreamOutput{{
        Protocol: livekit.StreamProtocol_RTMP,
        Urls:     []string{"rtmp://live.twitch.tv/app/<stream-key>"},
    }},
}

info, err := api.Egress().StartRoomCompositeEgress(ctx, streamRequest)
streamEgressID := info.EgressId

info, err = api.Egress().UpdateStream(ctx, &livekit.UpdateStreamRequest{
    EgressId:      streamEgressID,
    AddOutputUrls: []string{"rtmp://a.rtmp.youtube.com/live2/stream-key"},
})

import io.livekit.server.LiveKitAPI

val api = LiveKitAPI.createClient(host, apiKey, secret)
val info = api.egress.updateStream(
    "egressId",
    listOf("rtmp://new-url"),
    listOf("rtmp://old-url"),
).execute().body()

use livekit_api::services::LiveKitApi;

let api = LiveKitApi::with_api_key(host, api_key, api_secret);
let info = api
    .egress()
    .update_stream(
        "egress-id",
        vec!["rtmp://new-url".to_string()],
        vec!["rtmp://old-url".to_string()],
    )
    .await?;

ListEgress

Used to list active egress. Does not include completed egress.

lk egress list

import { LiveKitAPI } from 'livekit-server-sdk';

const api = new LiveKitAPI();
const res = await api.egress.listEgress();

from livekit import api

async with api.LiveKitAPI() as lkapi:
    res = await lkapi.egress.list_egress(api.ListEgressRequest())

require 'livekit'

lkapi = LiveKit::LiveKitAPI.new

# to list egress on myroom
lkapi.egress.list_egress(room_name: 'myroom')

# to list all egresses
lkapi.egress.list_egress

import lksdk "github.com/livekit/server-sdk-go/v2"

api, err := lksdk.NewLiveKitAPI()
res, err := api.Egress().ListEgress(ctx, &livekit.ListEgressRequest{})

import io.livekit.server.LiveKitAPI

val api = LiveKitAPI.createClient(host, apiKey, secret)
val egressInfos = api.egress.listEgress().execute().body()

use livekit_api::services::{egress::EgressListOptions, LiveKitApi};

let api = LiveKitApi::with_api_key(host, api_key, api_secret);
let res = api.egress().list_egress(EgressListOptions::default()).await?;

StopEgress

Stops an active egress.

lk egress stop --id <EGRESS_ID>

import { LiveKitAPI } from 'livekit-server-sdk';

const api = new LiveKitAPI();
const info = await api.egress.stopEgress(egressId);

from livekit import api

async with api.LiveKitAPI() as lkapi:
    info = await lkapi.egress.stop_egress(
        api.StopEgressRequest(egress_id=egress_id)
    )

require 'livekit'

lkapi = LiveKit::LiveKitAPI.new
lkapi.egress.stop_egress('egress-id')

import lksdk "github.com/livekit/server-sdk-go/v2"

api, err := lksdk.NewLiveKitAPI()
info, err := api.Egress().StopEgress(ctx, &livekit.StopEgressRequest{
    EgressId: egressID,
})

import io.livekit.server.LiveKitAPI

val api = LiveKitAPI.createClient(host, apiKey, secret)
val info = api.egress.stopEgress("egressId").execute().body()

use livekit_api::services::LiveKitApi;

let api = LiveKitApi::with_api_key(host, api_key, api_secret);
let info = api.egress().stop_egress("egress-id").await?;

Types

The Egress service includes the following types.

ListEgressResponse

EgressInfo

Returned by start, update, list, and stop operations. Describes the egress and its status.

EgressStatus

Enum. Egress lifecycle status:

EgressSourceType

Enum. Source of the egress:

StreamInfo

Per-stream output result.

StreamInfo.Status

Enum. Stream output status:

FileInfo

Per-file output result.

SegmentsInfo

Per-segmented-output result (e.g. HLS).

ImagesInfo

Per-image-output result.

TemplateSource

Composites a room using a layout template rendered in a headless browser. The service generates a token, builds the recorder URL, and waits for the template to signal that it's ready.

To get the audio-only billing rate , set audio_only and leave both layout and custom_base_url empty. Those three conditions together let the service capture the room directly instead of starting a browser.

WebSource

Records any URL in a headless browser. Unlike TemplateSource, it isn't tied to a room, so it can record content that isn't a LiveKit session.

MediaSource

Captures tracks directly from a room through the SDK, with no browser. Unifies the deprecated Participant, TrackComposite, and Track egress requests.

Omit audio to capture video only, or omit the video selector to capture audio only. A request that selects neither fails.

ParticipantVideo

Selects one participant's video track.

AudioConfig

Selects which audio to capture and routes it to output channels.

Routes are evaluated in order and the first match wins, so list the most specific matches first. A track matched by a route is captured and mixed into the channel that route specifies. A track no route matches is captured only when capture_all is set, and then lands in both channels.

To record an agent and a caller on separate channels, route the agent to the left channel and standard participants to the right. This replaces the deprecated AudioMixing modes: DEFAULT_MIXING is equivalent to setting capture_all alone, while dual-channel recording becomes explicit routes. StartEgress has no equivalent of DUAL_CHANNEL_ALTERNATE, which assigned channels in subscription order at runtime. Assign channels per participant or per track instead.

AudioRoute

Matches audio and assigns it to a channel.

AudioChannel

Enum. Output channel for matched audio:

AudioMixing

Enum. Audio mixing mode when recording audio only:

Output

One output destination. Every StartEgress request needs at least one.

Behavior

Output handling follows a few rules:

• A request can combine one file output, one stream output, one segment output, and any number of image outputs. Egress transcodes once and writes to all of them. Requesting two of the same kind fails, except for images.
• A WebSocket stream output carries audio only. If the request also selects video, Egress drops the video and streams the audio rather than returning an error.
• An image-only request records video only, and its audio is ignored.

FileOutput

Records to a single file. Replaces the deprecated EncodedFileOutput and DirectFileOutput. Unlike those, it carries no storage fields of its own: set storage with StorageConfig on the output or on the request.

EncodedFileType

Enum. Encoded file format:

EncodedFileOutput

DirectFileOutput

SegmentedFileProtocol

Enum. Segmented output protocol:

SegmentedFileSuffix

Enum. Suffix for segment filenames:

SegmentedFileOutput

StreamProtocol

Enum. Stream output protocol:

StreamOutput

ImageFileSuffix

Enum. Suffix for image filenames:

ImageOutput

StorageConfig

Specifies where Egress stores output files. Set it on a StartEgress request to apply the same storage configuration to every output, or on an individual Output to override the request-level configuration.

Egress resolves storage in three steps and uses the first one set: the storage set on the output, then the storage set on the request, then the storage configured on the server. On LiveKit Cloud, local storage isn't available, so a request that resolves to no storage fails.

The deprecated source-specific requests, along with SegmentedFileOutput and ImageOutput, still take s3, gcp, azure, and aliOSS fields directly. Those fields are deprecated. Use StorageConfig instead.

S3Upload

GCPUpload

AzureBlobUpload

AliOSSUpload

EncodingOptions

EncodingOptionsPreset

Enum. Encoding presets (H.264_MAIN / OPUS unless noted):

ProxyConfig

Proxy server for uploads (S3 and GCP). Use to work around network restrictions to destination buckets.

WebhookConfig

Extra webhooks for a specific egress request. Called for egress lifecycle events in addition to project webhooks. See Webhooks.