Overview

The PoolStat Scoreboard PWA communicates with OBS Studio using:

  • OBS WebSocket v5 — scene switching and stream control
  • Browser Source — the scoreboard overlay rendered in OBS
  • MQTT — live match data pushed to the browser source

OBS WebSocket v5

Enable in OBS

  1. In OBS, open Tools → WebSocket Server Settings
  2. Enable WebSocket Server
  3. Set a strong password
  4. Note the port (default: 4455)

Configure in the PWA

The browser source overlay (browser_source.html) manages the OBS WebSocket connection internally. The control panel handles scene switching through its own direct WebSocket connection — configured via the Settings tab in the control panel.

The PWA backend does not connect to OBS WebSocket directly. Scene switching instructions flow from the server → MQTT → browser source → OBS WebSocket.

Browser Source Setup

Add a browser source to every OBS scene collection that will show the scoreboard overlay.

URL format

https://your-pwa-server.example.com/browser-source.html?rigId=YOUR_RIG_ID

Replace YOUR_RIG_ID with the Rig ID configured in the Admin panel for this machine.

Setting Value
Width 1920
Height 1080
Use custom frame rate Off
Shutdown source when not visible Off
Refresh browser when scene becomes active Optional
Hardware acceleration On (if available)

Keep the source loaded. The browser source must remain in memory (not shut down when hidden) to receive MQTT messages while it is off-screen. If you enable “Shutdown source when not visible”, the overlay will miss match updates while hidden.

Scene Configuration

The PWA automates two scene transitions per match:

Transition Scene used
Go Live Match Scene Name from the rig’s admin config
Start Intermission Intermission Scene Name from the rig’s admin config

Configure these scene names in Admin → Rig → Edit.

The scene names must match exactly (case-sensitive) the scene names in OBS.

MQTT Data Flow

PoolStat Portal → MQTT Broker → browser_source.html (OBS)
                                        ↓
                               Renders overlay
                               Switches scenes via OBS WebSocket

The MQTT topic is filtered by rigId so that only messages intended for this rig are processed. The broker URL and credentials are configured in the server’s .env file (see Installation & Setup).

Troubleshooting

Overlay not appearing

  • Check that the browser source URL includes the correct ?rigId= parameter
  • Verify the rig ID in Admin matches exactly
  • Open the browser source Interact window in OBS and check the browser console for errors

Scenes not switching

  • Confirm OBS WebSocket is enabled and the password is correct in the control panel Settings tab
  • Check that scene names in Admin match exactly what is in OBS
  • Scene collection switching mid-stream is not supported by OBS WebSocket v5 — only scene switching within the active collection works

MQTT not receiving data

  • Confirm MQTT_BROKER_URL, MQTT_USERNAME, and MQTT_PASSWORD are set correctly in .env
  • The MQTT broker must support WebSocket connections (port 9001 by default)
  • Check server logs: npm start will show MQTT connection status on startup