Egress API | LiveKit Docs

API

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

important:

Requests to the Egress API need the roomRecord permission on the access token.

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"...}

tip:

All RPC definitions and options can be found here.

StartRoomCompositeEgress

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

Parameter	Type	Required	Description
room_name	string	yes	name of room to record
layout	string		layout parameter that is passed to the template
audio_only	bool		true if resulting output should only contain audio
video_only	bool		true if resulting output should only contain video
custom_base_url	string		URL to the page that would composite tracks, uses embedded templates if left blank
file_outputs	EncodedFileOutput[]		output to MP4 file. currently only supports a single entry
segment_outputs	SegmentedFileOutput[]		output to HLS segments. currently only supports a single entry
stream_outputs	StreamOutput[]		output to a stream. currently only supports a single entry, though it could includ multiple destination URLs
image_outputs	ImageOutput[]		output to a succession of snapshot images taken at a given interval (thumbnails). Currently only supports a single entry.
preset	EncodingOptionsPreset		encoding preset to use. only one of preset or advanced could be set
advanced	EncodingOptions		advanced encoding options. only one of preset or advanced could be set

StartTrackCompositeEgress

Starts a new Track Composite

Parameter	Type	Required	Description
room_name	string	yes	name of room to record
audio_track_id	string		ID of audio track to composite
video_track_id	string		ID of video track to composite
file_outputs	EncodedFileOutput[]		output to MP4 file. currently only supports a single entry
segment_outputs	SegmentedFileOutput[]		output to HLS segments. currently only supports a single entry
stream_outputs	StreamOutput[]		output to a stream. currently only supports a single entry, though it could includ multiple destination URLs
image_outputs	ImageOutput[]		output to a succession of snapshot images taken at a given interval (thumbnails). Currently only supports a single entry.
preset	EncodingOptionsPreset		encoding preset to use. only one of preset or advanced could be set
advanced	EncodingOptions		advanced encoding options. only one of preset or advanced could be set

StartTrackEgress

Starts a new Track Egress

Parameter	Type	Required	Description
room_name	string	yes	name of room to record
track_id	string		layout parameter that is passed to the template
file	DirectFileOutput		only one of file or websocket_url can be set
websocket_url	string		url to websocket to receive audio output. only one of file or websocket_url can be set

StartWebEgress

Starts a new Web Egress

Parameter	Type	Required	Description
url	string	yes	URL of the web page to record
audio_only	bool		true if resulting output should only contain audio
video_only	bool		true if resulting output should only contain video
file_outputs	EncodedFileOutput[]		output to MP4 file. currently only supports a single entry
segment_outputs	SegmentedFileOutput[]		output to HLS segments. currently only supports a single entry
stream_outputs	StreamOutput[]		output to a stream. currently only supports a single entry, though it could includ multiple destination URLs
image_outputs	ImageOutput[]		output to a succession of snapshot images taken at a given interval (thumbnails). Currently only supports a single entry.
preset	EncodingOptionsPreset		encoding preset to use. only one of preset or advanced could be set
advanced	EncodingOptions		advanced encoding options. only one of preset or advanced could be set

UpdateLayout

Used to change the web layout on an active RoomCompositeEgress.

Parameter	Type	Required	Description
egress_id	string	yes	Egress ID to update
layout	string	yes	layout to update to

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.

Parameter	Type	Required	Description
egress_id	string	yes	Egress ID to update
add_output_urls	string[]		URLs to add to the egress as output destinations
remove_output_urls	string[]		URLs to remove from the egress

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

Field	Type	Description
filepath	string	default {room_name}-{time}
disable_manifest	bool	by default, Egress outputs a {filepath}.json with metadata of the file
s3	S3Upload	set if uploading to S3 compatible storage. only one storage output can be set
gcp	GCPUpload	set if uploading to GCP
azure	AzureBlobUpload	set if uploading to Azure
aliOSS	AliOSSUpload	set if uploading to AliOSS

DirectFileOutput

Field	Type	Description
filepath	string	default {track_id}-{time}
disable_manifest	bool	by default, Egress outputs a {filepath}.json with metadata of the file
s3	S3Upload	set if uploading to S3 compatible storage. only one storage output can be set
gcp	GCPUpload	set if uploading to GCP
azure	AzureBlobUpload	set if uploading to Azure
aliOSS	AliOSSUpload	set if uploading to AliOSS

SegmentedFileOutput

Field	Type	Description
filename_prefix	string	prefix used in each segment (include any paths here)
playlist_name	string	name of the m3u8 playlist. when empty, matches filename_prefix
segment_duration	uint32	length of each segment (defaults to 4s)
filename_suffix	SegmentedFileSuffix	INDEX (1, 2, 3) or TIMESTAMP (in UTC)
disable_manifest	bool
s3	S3Upload	set if uploading to S3 compatible storage. only one storage output can be set
gcp	GCPUpload	set if uploading to GCP
azure	AzureBlobUpload	set if uploading to Azure
aliOSS	AliOSSUpload	set if uploading to AliOSS

StreamOutput

Field	Type	Description
protocol	SreamProtocol	(optional) only RTMP is supported
urls	string[]	list of URLs to send stream to

ImageOutput

Field	Type	Description
capture_interval	uint32	time in seconds between each snapshot
width	int32	width of the snapshot images (optional, the original width will be used if not provided)
height	int32	height of the snapshot images (optional, the original width will be used if not provided)
filename_prefix	string	prefix used in each image filename (include any paths here)
filename_suffix	ImageFileSuffix	INDEX (1, 2, 3) or TIMESTAMP (in UTC)
image_codec	ImageCodec	IC_DEFAULT or IC_JPEG (optional, both options will cause JPEGs to be generated currently)
disable_manifest	bool	by default, Egress outputs a {filepath}.json with a list of exported snapshots
s3	S3Upload	set if uploading to S3 compatible storage. only one storage output can be set
gcp	GCPUpload	set if uploading to GCP
azure	AzureBlobUpload	set if uploading to Azure
aliOSS	AliOSSUpload	set if uploading to AliOSS

S3Upload

Field	Type	Description
access_key	string
secret	string	S3 secret key
bucket	string	destination bucket
region	string	region of the S3 bucket (optional)
endpoint	string	URL to use for S3 (optional)
force_path_style	bool	leave bucket in the path and never to sub-domain (optional)
metadata	map<string, string>	metadata key/value pairs to store (optional)
tagging	string	(optional)
proxy	ProxyConfig	Proxy server to use when uploading(optional)

GCPUpload

Field	Type	Description
credentials	string	Contents of credentials.json
bucket	string	destination bucket
proxy	ProxyConfig	Proxy server to use when uploading(optional)

AzureBlobUpload

Field	Type	Description
account_name	string
account_key	string
container_name	string	destination container

AliOSSUpload

Field	Type	Description
access_key	string
secret	string
bucket	string
region	string
endpoint	string

EncodingOptions

Field	Type	Description
width	int32
height	int32
depth	int32	default 24
framerate	int32	default 30
audio_codec	AudioCodec	default AAC
audio_bitrate	int32	128
audio_frequency	int32	44100
video_codec	VideoCodec	default H264_MAIN
video_bitrate	int32	default 4500
key_frame_interval	int32	default 4s

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.

Field	Type	Description
url	string	URL of the proxy
username	string	username for basic auth (optional)
password	string	password for basic auth (optional)