createEgressService

Ce que ça fait

Démarre, arrête et suit des enregistrements composites de salle (room composite) via le service Egress de LiveKit.

Signature

function createEgressService(config: LiveKitServiceConfig): EgressService

Paramètres

Nom	Type	Requis	Défaut	Description
serverUrl	string	oui	—	URL HTTP du serveur LiveKit
apiKey	string	oui	—	Clé API LiveKit
apiSecret	string	oui	—	Secret API LiveKit

Retour

Un EgressService :

Méthode	Rôle
startRoomCompositeEgress(roomName, output, options?)	Démarre un enregistrement. output.filepath est toujours requis (gabarit de nom de fichier) ; output.s3/gcp/azure ajoutent une destination cloud — sans eux, le fichier reste local au serveur Egress.
stopEgress(egressId)	Arrête un enregistrement en cours.
getEgressStatus(egressId)	Consulte l’état d’un enregistrement. Lève EGRESS_FAILED si celui-ci a échoué ou a été abandonné.
listEgress(options?)	{ roomName?, activeOnly? } — reflète l’état réel du serveur, jamais un cache local.
raw	Instance réelle EgressClient du SDK — échappatoire typée, voir docs/recipes/raw-escape-hatch.md

EgressInfo (rendu par toutes les méthodes ci-dessus, sauf listEgress qui en rend un tableau) :

Champ	Type	Description
egressId	string	Identifiant unique de l’enregistrement
roomName	string	Salle enregistrée
status	"starting" | "active" | "ending" | "complete" | "failed" | "aborted" | "limit_reached"
error	string | undefined	Détail de l’échec, si status en porte un
files	EgressFileResult[]	{ filename, durationSeconds, sizeBytes }

Erreurs

Code	Quand	Comment corriger
LEGBA_INVALID_EGRESS_REQUEST	roomName vide/blanc	Fournir un nom de salle valide
LEGBA_EGRESS_ROOM_NOT_FOUND	startRoomCompositeEgress sur une salle qui n’existe pas	Créer la salle d’abord (createRoomService)
LEGBA_EGRESS_NOT_FOUND	stopEgress/getEgressStatus sur un egressId inconnu	Vérifier l’identifiant
LEGBA_EGRESS_FAILED	L’enregistrement a échoué ou a été abandonné	Voir error.message pour la cause ; l’appel en cours n’est jamais interrompu par cet échec

Exemple minimal

import { createEgressService } from "@legba-core/realtime";

const egress = createEgressService({ serverUrl, apiKey, apiSecret });
const { egressId } = await egress.startRoomCompositeEgress("salle-demo", {
  filepath: "enregistrements/{room_name}-{time}.mp4",
});

Exemple complet

import { createEgressService, LegbaEgressError, EGRESS_ERROR_CODES } from "@legba-core/realtime";
import { S3Upload } from "livekit-server-sdk";

const egress = createEgressService({ serverUrl, apiKey, apiSecret });

const started = await egress.startRoomCompositeEgress(
  "salle-demo",
  {
    filepath: "{room_name}-{time}.mp4",
    s3: new S3Upload({ accessKey, secret, bucket: "mes-enregistrements", region: "us-east-1" }),
  },
  { layout: "grid" },
);

try {
  const status = await egress.getEgressStatus(started.egressId);
  console.log(status.status, status.files);
} catch (error) {
  if (error instanceof LegbaEgressError && error.code === EGRESS_ERROR_CODES.EGRESS_FAILED) {
    console.error("échec de l'enregistrement :", error.message);
  }
}

Pièges

• Requiert Redis et un worker livekit-egress déployés à côté de livekit-server (voir docker-compose.yml) — l’enregistrement ne tourne jamais dans livekit-server lui-même. Un projet qui n’utilise pas l’enregistrement n’a besoin ni de l’un ni de l’autre.
• L’arrêt automatique en fin de salle est géré nativement par LiveKit : pas besoin d’écouter room_finished pour appeler stopEgress soi-même.
• Un enregistrement arrêté immédiatement après son démarrage (avant que le pipeline interne ait fini de s’initialiser) se termine en EGRESS_FAILED (statut "aborted"), pas en succès silencieux.
• LegbaWebhookEvent.egressId (voir createWebhookService) porte le même identifiant que EgressInfo.egressId pour les événements egress_* — utile pour corréler sans avoir à sonder getEgressStatus en boucle.
• raw est une échappatoire expérimentale : par exemple démarrer un egress TrackComposite/Track (non enveloppé par EgressService, qui ne couvre que RoomComposite) contourne toute validation propre à Legba — voir docs/recipes/raw-escape-hatch.md.

Voir aussi

• LegbaEgressError
• createWebhookService
• createRoomService