Skip to main content

Egress API

Use LiveKit's egress service to record or livestream a Room.

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.

ParameterTypeRequiredDescription
room_namestringyesname of room to record
layoutstringlayout parameter that is passed to the template
audio_onlybooltrue if resulting output should only contain audio
audio_mixingAudioMixingAudio mixing mode to use when audio_only is true. Defaults to DEFAULT_MIXING: All users are mixed together.
video_onlybooltrue if resulting output should only contain video
custom_base_urlstringURL to the page that would composite tracks, uses embedded templates if left blank
file_outputsEncodedFileOutput[]output to MP4 file. currently only supports a single entry
segment_outputsSegmentedFileOutput[]output to HLS segments. currently only supports a single entry
stream_outputsStreamOutput[]output to a stream. currently only supports a single entry, though it could includ multiple destination URLs
image_outputsImageOutput[]output to a succession of snapshot images taken at a given interval (thumbnails). Currently only supports a single entry.
presetEncodingOptionsPresetencoding preset to use. only one of preset or advanced could be set
advancedEncodingOptionsadvanced encoding options. only one of preset or advanced could be set
webhooksWebhookConfig[]extra webhooks to send on egress events for this request

StartTrackCompositeEgress

Starts a new Track Composite

ParameterTypeRequiredDescription
room_namestringyesname of room to record
audio_track_idstringID of audio track to composite
video_track_idstringID of video track to composite
file_outputsEncodedFileOutput[]output to MP4 file. currently only supports a single entry
segment_outputsSegmentedFileOutput[]output to HLS segments. currently only supports a single entry
stream_outputsStreamOutput[]output to a stream. currently only supports a single entry, though it could includ multiple destination URLs
image_outputsImageOutput[]output to a succession of snapshot images taken at a given interval (thumbnails). Currently only supports a single entry.
presetEncodingOptionsPresetencoding preset to use. only one of preset or advanced could be set
advancedEncodingOptionsadvanced encoding options. only one of preset or advanced could be set
webhooksWebhookConfig[]extra webhooks to send on egress events for this request

StartTrackEgress

Starts a new Track Egress

ParameterTypeRequiredDescription
room_namestringyesname of room to record
track_idstringID of track to record
fileDirectFileOutputonly one of file or websocket_url can be set
websocket_urlstringurl to websocket to receive audio output. only one of file or websocket_url can be set
webhooksWebhookConfig[]extra webhooks to send on egress events for this request

StartWebEgress

Starts a new Web Egress

ParameterTypeRequiredDescription
urlstringyesURL of the web page to record
audio_onlybooltrue if resulting output should only contain audio
video_onlybooltrue if resulting output should only contain video
file_outputsEncodedFileOutput[]output to MP4 file. currently only supports a single entry
segment_outputsSegmentedFileOutput[]output to HLS segments. currently only supports a single entry
stream_outputsStreamOutput[]output to a stream. currently only supports a single entry, though it could includ multiple destination URLs
image_outputsImageOutput[]output to a succession of snapshot images taken at a given interval (thumbnails). Currently only supports a single entry.
presetEncodingOptionsPresetencoding preset to use. only one of preset or advanced could be set
advancedEncodingOptionsadvanced encoding options. only one of preset or advanced could be set
webhooksWebhookConfig[]extra webhooks to send on egress events for this request

UpdateLayout

Used to change the web layout on an active RoomCompositeEgress.

ParameterTypeRequiredDescription
egress_idstringyesEgress ID to update
layoutstringyeslayout to update to
const info = await egressClient.updateLayout(egressID, 'grid-light');
info, err := egressClient.UpdateLayout(ctx, &livekit.UpdateLayoutRequest{
EgressId: egressID,
Layout: "grid-light",
})
egressClient.update_layout('egress-id', 'grid-dark')
try {
egressClient.updateLayout("egressId", "grid-light").execute();
} catch (IOException e) {
// handle exception
}
lk egress update-layout --id <EGRESS_ID> --layout speaker

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.

ParameterTypeRequiredDescription
egress_idstringyesEgress ID to update
add_output_urlsstring[]URLs to add to the egress as output destinations
remove_output_urlsstring[]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',
]);
streamRequest := &livekit.RoomCompositeEgressRequest{
RoomName: "my-room",
Layout: "speaker",
Output: &livekit.RoomCompositeEgressRequest_Stream{
Stream: &livekit.StreamOutput{
Protocol: livekit.StreamProtocol_RTMP,
Urls: []string{"rtmp://live.twitch.tv/app/<stream-key>"},
},
},
}
info, err := egressClient.StartRoomCompositeEgress(ctx, streamRequest)
streamEgressID := info.EgressId
info, err = egressClient.UpdateStream(ctx, &livekit.UpdateStreamRequest{
EgressId: streamEgressID,
AddOutputUrls: []string{"rtmp://a.rtmp.youtube.com/live2/<stream-key>"}
})
# to add streams
egressClient.update_stream(
'egress-id',
add_output_urls: ['rtmp://new-url'],
remove_output_urls: ['rtmp://old-url']
)
try {
egressClient.updateStream(
"egressId",
Collections.singletonList("rtmp://new-url"),
Collections.singletonList("rtmp://old-url")
).execute();
} catch (IOException e) {
// handle exception
}
lk update-stream \
--id <EGRESS_ID> \
--add-urls "rtmp://a.rtmp.youtube.com/live2/stream-key"

ListEgress

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

const res = await egressClient.listEgress();
res, err := egressClient.ListEgress(ctx, &livekit.ListEgressRequest{})
# to list egress on myroom
egressClient.list_egress(room_name: 'myroom')
# to list all egresses
egressClient.list_egress()
try {
List<LivekitEgress.EgressInfo> egressInfos = egressClient.listEgress().execute().body();
} catch (IOException e) {
// handle exception
}
lk egress list

StopEgress

Stops an active egress.

const info = await egressClient.stopEgress(egressID);
info, err := egressClient.StopEgress(ctx, &livekit.StopEgressRequest{
EgressId: egressID,
})
egressClient.stop_egress('egress-id')
try {
egressClient.stopEgress("egressId").execute();
} catch (IOException e) {
// handle exception
}
lk egress stop --id <EGRESS_ID>

Types

The Egress service includes the following types.

ListEgressResponse

FieldTypeDescription
itemsarray<EgressInfo>List of egress endpoints.

EgressInfo

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

FieldTypeDescription
egress_idstringUnique egress ID.
room_idstringRoom ID.
room_namestringRoom name.
source_typeEgressSourceTypeWhether the egress was started from web or SDK.
statusEgressStatusCurrent egress status.
started_atint64When the egress started.
ended_atint64When the egress ended.
updated_atint64Last update timestamp.
detailsstringAdditional status details.
errorstringError message, if any.
error_codeint32Error code, if any.
requestRoomCompositeEgressRequest | WebEgressRequest | ParticipantEgressRequest | TrackCompositeEgressRequest | TrackEgressRequestThe request that started this egress.
stream_resultsarray<StreamInfo>Results per stream output.
file_resultsarray<FileInfo>Results per file output.
segment_resultsarray<SegmentsInfo>Results per segmented output.
image_resultsarray<ImagesInfo>Results per image output.
manifest_locationstringLocation of the manifest file, if applicable.
backup_storage_usedboolWhether backup storage was used.

EgressStatus

Enum. Egress lifecycle status:

NameValueDescription
EGRESS_STARTING0Egress is starting.
EGRESS_ACTIVE1Egress is active and recording or streaming.
EGRESS_ENDING2Egress is shutting down.
EGRESS_COMPLETE3Egress completed successfully.
EGRESS_FAILED4Egress failed.
EGRESS_ABORTED5Egress was aborted.
EGRESS_LIMIT_REACHED6Egress limit was reached.

EgressSourceType

Enum. Source of the egress:

NameValueDescription
EGRESS_SOURCE_TYPE_WEB0Started from the web (e.g. Cloud dashboard).
EGRESS_SOURCE_TYPE_SDK1Started from the SDK or API.

StreamInfo

Per-stream output result.

FieldTypeDescription
urlstringStream URL.
started_atint64When the stream started.
ended_atint64When the stream ended.
durationint64Duration in nanoseconds.
statusStreamInfo.StatusStream status.
errorstringError message, if any.
last_retry_atint64Last retry timestamp.
retriesuint32Number of retries.

StreamInfo.Status

Enum. Stream output status:

NameValueDescription
ACTIVE0Stream is active.
FINISHED1Stream finished.
FAILED2Stream failed.

FileInfo

Per-file output result.

FieldTypeDescription
filenamestringOutput filename.
started_atint64When the file recording started.
ended_atint64When the file recording ended.
durationint64Duration in nanoseconds.
sizeint64File size in bytes.
locationstringStorage location (e.g. S3 URL).

SegmentsInfo

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

FieldTypeDescription
playlist_namestringPlaylist filename.
live_playlist_namestringLive playlist path, if configured.
durationint64Total duration in nanoseconds.
sizeint64Total size in bytes.
playlist_locationstringPlaylist storage location.
live_playlist_locationstringLive playlist storage location.
segment_countint64Number of segments.
started_atint64When the recording started.
ended_atint64When the recording ended.

ImagesInfo

Per-image-output result.

FieldTypeDescription
filename_prefixstringPrefix used for image filenames.
image_countint64Number of images captured.
started_atint64When capture started.
ended_atint64When capture ended.

AudioMixing

Enum. Audio mixing mode when recording audio only:

NameValueDescription
DEFAULT_MIXING0All users are mixed together.
DUAL_CHANNEL_AGENT1Agent audio in the left channel, all other audio in the right channel.
DUAL_CHANNEL_ALTERNATE2Each new audio track alternates between left and right channels.

EncodedFileType

Enum. Encoded file format:

NameValueDescription
DEFAULT_FILETYPE0File type chosen based on codecs.
MP41MP4 container.
OGG2OGG container.
MP33MP3 audio.

EncodedFileOutput

FieldTypeDescription
file_typeEncodedFileTypeOptional. Output file type. Default chosen from codecs.
filepathstringOutput path. See egress docs for templating. Default {room_name}-{time}.
disable_manifestboolIf true, do not upload manifest file. Default false.
s3S3UploadS3-compatible storage. Only one storage output.
gcpGCPUploadGoogle Cloud Storage. Only one storage output.
azureAzureBlobUploadAzure Blob Storage. Only one storage output.
aliOSSAliOSSUploadAlibaba Cloud OSS. Only one storage output.

DirectFileOutput

FieldTypeDescription
filepathstringOutput path. See egress docs for templating. Default {track_id}-{time}.
disable_manifestboolIf true, do not upload manifest file. Default false.
s3S3UploadS3-compatible storage. Only one storage output.
gcpGCPUploadGoogle Cloud Storage. Only one storage output.
azureAzureBlobUploadAzure Blob Storage. Only one storage output.
aliOSSAliOSSUploadAlibaba Cloud OSS. Only one storage output.

SegmentedFileProtocol

Enum. Segmented output protocol:

NameValueDescription
DEFAULT_SEGMENTED_FILE_PROTOCOL0Protocol chosen by server.
HLS_PROTOCOL1HLS.

SegmentedFileSuffix

Enum. Suffix for segment filenames:

NameValueDescription
INDEX0Numeric index (1, 2, 3, ...).
TIMESTAMP1UTC timestamp.

SegmentedFileOutput

FieldTypeDescription
protocolSegmentedFileProtocolOptional. Segmented protocol. Default chosen by server.
filename_prefixstringOptional. Prefix for each segment (include paths here).
playlist_namestringOptional. Name of the m3u8 playlist. When empty, matches filename_prefix.
live_playlist_namestringOptional. Path for a live playlist. Omitted if not set.
segment_durationuint32Segment length in seconds. Optional.
filename_suffixSegmentedFileSuffixOptional. INDEX or TIMESTAMP. Default INDEX.
disable_manifestboolIf true, do not upload manifest file. Default false.
s3S3UploadS3-compatible storage. Only one storage output.
gcpGCPUploadGoogle Cloud Storage. Only one storage output.
azureAzureBlobUploadAzure Blob Storage. Only one storage output.
aliOSSAliOSSUploadAlibaba Cloud OSS. Only one storage output.

StreamProtocol

Enum. Stream output protocol:

NameValueDescription
DEFAULT_PROTOCOL0Protocol chosen from URLs.
RTMP1RTMP.
SRT2SRT.

StreamOutput

FieldTypeDescription
protocolStreamProtocolRequired. Stream protocol (e.g. RTMP).
urlsarray<string>Required. Destination URLs.

ImageFileSuffix

Enum. Suffix for image filenames:

NameValueDescription
IMAGE_SUFFIX_INDEX0Numeric index (1, 2, 3, ...).
IMAGE_SUFFIX_TIMESTAMP1Timestamp.
IMAGE_SUFFIX_NONE_OVERWRITE2No suffix; overwrite the same file with the latest image.

ImageOutput

FieldTypeDescription
capture_intervaluint32Required. Seconds between each snapshot.
widthint32Optional. Image width. Defaults to track width.
heightint32Optional. Image height. Defaults to track height.
filename_prefixstringOptional. Prefix for each image filename (include paths here).
filename_suffixImageFileSuffixOptional. INDEX, TIMESTAMP, or NONE_OVERWRITE. Default INDEX.
image_codecImageCodecOptional. Image codec (e.g. JPEG).
disable_manifestboolIf true, do not upload manifest file. Default false.
s3S3UploadS3-compatible storage. Only one storage output.
gcpGCPUploadGoogle Cloud Storage. Only one storage output.
azureAzureBlobUploadAzure Blob Storage. Only one storage output.
aliOSSAliOSSUploadAlibaba Cloud OSS. Only one storage output.

S3Upload

FieldTypeDescription
access_keystringS3 access key.
secretstringS3 secret key.
session_tokenstringOptional. Session token for temporary credentials.
assume_role_arnstringOptional. ARN of role to assume for upload (LiveKit Cloud feature when enabled).
assume_role_external_idstringOptional. External ID for assume role.
regionstringBucket region. Optional.
endpointstringCustom S3 endpoint URL. Optional.
bucketstringDestination bucket.
force_path_styleboolIf true, keep bucket in path (no subdomain). Optional.
metadatamap<string, string>Metadata key-value pairs. Optional.
taggingstringS3 object tagging. Optional.
content_dispositionstringContent-Disposition header. Optional.
proxyProxyConfigProxy for uploads. Optional.

GCPUpload

FieldTypeDescription
credentialsstringService account credentials JSON (credentials.json).
bucketstringDestination bucket.
proxyProxyConfigProxy for uploads. Optional.

AzureBlobUpload

FieldTypeDescription
account_namestringAzure storage account name.
account_keystringAzure storage account key.
container_namestringDestination container.

AliOSSUpload

FieldTypeDescription
access_keystringAlibaba Cloud access key.
secretstringAlibaba Cloud secret key.
regionstringBucket region.
endpointstringCustom endpoint URL. Optional.
bucketstringDestination bucket.

EncodingOptions

FieldTypeDescription
widthint32Output width. Default 1920.
heightint32Output height. Default 1080.
depthint32Color depth. Default 24.
framerateint32Frame rate. Default 30.
audio_codecAudioCodecAudio codec. Default OPUS.
audio_bitrateint32Audio bitrate in kbps. Default 128.
audio_qualityint32Audio encoder quality setting. Optional.
audio_frequencyint32Sample rate in Hz. Default 44100.
video_codecVideoCodecVideo codec. Default H264_MAIN.
video_bitrateint32Video bitrate in kbps. Default 4500.
video_qualityint32Video encoder quality setting. Optional.
key_frame_intervaldoubleKey frame interval in seconds. Default 4 for streaming; segment duration for segmented output; encoder default for files.

EncodingOptionsPreset

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

NameValueDescription
H264_720P_3001280×720, 30 fps, 3000 kbps.
H264_720P_6011280×720, 60 fps, 4500 kbps.
H264_1080P_3021920×1080, 30 fps, 4500 kbps.
H264_1080P_6031920×1080, 60 fps, 6000 kbps.
PORTRAIT_H264_720P_304720×1280, 30 fps, 3000 kbps.
PORTRAIT_H264_720P_605720×1280, 60 fps, 4500 kbps.
PORTRAIT_H264_1080P_3061080×1920, 30 fps, 4500 kbps.
PORTRAIT_H264_1080P_6071080×1920, 60 fps, 6000 kbps.

ProxyConfig

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

FieldTypeDescription
urlstringProxy URL.
usernamestringUsername for basic auth. Optional.
passwordstringPassword for basic auth. Optional.

WebhookConfig

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

FieldTypeDescription
urlstringWebhook URL.
signing_keystringAPI key to sign the request. Must be defined for the project.