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

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/StartRoomCompositeEgress \
        -H 'Authorization: Bearer <livekit-access-token>' \
        -H 'Content-Type: application/json' \
        -d '{"room_name": "your-room", "segments": {"filename_prefix": "your-hls-playlist.m3u8", "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"...}

StartRoomCompositeEgress

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

StartTrackCompositeEgress

Starts a new Track Composite

StartTrackEgress

Starts a new Track Egress

StartWebEgress

Starts a new Web Egress

UpdateLayout

Used to change the web layout on an active RoomCompositeEgress.

const info = await egressClient.updateLayout(egressID, 'grid-light');

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.

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

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

ListEgress

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

const res = await egressClient.listEgress();

StopEgress

Stops an active egress.

const info = await egressClient.stopEgress(egressID);

Types

EncodedFileOutput

DirectFileOutput

SegmentedFileOutput

StreamOutput

ImageOutput

S3Upload

GCPUpload

AzureBlobUpload

AliOSSUpload

EncodingOptions

EncodingOptionsPreset

Enum, valid values:

• H264_720P_30: 0
• H264_720P_60: 1
• H264_1080P_30: 2
• H264_1080P_60: 3
• PORTRAIT_H264_720P_30: 4
• PORTRAIT_H264_720P_60: 5
• PORTRAIT_H264_1080P_30: 6
• PORTRAIT_H264_1080P_60: 7

ProxyConfig

For S3 and GCP, you can specify a proxy server for Egress to use when uploading files.

This can be helpful to avoid network restrictions on the destination buckets.