Skip to main content
The OBS integration connects to OBS Studio via WebSocket to automatically switch scenes based on game state.

​
Configuration

OBS connection settings are configured in your boofstream config: 
{
  "obs": {
    "doSwitch": true,
    "host": "127.0.0.1:4455",
    "password": "your-obs-websocket-password",
    "noGameScene": "Crowd Cam",
    "gameScene": "Melee"
  }
}
​
doSwitch
boolean
Enable automatic scene switching
​
host
string
OBS WebSocket host and port (default: 127.0.0.1:4455)
​
password
string
OBS WebSocket password (set in OBS Tools > WebSocket Server Settings)
​
noGameScene
string
Scene to switch to when no game is active
​
gameScene
string
Scene to switch to when a game starts

​
POST /obs/connect

Connects to OBS Studio via WebSocket.

​
Request

No request body required. Connection settings are read from the config.

​
Response

Returns a simple success response: 
"ok"
HTTP Status: 200 OK

​
Example Request

curl -X POST http://localhost:1337/obs/connect

​
Behavior

  • Connects to ws://{config.obs.host} with the configured password
  • Sets obsConnected state to true immediately
  • Connection failures are handled asynchronously and set obsConnected to false
  • Updates are broadcast to all connected clients via Socket.IO

​
Automatic Scene Switching

When doSwitch is enabled and OBS is connected:
  • Game Start: Switches to gameScene when Slippi detects a game starting
  • Game End: Switches to noGameScene when a game completes

​
Notes

  • Connection errors do not throw - they’re caught and handled silently
  • The endpoint returns success immediately, before confirming the connection
  • Actual connection status is reflected in the obsConnected state field

​
POST /obs/disconnect

Disconnects from OBS Studio.

​
Response

Returns a simple success response: 
"ok"
HTTP Status: 200 OK

​
Example Request

curl -X POST http://localhost:1337/obs/disconnect

​
Behavior

  • Closes the active OBS WebSocket connection
  • Sets obsConnected state to false
  • Safe to call even if not currently connected
  • Updates are broadcast to all connected clients via Socket.IO

​
State Updates

The OBS connection status is reflected in the global state: 
{
  obsConnected: boolean  // true when connected to OBS
}
Query the /state endpoint to check the current connection status: 
curl http://localhost:1337/state

​
Error Handling

Connection errors are handled gracefully:
  • Failed connections set obsConnected to false but don’t throw errors
  • Invalid credentials or wrong port will cause silent connection failures
  • Check the obsConnected state field to verify connection status

​
OBS WebSocket Setup

  1. In OBS Studio, go to Tools > WebSocket Server Settings
  2. Enable the WebSocket server
  3. Set a password (or use without authentication)
  4. Note the port (default: 4455)
  5. Configure these settings in your boofstream config

​
Supported OBS Version

This integration uses obs-websocket-js and supports OBS Studio 28.0+ with WebSocket protocol 5.x.

Build docs developers (and LLMs) love

Get started for freeTalk to us