Custom Recording Template

Since Egress uses an instance of headless Chrome to composite the room, you can use the same application code to design an interactive experience that's livestreamed or recorded.

There are a few differences compared to a standard LiveKit app:

• Do not render the local participant - in this case, the local participant will be the recorder instance
• The local participant should not publish any media
• Room controls (mute, leave, etc) should not be visible

1. You issue a Egress.StartRoomCompositeEgress request to LiveKit
2. LiveKit assigns an available instance of egress to handle it
3. Egress recorder creates necessary connection & authentication details for your template, including:
   • URL of LiveKit Server
   • an access token that's designed to join the room as a recorder
   • desired layout passed to StartRoomCompositeEgress
4. Egress recorder launches Chrome with <baseurl>?url=<>&template=<>&token=<>
5. Egress recorder waits for webapp to log START_RECORDING to start recording
6. Egress recorder waits for webapp to log END_RECORDING to terminate the stream

You don't have to worry about the specifics of the above, we provide a template SDK that handles the interactions with Egress itself.

yarn add @livekit/egress-sdk

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

const room = new Room({
  adaptiveStream: true,
})

// as soon as room is created, register with egress helper so it can listen
// to events.
// when autoEnd is set, recording will stop when all participants have left.
EgressHelper.setRoom(room, {
  autoEnd: true,
})

// advanced feature, if you'd like your recording to switch between different
// layouts programmatically using EgressService.UpdateLayout, those changes
// can be handled here
EgressHelper.onLayoutChanged((layout) => {
})

// connect to the room, and render your application UI as usual
// EgressHelper provides URL and token that are passed in by Egress Service
await room.connect(
  EgressHelper.getLiveKitURL(),
  EgressHelper.getAccessToken(),
);

// when a view has been rendered, call this to start recording
EgressHelper.startRecording();

LiveKit will authenticate the session with an access token that is generated by Egress recorder. It'll assign it a randomly generated user identity beginning with EG_.

If the web page is accessed without a correct access token, it would fail to connect.

To authenticate with your own system, you can attach any additional URL parameters to the baseUrl that is passed to Egress. For example, you could attach a unique authentication key with https://your-template-url.com/?authkey={} as your baseUrl.

In order to speed up the development cycle of your recording templates, we provide a convenient utility in livekit-cli. test-egress-template will spin up a few virtual publishers, and then simulate them joining your room. It'll also point a browser instance to your local template, with the correct URL parameters filled in.

Here's an example:

livekit-cli test-egress-template
  --base-url http://localhost:3000 \
  --url <livekit-instance>
  --api-key <key>
  --api-secret <secret>
  --room <your-room> --layout <your-layout> --publishers 3

This command will launch a browser pointed at http://localhost:3000, while simulating 3 publishers publishing to your livekit instance.