// docs / websocket-obs

WebSocket y OBS

LiveAudio levanta un servidor WebSocket local que emite subtítulos en JSON en tiempo real. OBS es el destino integrado mediante el overlay incluido subtitulos_obs.html, pero cualquier cliente HTML o WebSocket en localhost puede conectarse y recibir la misma transmisión.

Detalles del servidor

Esquema del payload JSON

{
  "id": "1760000000000-12",
  "text": "Hola a todos, bienvenidos al stream",
  "style": "default",
  "created_at": 1760000000.0,
  "processed_at": 1760000001.3,
  "queue_delay": 0.2,
  "total_delay": 1.3,
  "latency": 1.1,
  "is_replay": false,
  "catchup_interval_sec": 0.0
}

El overlay de OBS integrado solo consume text y style. Los demás campos son metadata para diagnóstico y control de backlog — útiles si construyes tu propio cliente, ignorables si no.

Estilos de subtítulos

El campo style selecciona uno de siete looks integrados, conmutables desde la pestaña Subtítulos:

Política de backlog en OBS

La política de backlog controla solo lo que se muestra en vivo en OBS. Todo lo válido siempre se guarda en disco, sin importar la política.

Seguridad

• Solo localhost — el servidor rechaza cualquier conexión que no sea de 127.0.0.1, ::1 o localhost.
• No requiere autenticación, porque está limitado a localhost.
• Broadcast — múltiples clientes reciben los mismos mensajes a la vez.

Configurar el Browser Source de OBS

• En OBS, Fuentes → + → Navegador.
• Elige Archivo local y selecciona subtitulos_obs.html (en liveaudio/assets/). Tamaño 1920×200.
• Pon los FPS en 30 o 60 y ubica la fuente en la parte inferior central de la escena.
• Desactiva "Apagar la fuente cuando no esté visible" y "Actualizar el navegador cuando la escena se active" — ambas pueden cortar la conexión WebSocket.
• Para un puerto personalizado, configura ws_port en config.json; el HTML de OBS lee ?port=XXXX de su URL (default 8765).

Comportamiento de la conexión

• Reconexión. Un cliente que pierde la conexión reintenta cada 3 segundos aproximadamente hasta que el servidor vuelve — el overlay incluido ya lo hace por ti.
• Broadcast. Cada cliente conectado recibe cada mensaje. Varios clientes (OBS más una pestaña de depuración) ven el mismo flujo, y un cliente lento no bloquea a los demás.
• Sin backpressure. Con websockets ≥ 16 el servidor usa broadcast(), que reparte sin esperar a ningún cliente en particular.

Construir tu propio cliente

Cualquier cliente WebSocket en localhost puede suscribirse a la misma transmisión que lee OBS. Un cliente mínimo en navegador — ábrelo directamente, o cárgalo como Browser Source en OBS:

<!-- open this file in a browser, or load it as an OBS Browser Source -->
<div id="caption"></div>
<script>
  // ?port=XXXX overrides the default; matches ws_port in config.json
  const port = new URLSearchParams(location.search).get("port") || "8765";
  let ws;
  function connect() {
    ws = new WebSocket("ws://127.0.0.1:" + port);
    ws.onmessage = (e) => {
      const msg = JSON.parse(e.data);       // the subtitle payload
      document.getElementById("caption").textContent = msg.text;
    };
    // the server only broadcasts — reconnect every 3 s if it drops
    ws.onclose = () => setTimeout(connect, 3000);
  }
  connect();
</script>

O un cliente mínimo en Python, para imprimir cada payload a medida que llega (requiere el paquete websockets):

import asyncio, websockets

async def test():
    async with websockets.connect("ws://127.0.0.1:8765") as ws:
        async for msg in ws:
            print(msg)

asyncio.run(test())

Señales de depuración

Abre el overlay en un navegador y presiona F12 → Consola. Estos mensajes indican dónde se traba un overlay que no muestra nada: