Egress output types

Since Composite and Participant Egress are transcoded, they can be output to a wide range of formats and destinations.

Egress is optimized to transcode once while sending output to multiple destinations. For example, from the same Egress you may simultaneously:

• stream to one or more RTMP endpoints
• record as HLS
• record as MP4
• generate thumbnails

When creating a new Egress, set one or more of the following:

• file_outputs - record to a MP4 file
• stream_outputs - stream to RTMP or SRT server
• segment_outputs - record as HLS segments
• image_outputs - generate thumbnails

{
  ... // source details
  "file_outputs": [
    {
      "filepath": "my-test-file.mp4",
      "s3": { ... },
      "gcp": { ... },
      "azure": { ... },
      "aliOSS": { ... }
    }
  ],
  "stream_outputs": [
    {
      "protocol": "rtmp",
      "urls": ["rtmp://my-rtmp-endpoint/path/stream-key"]
    }
  ],
  "segment_outputs": [
    {
      "filename_prefix": "my-output",
      "playlist_name": "my-output.m3u8",
      // when provided, we'll generate a playlist containing only the last few segments
      "live_playlist_name": "my-output-live.m3u8",
      "segment_duration": 2,
      "s3": { ... },
      "gcp": { ... },
      "azure": { ... },
      "aliOSS": { ... }
    }
  ],
  "image_outputs": [
    {
      "capture_interval": 5,
      "filename_prefix": "my-image",
      "filename_suffix": "IMAGE_SUFFIX_INDEX",
      "s3": { ... },
      "gcp": { ... },
      "azure": { ... },
      "aliOSS": { ... }
    }
  ]
}

RTMP streams do not perform well over long distances. Some stream providers include a region or location as part of your stream url, while others might use region-based routing.

• When self-hosting, choose stream endpoints that are close to where your Egress servers are deployed.
• With Cloud Egress, we will route your Egress request to a server closest to your RTMP endpoints.

Streams can be added and removed on the fly using the UpdateStream API.

To use the UpdateStream API, your initial request must include a StreamOutput. If the stream will start later, include a StreamOutput in the initial request with the correct protocol and an empty urls array.

Mux is LiveKit's preferred partner for HLS streaming. To start a Mux stream, all you need is your stream key. You can then use mux://<stream_key> as a url in your StreamOutput.

When outputing to files, the filepath and filename_prefix fields support templated variables. The below templates can be used in request filename/filepath parameters:

• If no filename is provided with a request, one will be generated in the form of "{room_name}-{time}".
• If your filename ends with a /, a file will be generated in that directory.
• If your filename is missing an extension or includes the wrong extension, the correct one will be added.

Examples:

Image output allows you to create periodic snapshots from a recording or stream, useful for generating thumbnails or running moderation workflows in your application.

The configuration options are:

• capture_interval - the interval in seconds between each snapshot
• filename_prefix - the prefix for each image file
• filename_suffix - the suffix for each image file. This can be a timestamp or an index.
• width and height - the dimensions of the image. If not provided, the image will be the same size as the video frame.

Egress supports any S3-compatible storage provider, including:

• MinIO
• Oracle Cloud
• CloudFlare R2
• Digital Ocean
• Akamai Linode
• Backblaze

When using non-AWS storage, set force_path_style to true. This ensures the bucket name is used in the path, rather than as a subdomain.

Configuration fields:

• access_key - the access key for your S3 account
• secret - the secret key for your S3 account
• region - the region where your S3 bucket is located (required when endpoint is not set)
• bucket - the name of the bucket where the file will be stored
• endpoint - the endpoint for your S3-compatible storage provider (optional)
• metadata - key/value pair to set as S3 metadata
• content_disposition - Content-Disposition header when the file is downloaded
• proxy - HTTP proxy to use when uploading files. {url: "", username: "", password: ""}

For Egress to upload to Google Cloud Storage, you'll need to provide credentials in JSON.

This can be obtained by first creating a service account that has permissions to create storage objects (i.e. Storage Object Creator). Then create a key for that account and export as a JSON file. We'll refer to this file as credentials.json.

Configuration fields:

• credentials - service account credentials serialized in JSON "credentials.json"
• bucket - the name of the bucket where the file will be stored
• proxy - HTTP proxy to use when uploading files. {url: "", username: "", password: ""}

In order to upload to Azure Blob Storage, you'll need the account's shared access key.

Configuration fields:

• account_name - the name of the Azure account
• account_key - the shared access key for the Azure account
• container_name - the name of the container where the file will be stored