LiveKit Egress

When submitting an egress request, you can use specific placeholders in the filename or filepath parameters to generate dynamic names based on the session context.

Supported Placeholders

Behavior Rules

• Default Filename: If no filename is provided, it defaults to "{room_name}-{time}".
• Directories: If the filename ends with a /, the file will be generated inside that directory.
• Compatibility by Egress Type:
  • Room Composite: Supports {room_id}, {room_name}, {time}, {utc}.
  • Web: Supports {time}, {utc}.
  • Track Composite: Supports {room_id}, {room_name}, {time}, {utc}, {publisher_identity}.
  • Track: Supports all placeholders listed above.

# Examples of resulting filenames
"{room_name}/{time}" -> testroom/2022-10-04T011306.mp4
"{room_id}-{publisher_identity}.mp4" -> 10719607-f7b0-4d82-afe1-06b77e91fe12-david.mp4
"{track_type}-{track_source}-{track_id}" -> audio-microphone-TR_SKasdXCVgHsei.ogg

To run Egress against a local LiveKit server, you must ensure the Egress container can communicate with your host's Redis and LiveKit server.

Prerequisites

1. Configure Redis: In your host's redis.conf:
   • Comment out bind 127.0.0.1.
   • Set protected-mode no.
2. Identify Host IP: Find the IP address that Docker uses to reach your host (e.g., 172.17.0.1 on Linux, or use nslookup host.docker.internal on Mac/Windows).

Setup Steps

1. Create a local directory (e.g., ~/egress-test).
2. Create a config.yaml in that directory. Use the host IP for ws_url and redis.address, and set insecure: true.
3. Run the container using the following command:

docker run --rm \
    -e EGRESS_CONFIG_FILE=/out/config.yaml \
    -v ~/egress-test:/out \
    livekit/egress

# Example local config.yaml
log_level: debug
api_key: your-api-key
api_secret: your-api-secret
ws_url: ws://192.168.65.2:7880
insecure: true
redis:
  address: 192.168.65.2:6379

The Egress service is configured using a YAML file. You can provide this file by setting the EGRESS_CONFIG_FILE environment variable to the file path (mounted via a volume) or by passing the configuration body directly via the EGRESS_CONFIG_BODY environment variable.

Required Fields

• api_key: LiveKit server API key (or use LIVEKIT_API_KEY env).
• api_secret: LiveKit server API secret (or use LIVEKIT_API_SECRET env).
• ws_url: LiveKit server websocket URL (or use LIVEKIT_WS_URL env).
• redis:
  • address: The Redis address used by your LiveKit server.
  • username: Redis username.
  • password: Redis password.
  • db: Redis database index.

Storage Configuration

You must specify exactly one storage provider. Note that some S3 options can only be set in the global config and cannot be overridden per request.

S3 Options:

• access_key, secret, session_token, region, endpoint, bucket.
• proxy_config: { url, username, password }.
• max_retries (default: 3).
• max_retry_delay (default: 5s).
• min_retry_delay (default: 500ms).
• aws_log_level (default: LogOff).

Azure Options:

• account_name, account_key, container_name.

GCP Options:

• credentials_json, bucket.
• proxy_config: { url, username, password }.

AliOSS Options:

• access_key, secret, region, endpoint, bucket.

# Example minimal config
api_key: livekit-key
api_secret: livekit-secret
ws_url: ws://livekit.example.com
redis:
  address: redis:6379
  db: 0
storage:
  s3:
    bucket: my-egress-bucket
    region: us-east-1

LiveKit Egress supports various output formats depending on the type of egress requested. Files can be uploaded to S3-compatible storage, Azure, or GCP.

The EgressHelper object provides utility methods for web-based LiveKit recording templates to extract necessary connection parameters from the URL and manage the recording lifecycle.

When a recording starts using a web template, the LiveKit Egress service will point a browser instance to your template URL. You should use EgressHelper to:

1. Extract the url (LiveKit server URL) and token (access token) from the query string to connect to the room.
2. Manage the Room instance via setRoom.
3. Handle layout changes triggered by participant metadata updates.
4. Signal the start and end of recording via console logs (START_RECORDING and END_RECORDING).

import EgressHelper from '@livekit/egress-sdk';
import { Room } from 'livekit-client';

// 1. Get connection details from the URL
const livekitUrl = EgressHelper.getLiveKitURL();
const token = EgressHelper.getAccessToken();

// 2. Initialize the room and register it with the helper
const room = new Room();
await room.connect(livekitUrl, token);
EgressHelper.setRoom(room);

// 3. Listen for layout changes (e.g., switching from grid to speaker view)
EgressHelper.onLayoutChanged((newLayout) => {
  console.log('Switching to layout:', newLayout);
  // Apply your CSS or UI logic here
});

// 4. Start recording logic
EgressHelper.startRecording();