Skip to main content
Boofstream can automatically switch your OBS scenes based on game state, making it easy to show gameplay when a match is active and switch to a camera or crowd view between games.

​
How It Works

The scene switching feature connects to OBS via WebSocket and listens for game start and end events from Slippi:

Game Scene

Automatically switches when a game begins

No-Game Scene

Switches back when the game ends

​
Game Start Detection

When a game starts, boofstream switches to your configured game scene: 
realtime.game.start$.subscribe(e => {
    // Capture game data...

    if (state.obsConnected && config.obs.doSwitch) {
        scene(config.obs.gameScene);
    }
});

​
Game End Detection

When a game ends, boofstream switches to your no-game scene: 
livestream.gameEnd$.subscribe(e => {
    if (state.obsConnected && config.obs.doSwitch) {
        scene(config.obs.noGameScene);
    }
    
    // Handle scoring...
});
Scene switching respects LRAS game resets - the scene won’t flicker when players restart a game quickly.

​
OBS WebSocket Connection

Boofstream uses the obs-websocket-js library to communicate with OBS: 
const obs = new OBSWebSocket();

function scene(sceneName: string) {
    obs.call("SetCurrentProgramScene", { sceneName });
}

​
Connection Setup

Connect to OBS with your configured settings: 
app.post("/obs/connect", (_, res) => {
    obs.connect(`ws://${config.obs.host}`, config.obs.password)
        .catch(() => {
            state.obsConnected = false;
            writeState();
            io.emit("update_state", "system");
        });

    state.obsConnected = true;
    writeState();
});
OBS must have the WebSocket plugin enabled and accessible. By default, boofstream connects to 127.0.0.1:4455.

​
Configuration Options

Scene switching behavior is controlled by your boofstream config: 
config: {
    obs: {
        doSwitch: false,              // Enable/disable automatic switching
        host: "127.0.0.1:4455",       // OBS WebSocket address
        password: "",                 // WebSocket password (if set)
        noGameScene: "Crowd Cam",     // Scene to show between games
        gameScene: "Melee",           // Scene to show during games
    }
}

doSwitch

Master toggle for automatic scene switching

host

OBS WebSocket server address and port

password

Authentication password if WebSocket is secured

Scene Names

Exact names of scenes to switch between
Scene names in the config must exactly match your OBS scene names, including capitalization and spacing.

​
Connection Status

Boofstream tracks OBS connection status in the application state: 
state: {
    obsConnected: false,  // true when connected to OBS
    // ...
}
The UI displays connection status, and scene switching only occurs when obsConnected is true.

​
User Workflow

​
Initial Setup

  1. Enable OBS WebSocket: In OBS, go to Tools → WebSocket Server Settings
  2. Configure boofstream: Enter your OBS host, password, and scene names
  3. Connect: Click “Connect to OBS” in the boofstream UI
  4. Test: Start a game to verify scene switching works

​
During Streaming

  1. Enable Switching: Toggle “Auto Switch Scenes” in settings
  2. Game Starts: OBS automatically switches to your game scene
  3. Game Ends: OBS switches back to your no-game scene
  4. Manual Override: You can still manually switch scenes in OBS
Scene switching happens instantly when game state changes, typically within 1-2 frames of the game starting or ending.

​
Common Use Cases

Tournament Streams

Switch from crowd/player cam to gameplay automatically

Netplay Sets

Show your facecam between games, hide during matches

Commentary Focus

Display commentators between games, full gameplay during

Multi-Setup Events

Reduce production workload by automating scene changes

​
Troubleshooting

​
Connection Issues

If OBS won’t connect:
  • Verify WebSocket server is enabled in OBS
  • Check that the host and port match your OBS settings
  • Ensure the password is correct (if you set one)
  • Try restarting both OBS and boofstream

​
Scene Not Switching

If scenes don’t change:
  • Confirm doSwitch is enabled in config
  • Verify scene names exactly match OBS scene names
  • Check that obsConnected shows as true in the UI
  • Look for connection errors in the boofstream console
You can disable automatic scene switching at any time without disconnecting from OBS by toggling the doSwitch setting.

Build docs developers (and LLMs) love

Get started for freeTalk to us