LiveKit Logo

docs

Github

Guides / Egress

Egress

Record or stream your LiveKit rooms

How it works

Depending on your request type, the egress service will either launch a web template in Chrome and connect to the room (room composite requests), or it will use the sdk directly (track and track composite requests). It uses GStreamer to encode, and can output to a file or to one or more streams.

Egress instance

Egress Types

Room Composite Egress

Export an entire room's video and/or audio using a web layout rendered by chrome. Always transcoded.

Example use case: recording a meeting for team members to watch later.

Track Composite Egress

Sync and export up to one audio and one video track. Will transcode and mux.

Example use case: exporting audio+video from many cameras at once during a production, for use in additional post-production.

Track Egress

Export individual tracks directly. Video tracks are not transcoded.

Example use case: streaming an audio track to a captioning service via websocket.

Supported Output

Egress TypeMP4 FileOGG FileIVF FileRtmp(s) StreamWebsocket Stream
Room Composite
Track Composite
Track

Files can be uploaded to any S3 compatible storage, Azure, or GCP.

API

All RPC definitions and options can be found here.

Egress service requires roomRecord permissions in Access Tokens

The Egress API exists within our server SDKs and CLI

The API is part of LiveKit Server, which uses redis to communicate with the Egress service.

StartRoomCompositeEgress

Starts a room composite egress (uses a web template).

const egressClient = new EgressClient(
'https://my-livekit-host',
'livekit-api-key',
'livekit-api-secret'
);
const output = {
fileType: EncodedFileType.MP4,
filepath: 'livekit-demo/room-composite-test.mp4',
s3: {
accessKey: 'aws-access-key',
secret: 'aws-access-secret',
region: 'aws-region',
bucket: 'my-bucket'
}
};
const info = await egressClient.startRoomCompositeEgress('my-room', 'speaker-dark', output);
const egressID = info.egressId;
  • fileRequest.Output.File.Output can be left empty if one of s3, azure, or gcp is supplied with your config (see below).
  • fileRequest.Output.File.Filepath can be left empty, and a unique filename will be generated based on the date and room name.
Layouts

Built-in layouts include speaker-dark, speaker-light, grid-dark, and grid-light.

You can also build your own layouts. You likely already have a room UI built with LiveKit web SDKs - the recording UI can be similar to your existing room UI, with a few differences:

  • Do not render the local participant - in this case, the local participant will be the recorder instance
  • Token permissions - the recorder should have canSubscribe and hidden set to true
  • Room controls (mute, leave, etc) should not be visible

Source code to our default room templates can be found here, and the Template SDK for building your own templates can be found here.

StartTrackCompositeEgress

Starts a track composite egress with up to one audio track and one video track. Track IDs can be found using webhooks or one of the server SDKs.

const output = {
fileType: EncodedFileType.MP4,
filepath: 'livekit-demo/track-composite-test.mp4',
s3: {
accessKey: 'aws-access-key',
secret: 'aws-access-secret',
region: 'aws-region',
bucket: 'my-bucket'
}
};
const info = await egressClient.startTrackCompositeEgress('my-room', output, audioTrackID, videoTrackID);
const egressID = info.egressId;

StartTrackEgress

Starts a track egress. Track ID can be found using webhooks or one of the server SDKs.

const output = {
fileType: EncodedFileType.MP4,
filepath: 'livekit-demo/track-test.mp4',
s3: {
accessKey: 'aws-access-key',
secret: 'aws-access-secret',
region: 'aws-region',
bucket: 'my-bucket'
}
};
const info = await egressClient.startTrackEgress('my-room', trackID, output);
const egressID = info.egressId;

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 or remove outputs from a stream (RTMP output instead of filepath).

const output = {
protocol: StreamProtocol.RTMP,
urls: ['rtmp://live.twitch.tv/app/<stream-key>']
};
var info = await egressClient.startRoomCompositeEgress('my-room', 'speaker-dark', output);
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);

Deployment

See the deployment docs for more info on deployment, config, and autoscaling.

On this page

How it works

Egress Types

Room Composite Egress

Track Composite Egress

Track Egress

Supported Output

API

StartRoomCompositeEgress

Layouts

StartTrackCompositeEgress

StartTrackEgress

UpdateLayout

UpdateStream

ListEgress

StopEgress

Deployment