Bedrud utiliza LiveKit para gestionar la comunicación de video y audio en tiempo real. LiveKit proporciona el servidor de medios SFU (Selective Forwarding Unit), y Bedrud se encarga de la autenticación, la gestión de salas y los controles de administración.

Modo Integrado vs. Externo

Bedrud admite dos modos de despliegue de LiveKit:

1. Modo Integrado (Predeterminado): El backend inicia y gestiona un proceso del servidor LiveKit internamente. No se requiere infraestructura adicional - el backend gestiona el ciclo de vida del proceso de LiveKit.
2. Modo Externo: Bedrud se conecta a un servidor o clúster de LiveKit independiente. Esto es útil para escalado horizontal o cuando se utiliza una instancia gestionada de LiveKit Cloud.

Configuración del Modo Externo

Para usar un servidor LiveKit externo, establece las siguientes claves en config.yaml:

livekit:
  host: "wss://livekit.example.com:7880"    # Client WebSocket URL (ws:// or wss://)
  internalHost: "https://livekit.example.com:7880"  # Server-to-server API URL
  apiKey: "your-api-key"
  apiSecret: "your-api-secret"
  external: true          # Skip embedded LiveKit startup
  skipTLSVerify: false    # Set true if LiveKit uses self-signed certs

Cuando embedded es false, Bedrud omite el inicio del binario LiveKit integrado. La API key y el secret deben coincidir con las credenciales del servidor externo.

Para la configuración y despliegue de clústeres de LiveKit, consulta la documentación de LiveKit.

Configuración de Webhook (Solo Externo)

Al usar un servidor LiveKit externo, debes configurar webhooks para que LiveKit pueda notificar a Bedrud sobre desconexiones de participantes y cierres de salas. Sin webhooks, el estado de la base de datos se volverá obsoleto.

Endpoint: https://<your-domain>/api/livekit/webhook

Autenticación: Usa la firma JWT de LiveKit — el mismo apiKey/apiSecret que configuraste arriba. No se necesita ningún secreto adicional.

LiveKit Cloud: Configuración → Webhooks → Crear nuevo webhook. Ingresa la URL del endpoint y selecciona tu clave API.

LiveKit autogestionado: Añade a tu configuración YAML de LiveKit (ej. livekit.yaml):

webhook:
  urls: ["https://bedrud.example.com/api/livekit/webhook"]
  api_key: "your-api-key"

Compatibilidad de Versiones de LiveKit

El modo LiveKit integrado de Bedrud genera automáticamente una configuración compatible. Sin embargo, si autogestionas un servidor LiveKit externo, ten en cuenta los cambios de ruptura entre las versiones de LiveKit:

• LiveKit v1.12+ eliminó el campo tls de nivel superior de su configuración. Si estabas usando tls: en tu YAML de LiveKit, elimínalo. Configura http:// para internalHost y ws:// para host en la configuración de Bedrud. TURN TLS sigue siendo compatible en la sección turn:.
• LiveKit v1.11 y anteriores admiten tls: en el nivel superior. Usa https:// para internalHost y wss:// para host.

En caso de duda, verifica la versión de tu servidor LiveKit con livekit-server --version y consulta las notas de versión de LiveKit.

Generación de Configuración Integrada (Embedded Config Generation)

Cuando TLS está habilitado en modo integrado, Bedrud genera una configuración YAML temporal de LiveKit (/tmp/bedrud-livekit-*.yaml) con:

• TURN habilitado, domain auto-configurado desde server.host, udp_port: 3478, tls_port: 5349, y el certificado TLS del servidor reutilizado para TURN/TLS
• node_ip resuelto mediante livekit.nodeIP → server.host → detección automática de IP saliente
• bind_addresses omitido (LiveKit escucha en todas las interfaces por defecto)

El archivo temporal se elimina cuando el proceso de LiveKit termina. Para omitir la generación automática con una configuración estática, establece livekit.configPath o LIVEKIT_CONFIG_PATH.

Cómo Funciona

1. Creación de Salas

Cuando un usuario crea una sala en Bedrud, el servidor no crea una sala de LiveKit inmediatamente. Las salas de LiveKit se crean bajo demanda cuando el primer participante se une.

2. Tokens de Acceso

Cuando un usuario se une a una reunión:

1. El frontend envía una solicitud a /api/room/join.

2. El backend verifica que el usuario tiene permiso para unirse a esa sala.

3. El backend utiliza su API Key y Secret para generar un JWT firmado (Token de Acceso).

4. El token contiene:

   • El nombre de la sala.
   • La identidad del usuario (nombre para mostrar).
   • Permisos - por ejemplo, si el usuario puede publicar audio o compartir su pantalla.

5. El frontend recibe este token y se conecta directamente al puerto de medios de LiveKit (predeterminado 7880).

3. Controles de Sala (Administración)

El backend utiliza el SDK de Go de LiveKit para realizar acciones administrativas:

• Expulsar: Desconecta a un participante.
• Silenciar: Fuerza el silenciamiento del micrófono de un participante.
• Permisos: Cambia lo que un participante puede hacer en tiempo real.

Arquitectura de Red

• Puerto de API (8090/443): Gestiona las solicitudes HTTP y la señalización WebSocket para la configuración de llamadas.
• Puerto de Medios (7880): Gestiona los datos de video y audio mediante protocolos WebRTC. El fallback ICE/TCP utiliza el puerto 7881 cuando UDP está bloqueado.
• Puerto TURN (3478 UDP / 5349 TLS): Retransmite los medios para clientes detrás de NATs restrictivos o firewalls. Consulta la Guía del Servidor TURN.

Para los requisitos de firewall y puertos, consulta Conectividad WebRTC.

Troubleshooting

Startup & Config Crashes

Connectivity

Media & TURN

Webhook & State

Recording (Egress)

Bedrud uses LiveKit’s RoomCompositeEgress API to record rooms as MP4 files.

Prerequisites

• Redis — LiveKit egress requires Redis for coordinating egress workers. Without Redis, StartRoomCompositeEgress returns permission errors.

• Egress S3 storage (external mode only) — For external LiveKit, you must configure an egress: section in your LiveKit YAML so recordings are stored to durable S3-compatible storage. Otherwise the FileURL is a local path unreachable from Bedrud.

  egress:
    s3:
      access_key: "your-s3-access-key"
      secret_key: "your-s3-secret-key"
      endpoint: "http://minio:9000"
      bucket: "bedrud-recordings"
      region: "us-east-1"
      force_path_style: true

Troubleshooting: Recording

Consulta también

• Guía del Servidor TURN - Arquitectura TURN, configuración, TLS y solución de problemas
• Conectividad WebRTC - pila completa de conectividad STUN/ICE/TURN/SFU
• Resumen de Arquitectura - arquitectura completa del sistema