Overview
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
Understanding the flow
- You issue a
Egress.StartRoomCompositeEgress
request to LiveKit - LiveKit assigns an available instance of egress to handle it
- 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
- Egress recorder launches Chrome with
<baseurl>?url=<>&template=<>&token=<>
- Egress recorder waits for webapp to log
START_RECORDING
to start recording - 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.
Using the template SDK
Install
yarn add @livekit/egress-sdk
Usage
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 hereEgressHelper.onLayoutChanged((layout) => {})// connect to the room, and render your application UI as usual// EgressHelper provides URL and token that are passed in by Egress Serviceawait room.connect(EgressHelper.getLiveKitURL(),EgressHelper.getAccessToken(),);// when a view has been rendered, call this to start recordingEgressHelper.startRecording();
Authentication
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
.
Testing your templates
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.