Ce guide détaille la procédure de connexion du plugin Voice de Discourse à un serveur média LiveKit. Par défaut, les appels vocaux sont effectués en pair-à-pair : chaque participant envoie son audio directement à tous les autres participants. Cela fonctionne très bien pour les petites salles, mais la bande passante augmente avec la taille de la salle. Acheminer les appels via LiveKit maintient l’envoi de chaque participant constant, quel que soit le nombre de personnes qui rejoignent.
Prérequis
Avant de commencer, assurez-vous de disposer de :
- Un site Discourse exécutant le plugin Voice activé
- Un serveur LiveKit accessible, avec ses identifiants API. Vous pouvez héberger LiveKit vous-même ou utiliser une offre gérée telle que LiveKit Cloud.
- Un accès administrateur à votre site Discourse.
Étape 1 — Activer le plugin Voice
Voice est fourni en bundle avec Discourse. Allez dans Admin → Settings → Plugins et
activez le paramètre Voice (voice_enabled).
Étape 2 — Provisionner un serveur LiveKit et noter les identifiants
Vous avez besoin de trois éléments de votre déploiement LiveKit : l’URL WebSocket, la
clé API et le secret API.
Ces étapes sont relativement simples avec LiveKit Cloud :
- Créez un projet dans le tableau de bord LiveKit Cloud.
- Depuis la page Settings → Keys du projet, révélez la clé API et le
secret API. - Notez l’URL WebSocket (par exemple
wss://my-project.livekit.cloud).
Pour les installations LiveKit auto-hébergées, veuillez vous référer à la documentation respective.
Étape 3 — Configurer la connexion LiveKit dans Discourse
Allez dans Admin → Plugins → Voice, ouvrez les paramètres et remplissez la section LiveKit :
| Paramètre | Ce qu’il faut saisir |
|---|---|
voice_livekit_url |
L’URL WebSocket, par ex. wss://livekit.example.com (ou ws:// pour les laboratoires HTTP simples). |
voice_livekit_api_key |
La clé API de l’étape 2. |
voice_livekit_api_secret |
Le secret API de l’étape 2. |
voice_livekit_room_policy |
Quelles salles utilisent LiveKit. |
Le paramètre voice_livekit_room_policy détermine comment les salles choisissent un transport :
| Politique | Comportement |
|---|---|
disabled |
Tous les appels sont exécutés en pair-à-pair (par défaut). |
per_room |
Les créateurs/gestionnaires de salle optent individuellement pour une salle via une case à cocher Utiliser le serveur média (SFU) dans le formulaire de la salle. |
all_rooms |
Chaque salle est acheminée via LiveKit. |
Étape 5 — Paramètres supplémentaires optionnels
Ces paramètres affinent l’intégration :
| Paramètre | But |
|---|---|
voice_livekit_room_prefix |
Préfixe d’espace de noms pour les noms de salles sur LiveKit. Avec plusieurs sites partageant un seul serveur LiveKit, définissez un préfixe unique par site. Vide par défaut, il se substitue par le nom de la base de données du site. |
voice_livekit_mesh_fallback |
Lorsqu’un jeton LiveKit ne peut pas être émis et que la salle est vide, démarrez sur le maillage pair-à-pair au lieu d’échouer à la connexion. Désactivé par défaut — une dégradation silencieuse peut masquer une panne de LiveKit. |
voice_livekit_recording_enabled |
Permettre aux modérateurs de salle d’enregistrer les appels exécutés sur LiveKit. Les enregistrements sont produits par LiveKit Egress et stockés sur le stockage du déploiement LiveKit (S3, GCS, disque local) — et non téléversés sur Discourse. |
voice_livekit_recording_filepath |
Le chemin de fichier transmis à LiveKit Egress, par ex. voice/{room_name}-{utc}. Prend en charge des espaces réservés tels que {room_name}, {room_id}, {time}, {utc} ; l’extension du fichier est ajoutée automatiquement. |
Étape 6 — Optionnel : activer les webhooks LiveKit
Les webhooks sont un filet de sécurité de réconciliation uniquement. Lorsque la connexion d’un participant meurt
brutalement ou qu’une salle se termine, les webhooks permettent au plugin de nettoyer la présence et l’état de la
salle en quelques secondes au lieu d’attendre l’expiration du TTL de battement de cœur. Ils sont
optionnels — s’ils ne peuvent pas être livrés, les appels fonctionnent toujours, le nettoyage prend juste
un peu plus de temps.
Sur le serveur LiveKit, ajoutez le point de terminaison du webhook (le plugin affiche l’extrait exact sur son tableau de bord d’administration jusqu’à l’arrivée du premier webhook) :
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
Redémarrez LiveKit. Les livraisons sont authentifiées avec le secret API —
aucun secret partagé supplémentaire à configurer.
Étape 7 — Vérifier l’intégration
Vérifier le tableau de bord d’administration Voice de Discourse
Allez dans Admin → Plugins → Voice → Dashboard. Dès qu’un paramètre LiveKit est
présent, le tableau de bord affiche une carte d’état Serveur média LiveKit avec des
vérifications en direct :
- l’état de la configuration (quels paramètres sont présents et la politique active),
- si les jetons d’accès peuvent être signés avec la paire de clés,
- si le serveur est accessible et combien de salles sont actives,
- la dernière vérification de connectivité automatique,
- si les webhooks sont reçus.
Utilisez Refresh pour exécuter une sonde à la demande.
Voici une capture d’écran du tableau de bord du plugin Voice avec LiveKit activé :
Vérifier le tableau de bord LiveKit
Il y a aussi des détails sur les appels dans le tableau de bord LiveKit. Voici un exemple :
