Skip to main content

ADR 0006: Start LiveKit Egress on track_published

  • Status: accepted
  • Date: 2026-11-06
  • Decision makers: the fix task, recorded in the fix report

Context and problem statement​

Live classes must be recorded automatically. Egress started the instant a class moved to IN_PROGRESS, before anyone had joined. In an empty room the composite layout renders nothing and never signals that recording has started, so the egress timed out with code 412 "Start signal not received" and wrote no file.

Decision drivers​

  • No mentor should have to press record.
  • The trigger must fire only when the room has media.
  • Starting twice must not create two recordings.

Considered options​

  • Start egress when the class starts. This is the behaviour that failed.
  • Ask the mentor to start recording by hand.
  • Start egress on the first track_published webhook for the class room.

Decision outcome​

Starting a class only changes its status. The LiveKit server sends a track_published webhook to the LMS service, which starts a room-composite egress for the class if it is IN_PROGRESS and has no egress id yet. Ending the class stops the egress. An egress_ended webhook with status EGRESS_COMPLETE creates the recording. The webhook accepts any content type, because LiveKit sends application/webhook+json, and the signed JWT is the gate.

Consequences​

  • Good: a recording exists for every class that had media, with no manual step. A fully automatic run produced a playable MP4 in production.
  • Bad: recording depends on the webhook reaching the LMS service. The server's webhook URL must point at port 8080.
  • Bad: a webhook lost in transit means a class is not recorded. The server does not retry a response it considers delivered.

Confirmation​

The LMS tests cover the dispatch. In production, an object appears under recordings/<classId>/ after a class with a publisher.

Sources​

.agents/tasks/lms-egress-412/fix-report.md, services/lms-service/src/main/java/com/rtih/startupos/lms/{service/LiveClassService,resource/EgressWebhookResource}.java.