Room composite recording shows black screen when no video tracks are active

Egress / Ingress
1

This question originally came up in our Slack community and the thread has been consolidated here for long-term reference.

I’m recording a room using RoomCompositeEgress and uploading to Cloudflare R2. When screen share or camera is ON, the recording looks fine, but when no screen share or camera is active, the recorded video shows a black screen.

I expected to see a default participant tile/placeholder UI (similar to what the LiveKit UI shows for audio-only users) instead of black frames.

Is this expected behavior? Is there a way to force a default tile/placeholder in recordings?

2

Yes, the black screen is expected behavior with the default egress template.

The solution is to use a custom recording layout via customBaseUrl. Your custom page needs to:

  1. Parse URL parameters for connection details:
const url = getURLParam('url');      // LiveKit WebSocket URL
const token = getURLParam('token');  // Access token
const layout = getURLParam('layout'); // Layout name

  1. Connect to the room using LiveKit JS SDK with those parameters

  2. Signal recording lifecycle via console events:

console.log('START_RECORDING');  // Begin recording
console.log('END_RECORDING');    // End recording

For reference, see the default template source:

And the custom template documentation: