OBS Studio Web Socket tutorial with examples Python and Javascript

Prerequisites

• OBS Studio 28+ (WebSocket v5.x is built-in, no plugin needed).
• Enable the WebSocket server under Tools → WebSocket Server Settings.
• Client libraries:
  • pip install obsws-python
  • npm install obs-websocket-js

Setting Up OBS WebSocket

1. Go to Tools → WebSocket Server Settings in OBS.
2. Enable the server.
3. Default port is 4455 (WebSocket v5).
4. Set a secure password & enable authentication.
5. Click Apply → OK.

Python: Change Scene

from obsws_python import obsws, requests

host = "localhost"
port = 4455
password = "your_password"

ws = obsws(host, port, password)
ws.connect()

scene_name = "YourSceneName"
ws.call(requests.SetCurrentProgramScene(scene_name))

ws.disconnect()
      

This script connects, authenticates, and switches the program scene in OBS.

JavaScript: Change Scene

import OBSWebSocket from 'obs-websocket-js';

const obs = new OBSWebSocket();

async function changeScene() {
  try {
    await obs.connect('ws://localhost:4455', 'your_password');
    await obs.call('SetCurrentProgramScene', { sceneName: 'YourSceneName' });
    console.log('Scene changed!');
    await obs.disconnect();
  } catch (err) {
    console.error('OBS WebSocket Error:', err);
  }
}

changeScene();
      

Listening for Events

obs.on('CurrentProgramSceneChanged', data => {
  console.log(`Scene changed to: ${data.sceneName}`);
});

obs.on('StreamStateChanged', state => {
  console.log(`Streaming: ${state.outputActive}`);
});
      

Events allow you to build reactive dashboards and bots that sync with OBS actions.

Advanced Examples

Toggle Source Visibility

await obs.call('SetSceneItemEnabled', {
  sceneName: 'YourSceneName',
  sceneItemId: 3,
  sceneItemEnabled: true
});
      

Get Scene List

const scenes = await obs.call('GetSceneList');
console.log(scenes.scenes);
      

Security Tips

• Always use a strong password.
• Restrict to localhost unless remote access is needed.
• Use WSS + reverse proxy (NGINX) if exposed online.
• Firewall/IP whitelist where possible.
• Keep OBS & libraries up to date.

Common Errors

• Connection refused: Enable server in OBS, check firewall/port 4455.
• Auth failed: Password mismatch.
• Invalid request: Use v5 method names (SetCurrentProgramScene not SetCurrentScene).
• Scene not found: Scene names are case-sensitive.
• Crashes: Update OBS + client SDK.

Real-World Uses

• Twitch bots that switch scenes on chat commands.
• Game event triggers that update overlays in real time.
• Remote control panels for team productions.
• Automated production pipelines with scheduled scene changes.

Conclusion

The OBS WebSocket 5.x API is now stable and built-in, making automation easier than ever. With obs-websocket-js and obsws-python, you can build bots, dashboards, and production tools with full control of OBS Studio.

Resources:

• Protocol Reference
• obs-websocket-js
• obsws-python
• OBS Discord