createLegbaRoom

Ce que ça fait

Crée un client de connexion LiveKit côté navigateur : connexion, publication micro/caméra/partage d’écran, changement de périphérique, événements de présence, messages de données.

Signature

function createLegbaRoom(): LegbaClientRoom

Paramètres

Aucun. La connexion elle-même se fait via connect(options).

Retour

Un LegbaClientRoom :

Méthode	Rôle
connect({ serverUrl, token })	Se connecte à une salle. Idempotent si déjà connecté.
disconnect()	Se déconnecte et libère les pistes locales. Ne lève jamais, même sans connexion active.
publishMicrophone() / unpublishMicrophone()	Active/désactive le micro local
publishCamera() / unpublishCamera()	Active/désactive la caméra locale
startScreenShare() / stopScreenShare()	Démarre/arrête un partage d’écran (avec audio si la source le fournit). stopScreenShare() sans partage actif ne fait rien.
sendData(payload, options?)	Envoie un message de données JSON à la salle (options.destinationIdentities omis/vide) ou à des participants ciblés. options.reliable (défaut true) et options.topic optionnels.
switchMicrophoneDevice(deviceId) / switchCameraDevice(deviceId)	Change de périphérique actif sans interrompre la publication
getRemoteParticipants()	Instantané des participants distants actuellement connus et de leurs pistes actuellement abonnées. [] avant toute connexion.
on(event, listener) / off(event, listener)	S’abonne/se désabonne des événements (participantConnected, participantDisconnected, trackSubscribed, trackUnsubscribed, dataReceived, reconnecting, reconnected, disconnected)
state	"disconnected" | "connecting" | "connected" | "reconnecting" | "signalReconnecting"
raw	Instance réelle Room de livekit-client — échappatoire typée, voir docs/recipes/raw-escape-hatch.md

Erreurs

Code	Quand	Comment corriger
LEGBA_CLIENT_CONNECTION_FAILED	Le serveur refuse la connexion (jeton invalide/expiré)	Vérifier le jeton, voir le message pour la cause serveur
LEGBA_CLIENT_DEVICE_PERMISSION_DENIED	Le navigateur refuse l’accès micro/caméra/partage d’écran	Demander la permission à l’utilisateur avant de rappeler publishMicrophone/publishCamera/startScreenShare
LEGBA_CLIENT_NOT_CONNECTED	startScreenShare() appelé avant connect() ou après disconnect()	Se connecter avant de démarrer un partage
LEGBA_CLIENT_SCREEN_SHARE_ALREADY_ACTIVE	startScreenShare() appelé alors qu’un partage est déjà en cours (y compris deux appels concurrents)	Appeler stopScreenShare() avant d’en démarrer un nouveau
LEGBA_CLIENT_SCREEN_SHARE_NOT_SUPPORTED	Le navigateur ne fournit pas getDisplayMedia (API absente ou contexte non sécurisé)	Vérifier le support avant d’afficher le bouton de partage
LEGBA_CLIENT_DATA_MESSAGE_NOT_SERIALIZABLE	sendData() : le payload n’est pas sérialisable en JSON (référence circulaire, etc.)	Envoyer une valeur sérialisable en JSON
LEGBA_CLIENT_DATA_MESSAGE_INVALID_DESTINATION	sendData() : destinationIdentities contient une identité vide/blanche	Filtrer les identités vides avant l’appel
LEGBA_CLIENT_DATA_MESSAGE_TOO_LARGE	sendData() : le message dépasse la taille maximale négociée pour la connexion (dynamique, pas une constante fixe)	Réduire la taille du payload

Exemple minimal

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

const room = createLegbaRoom();
await room.connect({ serverUrl: "wss://mon-serveur.livekit.cloud", token });
await room.publishMicrophone();

Exemple complet

import { createLegbaRoom, LegbaClientError, CLIENT_ERROR_CODES } from "@legba-core/realtime/client";

const room = createLegbaRoom();

room.on("participantConnected", ({ identity }) => console.log(`${identity} a rejoint`));
room.on("reconnecting", () => console.log("connexion instable, reconnexion…"));
room.on("reconnected", () => console.log("reconnecté"));

try {
  await room.connect({ serverUrl, token });
  await room.publishMicrophone();
} catch (error) {
  if (error instanceof LegbaClientError && error.code === CLIENT_ERROR_CODES.DEVICE_PERMISSION_DENIED) {
    alert("Autorise le micro pour rejoindre l'appel.");
  }
}

Pièges

• @legba-core/realtime/client est un point d’entrée séparé de @legba-core/realtime : n’importer que l’un ou l’autre selon l’environnement (navigateur vs serveur Node), jamais les deux dans le même bundle.
• La reconnexion après coupure réseau est gérée automatiquement par livekit-client en interne (piste republiées sans action de l’appelant) : reconnecting/reconnected ne sont que des notifications, pas des actions à effectuer.
• participantConnected ne se déclenche jamais pour un participant déjà présent au moment de la connexion — seulement pour ceux qui rejoignent après. Pour savoir qui est déjà là, s’appuyer sur trackSubscribed (déclenché pour toute piste disponible, peu importe l’ordre d’arrivée) plutôt que sur la présence seule.
• Si l’utilisateur arrête le partage via le contrôle natif du navigateur (bouton « Arrêter le partage » de Chrome) plutôt que via stopScreenShare(), l’état se resynchronise automatiquement : un nouvel appel à startScreenShare() fonctionne directement, sans appel préalable à stopScreenShare().
• sendData() ne déclenche jamais dataReceived chez l’émetteur lui-même (pas d’auto-écoute) : une UI de chat doit afficher son propre message localement au moment de l’appel, pas attendre dataReceived.
• La réception de dataReceived est volontairement tolérante : si le payload reçu n’est pas un JSON valide (pair non-Legba, message malformé), payload contient la chaîne brute décodée plutôt que de lever une exception — un payload non fiable ne doit jamais faire planter les autres écouteurs branchés sur le même événement.
• sendData() n’attend pas de rejeu après une reconnexion : livekit-client n’a aucun backlog de canal de données, seuls les nouveaux messages envoyés après la reconnexion sont reçus.
• raw est une échappatoire expérimentale : appeler directement une méthode du SDK natif via raw contourne toute validation propre à Legba (aucun garde-fou, aucune erreur LegbaClientError typée). À réserver aux fonctionnalités que LegbaClientRoom n’enveloppe pas encore — voir docs/recipes/raw-escape-hatch.md.

Voir aussi

• createAccessToken
• LegbaClientError