Skip to main content

​
Overview

boofstream connects to OBS via the WebSocket protocol to enable automatic scene switching. Connection problems usually involve incorrect host/port settings, wrong passwords, or OBS WebSocket not being enabled.
You must have the OBS WebSocket plugin installed and enabled. OBS Studio 28.0+ includes WebSocket support by default.

​
Common OBS Problems

Symptoms: Connection to OBS fails immediately or times out.Solutions:
  1. Verify OBS is running
    • OBS Studio must be open before connecting
    • The WebSocket server only runs while OBS is active
  2. Check WebSocket settings in OBS
    • In OBS: Tools → WebSocket Server Settings
    • Verify “Enable WebSocket server” is checked
    • Note the server port (default: 4455)
    • Check if “Enable Authentication” is on and note the password
  3. Confirm host and port in boofstream
    • Default host: 127.0.0.1:4455
    • In boofstream: Settings → OBS Settings
    • Verify host matches OBS (format: IP:PORT)
    • If you changed OBS WebSocket port, update it here
The default OBS WebSocket configuration is 127.0.0.1:4455 with no password (source: /home/daytona/workspace/source/boofstream/index.ts:67-72)
Symptoms: Connection fails with authentication error.How to fix:
1

Find your OBS WebSocket password

In OBS Studio:
  1. Go to Tools → WebSocket Server Settings
  2. Check if “Enable Authentication” is enabled
  3. Note the password (you may need to click “Show password”)
  4. If no password is set, disable authentication or leave the password field empty in boofstream
2

Update boofstream password

In boofstream:
  1. Open Settings → OBS Settings
  2. Enter the password in the password field
  3. Click Save
3

Test the connection

After saving, click connect to OBS to verify the password works.
You must click Save before attempting to connect. The connect button is disabled if you have unsaved changes (source: /home/daytona/workspace/source/boofstream-manager/src/components/config/OBSSubConfigModal.tsx:64-67)
Symptoms: Connection times out or “connection refused” error.Troubleshooting:
  1. Verify the WebSocket port in OBS
    • Default port: 4455
    • In OBS: Tools → WebSocket Server Settings
    • Note the “Server Port” value
  2. Check if OBS is on the same machine
    • If OBS is on the same computer as boofstream: use 127.0.0.1:4455
    • If OBS is on a different computer: use the IP address of that computer
    • Format: IP_ADDRESS:PORT (e.g., 192.168.1.100:4455)
  3. Update host in boofstream
    • Settings → OBS Settings
    • Update the host field
    • Click Save
  4. Check firewall settings
    • If connecting to OBS on another computer, ensure the firewall allows WebSocket connections on port 4455
    • Add an exception for OBS WebSocket if needed
Symptoms: Connected to OBS but scenes don’t switch automatically during games.Possible causes:
  1. Automatic switching is disabled
    • In boofstream: Settings → OBS Settings
    • Check “automatically switch between scenes when game starts/ends”
    • This must be enabled for automatic scene switching
  2. Scene names don’t match
    • boofstream switches to specific scene names you configure
    • ingame scene name: Scene to show during games (e.g., “Melee”)
    • no game / crowd cam scene name: Scene when no game is active (e.g., “Crowd Cam”)
    • These names must EXACTLY match scene names in OBS (case-sensitive)
  3. Verify scene names in OBS
    • Check the “Scenes” panel in OBS
    • Note the exact names of your game and non-game scenes
    • Update boofstream settings to match exactly
  4. Slippi not connected
    • Scene switching only works when connected to Slippi
    • boofstream switches scenes based on game start/end events from Slippi
    • Ensure Slippi connection is active
Scene switching happens automatically: game scene when a match starts, no-game scene when a match ends (source: /home/daytona/workspace/source/boofstream/index.ts:411-413, 430-434)
Symptoms: The connect button is disabled or grayed out.Why this happens:boofstream requires you to save any configuration changes before attempting to connect to OBS. This ensures the connection uses your latest settings.How to fix:
  1. Make your changes to OBS settings
  2. Click the Save button
  3. The connect to OBS button will become enabled
  4. Click to connect with your new settings
Technical details:The connect button is disabled when:
  • doSwitch value has changed
  • host value has changed
  • password value has changed
  • gameScene name has changed
  • noGameScene name has changed
The button shows the message: “you must save before connecting”
Symptoms: OBS connection drops during use.Troubleshooting:
  1. Check if OBS is still running
    • If OBS closes or crashes, the WebSocket connection will drop
    • Restart OBS and reconnect from boofstream
  2. Network stability
    • If OBS is on a different computer, check network connectivity
    • Use a wired connection for more stability
  3. OBS WebSocket settings
    • Ensure the WebSocket server is still enabled in OBS
    • Verify no settings changed in OBS that would affect the connection
  4. Reconnect manually
    • In boofstream: Settings → OBS Settings
    • Click connect to OBS
    • The connection is not automatic after disconnection

​
OBS WebSocket Setup

If you haven’t set up OBS WebSocket yet:
1

Check your OBS version

OBS Studio 28.0 and later includes WebSocket support built-in. If you’re using an older version, update to the latest OBS Studio.
2

Enable WebSocket in OBS

  1. Open OBS Studio
  2. Go to Tools → WebSocket Server Settings
  3. Check “Enable WebSocket server”
  4. Note the port (usually 4455)
  5. Optionally enable authentication and set a password
  6. Click OK
3

Configure boofstream

  1. In boofstream: Settings → OBS Settings
  2. Set host to 127.0.0.1:4455 (or your custom port)
  3. Enter password if you set one in OBS
  4. Set your ingame scene name (e.g., “Melee”)
  5. Set your no game / crowd cam scene name (e.g., “Crowd Cam”)
  6. Check “automatically switch between scenes when game starts/ends”
  7. Click Save
4

Connect

Click connect to OBS to establish the connection.
For more information about OBS WebSocket, see the official OBS remote control guide.

​
Technical Details

​
Connection Process

boofstream connects to OBS using:
  1. WebSocket protocol at ws://HOST (e.g., ws://127.0.0.1:4455)
  2. Authentication with the configured password
  3. Scene switching via SetCurrentProgramScene calls

​
Default Configuration

{
  "obs": {
    "doSwitch": false,
    "host": "127.0.0.1:4455",
    "password": "",
    "noGameScene": "Crowd Cam",
    "gameScene": "Melee"
  }
}

​
Connection States

  • Connected: Active WebSocket connection to OBS
  • Disconnected: No connection to OBS
Connection status is shown in the OBS settings modal and stored in state.obsConnected.

​
Still Having Issues?

If you’ve tried all the troubleshooting steps above:

Common Issues

General troubleshooting tips and how to report bugs

GitHub Issues

Search existing issues or report a new problem

Build docs developers (and LLMs) love

Get started for freeTalk to us