Esta guía explica cómo conectar el plugin Voice de Discourse con un servidor de medios LiveKit. Por defecto, las llamadas de voz funcionan de extremo a extremo (peer-to-peer): cada participante envía su audio directamente a todos los demás. Esto funciona muy bien para salas pequeñas, pero el ancho de banda aumenta con el tamaño de la sala. Rutar las llamadas a través de LiveKit mantiene la carga de subida de cada participante constante, sin importar cuántas personas se unan.
Requisitos previos
Antes de comenzar, asegúrate de tener:
- Un sitio de Discourse con el plugin Voice habilitado.
- Un servidor de LiveKit al que puedas acceder, con sus credenciales de API. Puedes autoalojar LiveKit o usar un servicio gestionado como LiveKit Cloud.
- Acceso de administrador a tu sitio de Discourse.
Paso 1 — Habilitar el plugin Voice
Voice se distribuye incluido con Discourse. Ve a Admin → Settings → Plugins y
desactiva la configuración Voice (voice_enabled).
Paso 2 — Aprovisionar un servidor de LiveKit y anotar las credenciales
Necesitas tres cosas de tu despliegue de LiveKit: la URL de WebSocket, la
clave de API y el secreto de API.
Estos pasos son relativamente sencillos con LiveKit Cloud:
- Crea un proyecto en el panel de LiveKit Cloud.
- Desde la página Settings → Keys del proyecto, muestra la API key y
el API secret. - Anota la URL de WebSocket (por ejemplo,
wss://my-project.livekit.cloud).
Para instalaciones de LiveKit autoalojadas, consulta la documentación respectiva.
Paso 3 — Configurar la conexión de LiveKit en Discourse
Ve a Admin → Plugins → Voice, abre la configuración y completa la sección de LiveKit:
| Configuración | Qué introducir |
|---|---|
voice_livekit_url |
La URL de WebSocket, p. ej. wss://livekit.example.com (o ws:// para laboratorios HTTP sin cifrar). |
voice_livekit_api_key |
La clave de API del Paso 2. |
voice_livekit_api_secret |
El secreto de API del Paso 2. |
voice_livekit_room_policy |
Qué salas usan LiveKit. |
La configuración voice_livekit_room_policy decide cómo eligen el transporte las salas:
| Política | Comportamiento |
|---|---|
disabled |
Todas las llamadas funcionan de extremo a extremo (el valor predeterminado). |
per_room |
Los creadores/gestores de sala activan individualmente las salas con una casilla Use media server (SFU) en el formulario de la sala. |
all_rooms |
Todas las salas se enrutan a través de LiveKit. |
Paso 5 — Configuraciones adicionales opcionales
Estas configuraciones ajustan la integración:
| Configuración | Propósito |
|---|---|
voice_livekit_room_prefix |
Prefijo de espacio de nombres para los nombres de sala en LiveKit. Con múltiples sitios compartiendo un solo servidor de LiveKit, establece un prefijo único por sitio. Si está vacío, se usa el nombre de la base de datos del sitio. |
voice_livekit_mesh_fallback |
Cuando no se puede emitir un token de LiveKit y la sala está vacía, inicia en la malla de extremo a extremo en lugar de fallar la entrada. Desactivado por defecto: la degradación silenciosa puede ocultar una interrupción de LiveKit. |
voice_livekit_recording_enabled |
Permite a los moderadores de sala grabar llamadas que se ejecutan en LiveKit. Las grabaciones son producidas por LiveKit Egress y almacenadas en el almacenamiento de tu despliegue de LiveKit (S3, GCS, disco local), no se suben a Discourse. |
voice_livekit_recording_filepath |
La ruta de archivo pasada a LiveKit Egress, p. ej. voice/{room_name}-{utc}. Admite marcadores de posición como {room_name}, {room_id}, {time}, {utc}; la extensión del archivo se añade automáticamente. |
Paso 6 — Opcional: habilitar webhooks de LiveKit
Los webhooks son una red de seguridad solo de reconciliación. Cuando la conexión de un participante se interrumpe bruscamente o una sala termina, los webhooks permiten al plugin limpiar la presencia y el estado de la sala en segundos, en lugar de esperar al TTL del heartbeat. Son opcionales: si no se pueden entregar, las llamadas siguen funcionando, pero la limpieza tarda un poco más.
En el servidor de LiveKit, añade el punto de final del webhook (el plugin muestra el fragmento exacto en su panel de administración hasta que llega el primer webhook):
# livekit.yaml
webhook:
api_key: <your-api-key>
urls:
- https://forum.example.com/voice/livekit/webhook
Reinicia LiveKit. Las entregas se autentican con el secreto de API; no se necesita configurar ningún secreto compartido adicional.
Paso 7 — Verificar la integración
Revisar el panel de administración de Voice de Discourse
Ve a Admin → Plugins → Voice → Dashboard. Una vez que esté presente cualquier configuración de LiveKit, el panel muestra una tarjeta de estado de servidor de medios LiveKit con comprobaciones en vivo:
- estado de la configuración (qué configuraciones están presentes y la política activa),
- si se pueden firmar tokens de acceso con el par de claves,
- si el servidor es accesible y cuántas salas están activas,
- la última comprobación automática de conectividad,
- si se están recibiendo webhooks.
Usa Refresh para ejecutar una sonda bajo demanda.
Aquí hay una captura de pantalla del panel del plugin Voice con LiveKit habilitado:
Revisar el panel de LiveKit
También hay detalles sobre las llamadas en el panel de LiveKit. Aquí hay un ejemplo:
