API
The Egress API is available within our server SDKs and CLI:
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"...}
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 | |
audio_mixing | AudioMixing | Audio mixing mode to use when audio_only is true. Defaults to DEFAULT_MIXING: All users are mixed together. | |
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 | |
webhooks | WebhookConfig[] | extra webhooks to send on egress events for this request |
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 | |
webhooks | WebhookConfig[] | extra webhooks to send on egress events for this request |
StartTrackEgress
Starts a new Track Egress
| Parameter | Type | Required | Description |
|---|---|---|---|
room_name | string | yes | name of room to record |
track_id | string | ID of track to record | |
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 | |
webhooks | WebhookConfig[] | extra webhooks to send on egress events for this request |
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 | |
webhooks | WebhookConfig[] | extra webhooks to send on egress events for this request |
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');
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.
| 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',]);
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.EgressIdinfo, err = egressClient.UpdateStream(ctx, &livekit.UpdateStreamRequest{EgressId: streamEgressID,AddOutputUrls: []string{"rtmp://a.rtmp.youtube.com/live2/<stream-key>"}})
# to add streamsegressClient.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 myroomegressClient.list_egress(room_name: 'myroom')# to list all egressesegressClient.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
| Field | Type | Description |
|---|---|---|
| items | array<EgressInfo> | List of egress endpoints. |
EgressInfo
Returned by start, update, list, and stop operations. Describes the egress and its status.
| Field | Type | Description |
|---|---|---|
| egress_id | string | Unique egress ID. |
| room_id | string | Room ID. |
| room_name | string | Room name. |
| source_type | EgressSourceType | Whether the egress was started from web or SDK. |
| status | EgressStatus | Current egress status. |
| started_at | int64 | When the egress started. |
| ended_at | int64 | When the egress ended. |
| updated_at | int64 | Last update timestamp. |
| details | string | Additional status details. |
| error | string | Error message, if any. |
| error_code | int32 | Error code, if any. |
| request | RoomCompositeEgressRequest | WebEgressRequest | ParticipantEgressRequest | TrackCompositeEgressRequest | TrackEgressRequest | The request that started this egress. |
| stream_results | array<StreamInfo> | Results per stream output. |
| file_results | array<FileInfo> | Results per file output. |
| segment_results | array<SegmentsInfo> | Results per segmented output. |
| image_results | array<ImagesInfo> | Results per image output. |
| manifest_location | string | Location of the manifest file, if applicable. |
| backup_storage_used | bool | Whether backup storage was used. |
EgressStatus
Enum. Egress lifecycle status:
| Name | Value | Description |
|---|---|---|
| EGRESS_STARTING | 0 | Egress is starting. |
| EGRESS_ACTIVE | 1 | Egress is active and recording or streaming. |
| EGRESS_ENDING | 2 | Egress is shutting down. |
| EGRESS_COMPLETE | 3 | Egress completed successfully. |
| EGRESS_FAILED | 4 | Egress failed. |
| EGRESS_ABORTED | 5 | Egress was aborted. |
| EGRESS_LIMIT_REACHED | 6 | Egress limit was reached. |
EgressSourceType
Enum. Source of the egress:
| Name | Value | Description |
|---|---|---|
| EGRESS_SOURCE_TYPE_WEB | 0 | Started from the web (e.g. Cloud dashboard). |
| EGRESS_SOURCE_TYPE_SDK | 1 | Started from the SDK or API. |
StreamInfo
Per-stream output result.
| Field | Type | Description |
|---|---|---|
| url | string | Stream URL. |
| started_at | int64 | When the stream started. |
| ended_at | int64 | When the stream ended. |
| duration | int64 | Duration in nanoseconds. |
| status | StreamInfo.Status | Stream status. |
| error | string | Error message, if any. |
| last_retry_at | int64 | Last retry timestamp. |
| retries | uint32 | Number of retries. |
StreamInfo.Status
Enum. Stream output status:
| Name | Value | Description |
|---|---|---|
| ACTIVE | 0 | Stream is active. |
| FINISHED | 1 | Stream finished. |
| FAILED | 2 | Stream failed. |
FileInfo
Per-file output result.
| Field | Type | Description |
|---|---|---|
| filename | string | Output filename. |
| started_at | int64 | When the file recording started. |
| ended_at | int64 | When the file recording ended. |
| duration | int64 | Duration in nanoseconds. |
| size | int64 | File size in bytes. |
| location | string | Storage location (e.g. S3 URL). |
SegmentsInfo
Per-segmented-output result (e.g. HLS).
| Field | Type | Description |
|---|---|---|
| playlist_name | string | Playlist filename. |
| live_playlist_name | string | Live playlist path, if configured. |
| duration | int64 | Total duration in nanoseconds. |
| size | int64 | Total size in bytes. |
| playlist_location | string | Playlist storage location. |
| live_playlist_location | string | Live playlist storage location. |
| segment_count | int64 | Number of segments. |
| started_at | int64 | When the recording started. |
| ended_at | int64 | When the recording ended. |
ImagesInfo
Per-image-output result.
| Field | Type | Description |
|---|---|---|
| filename_prefix | string | Prefix used for image filenames. |
| image_count | int64 | Number of images captured. |
| started_at | int64 | When capture started. |
| ended_at | int64 | When capture ended. |
AudioMixing
Enum. Audio mixing mode when recording audio only:
| Name | Value | Description |
|---|---|---|
| DEFAULT_MIXING | 0 | All users are mixed together. |
| DUAL_CHANNEL_AGENT | 1 | Agent audio in the left channel, all other audio in the right channel. |
| DUAL_CHANNEL_ALTERNATE | 2 | Each new audio track alternates between left and right channels. |
EncodedFileType
Enum. Encoded file format:
| Name | Value | Description |
|---|---|---|
| DEFAULT_FILETYPE | 0 | File type chosen based on codecs. |
| MP4 | 1 | MP4 container. |
| OGG | 2 | OGG container. |
| MP3 | 3 | MP3 audio. |
EncodedFileOutput
| Field | Type | Description |
|---|---|---|
| file_type | EncodedFileType | Optional. Output file type. Default chosen from codecs. |
| filepath | string | Output path. See egress docs for templating. Default {room_name}-{time}. |
| disable_manifest | bool | If true, do not upload manifest file. Default false. |
| s3 | S3Upload | S3-compatible storage. Only one storage output. |
| gcp | GCPUpload | Google Cloud Storage. Only one storage output. |
| azure | AzureBlobUpload | Azure Blob Storage. Only one storage output. |
| aliOSS | AliOSSUpload | Alibaba Cloud OSS. Only one storage output. |
DirectFileOutput
| Field | Type | Description |
|---|---|---|
| filepath | string | Output path. See egress docs for templating. Default {track_id}-{time}. |
| disable_manifest | bool | If true, do not upload manifest file. Default false. |
| s3 | S3Upload | S3-compatible storage. Only one storage output. |
| gcp | GCPUpload | Google Cloud Storage. Only one storage output. |
| azure | AzureBlobUpload | Azure Blob Storage. Only one storage output. |
| aliOSS | AliOSSUpload | Alibaba Cloud OSS. Only one storage output. |
SegmentedFileProtocol
Enum. Segmented output protocol:
| Name | Value | Description |
|---|---|---|
| DEFAULT_SEGMENTED_FILE_PROTOCOL | 0 | Protocol chosen by server. |
| HLS_PROTOCOL | 1 | HLS. |
SegmentedFileSuffix
Enum. Suffix for segment filenames:
| Name | Value | Description |
|---|---|---|
| INDEX | 0 | Numeric index (1, 2, 3, ...). |
| TIMESTAMP | 1 | UTC timestamp. |
SegmentedFileOutput
| Field | Type | Description |
|---|---|---|
| protocol | SegmentedFileProtocol | Optional. Segmented protocol. Default chosen by server. |
| filename_prefix | string | Optional. Prefix for each segment (include paths here). |
| playlist_name | string | Optional. Name of the m3u8 playlist. When empty, matches filename_prefix. |
| live_playlist_name | string | Optional. Path for a live playlist. Omitted if not set. |
| segment_duration | uint32 | Segment length in seconds. Optional. |
| filename_suffix | SegmentedFileSuffix | Optional. INDEX or TIMESTAMP. Default INDEX. |
| disable_manifest | bool | If true, do not upload manifest file. Default false. |
| s3 | S3Upload | S3-compatible storage. Only one storage output. |
| gcp | GCPUpload | Google Cloud Storage. Only one storage output. |
| azure | AzureBlobUpload | Azure Blob Storage. Only one storage output. |
| aliOSS | AliOSSUpload | Alibaba Cloud OSS. Only one storage output. |
StreamProtocol
Enum. Stream output protocol:
| Name | Value | Description |
|---|---|---|
| DEFAULT_PROTOCOL | 0 | Protocol chosen from URLs. |
| RTMP | 1 | RTMP. |
| SRT | 2 | SRT. |
StreamOutput
| Field | Type | Description |
|---|---|---|
| protocol | StreamProtocol | Required. Stream protocol (e.g. RTMP). |
| urls | array<string> | Required. Destination URLs. |
ImageFileSuffix
Enum. Suffix for image filenames:
| Name | Value | Description |
|---|---|---|
| IMAGE_SUFFIX_INDEX | 0 | Numeric index (1, 2, 3, ...). |
| IMAGE_SUFFIX_TIMESTAMP | 1 | Timestamp. |
| IMAGE_SUFFIX_NONE_OVERWRITE | 2 | No suffix; overwrite the same file with the latest image. |
ImageOutput
| Field | Type | Description |
|---|---|---|
| capture_interval | uint32 | Required. Seconds between each snapshot. |
| width | int32 | Optional. Image width. Defaults to track width. |
| height | int32 | Optional. Image height. Defaults to track height. |
| filename_prefix | string | Optional. Prefix for each image filename (include paths here). |
| filename_suffix | ImageFileSuffix | Optional. INDEX, TIMESTAMP, or NONE_OVERWRITE. Default INDEX. |
| image_codec | ImageCodec | Optional. Image codec (e.g. JPEG). |
| disable_manifest | bool | If true, do not upload manifest file. Default false. |
| s3 | S3Upload | S3-compatible storage. Only one storage output. |
| gcp | GCPUpload | Google Cloud Storage. Only one storage output. |
| azure | AzureBlobUpload | Azure Blob Storage. Only one storage output. |
| aliOSS | AliOSSUpload | Alibaba Cloud OSS. Only one storage output. |
S3Upload
| Field | Type | Description |
|---|---|---|
| access_key | string | S3 access key. |
| secret | string | S3 secret key. |
| session_token | string | Optional. Session token for temporary credentials. |
| assume_role_arn | string | Optional. ARN of role to assume for upload (LiveKit Cloud feature when enabled). |
| assume_role_external_id | string | Optional. External ID for assume role. |
| region | string | Bucket region. Optional. |
| endpoint | string | Custom S3 endpoint URL. Optional. |
| bucket | string | Destination bucket. |
| force_path_style | bool | If true, keep bucket in path (no subdomain). Optional. |
| metadata | map<string, string> | Metadata key-value pairs. Optional. |
| tagging | string | S3 object tagging. Optional. |
| content_disposition | string | Content-Disposition header. Optional. |
| proxy | ProxyConfig | Proxy for uploads. Optional. |
GCPUpload
| Field | Type | Description |
|---|---|---|
| credentials | string | Service account credentials JSON (credentials.json). |
| bucket | string | Destination bucket. |
| proxy | ProxyConfig | Proxy for uploads. Optional. |
AzureBlobUpload
| Field | Type | Description |
|---|---|---|
| account_name | string | Azure storage account name. |
| account_key | string | Azure storage account key. |
| container_name | string | Destination container. |
AliOSSUpload
| Field | Type | Description |
|---|---|---|
| access_key | string | Alibaba Cloud access key. |
| secret | string | Alibaba Cloud secret key. |
| region | string | Bucket region. |
| endpoint | string | Custom endpoint URL. Optional. |
| bucket | string | Destination bucket. |
EncodingOptions
| Field | Type | Description |
|---|---|---|
| width | int32 | Output width. Default 1920. |
| height | int32 | Output height. Default 1080. |
| depth | int32 | Color depth. Default 24. |
| framerate | int32 | Frame rate. Default 30. |
| audio_codec | AudioCodec | Audio codec. Default OPUS. |
| audio_bitrate | int32 | Audio bitrate in kbps. Default 128. |
| audio_quality | int32 | Audio encoder quality setting. Optional. |
| audio_frequency | int32 | Sample rate in Hz. Default 44100. |
| video_codec | VideoCodec | Video codec. Default H264_MAIN. |
| video_bitrate | int32 | Video bitrate in kbps. Default 4500. |
| video_quality | int32 | Video encoder quality setting. Optional. |
| key_frame_interval | double | Key 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):
| Name | Value | Description |
|---|---|---|
| H264_720P_30 | 0 | 1280×720, 30 fps, 3000 kbps. |
| H264_720P_60 | 1 | 1280×720, 60 fps, 4500 kbps. |
| H264_1080P_30 | 2 | 1920×1080, 30 fps, 4500 kbps. |
| H264_1080P_60 | 3 | 1920×1080, 60 fps, 6000 kbps. |
| PORTRAIT_H264_720P_30 | 4 | 720×1280, 30 fps, 3000 kbps. |
| PORTRAIT_H264_720P_60 | 5 | 720×1280, 60 fps, 4500 kbps. |
| PORTRAIT_H264_1080P_30 | 6 | 1080×1920, 30 fps, 4500 kbps. |
| PORTRAIT_H264_1080P_60 | 7 | 1080×1920, 60 fps, 6000 kbps. |
ProxyConfig
Proxy server for uploads (S3 and GCP). Use to work around network restrictions to destination buckets.
| Field | Type | Description |
|---|---|---|
| url | string | Proxy URL. |
| username | string | Username for basic auth. Optional. |
| password | string | Password for basic auth. Optional. |
WebhookConfig
Extra webhooks for a specific egress request. Called for egress lifecycle events in addition to project webhooks. See Webhooks.
| Field | Type | Description |
|---|---|---|
| url | string | Webhook URL. |
| signing_key | string | API key to sign the request. Must be defined for the project. |