OBS Studio Web Socket tutorial with examples Python and Javascript

Control OBS Studio 30+ with OBS WebSocket 5.x using Python and JavaScript. Learn setup, scene switching, events, source control, security, and troubleshooting.

By Updated 16 min read
OBS Studio Web Socket tutorial with examples Python and Javascript cover image

Learn how to control OBS Studio 30+ using OBS WebSocket 5.x with Python and JavaScript. Includes setup, scene switching, events, source control, troubleshooting, security tips, and real-world automation examples.

In this complete guide, I will show you how to use the OBS WebSocket 5.x protocol to control OBS Studio with Python and JavaScript. These examples are written for modern OBS Studio versions, including OBS Studio 30+, and are updated for the current WebSocket API used by OBS.

Important: Many older tutorials still use the OBS WebSocket v4.x method SetCurrentScene. That method is no longer correct for modern OBS WebSocket 5.x workflows. In OBS Studio 28 and newer, WebSocket support is built in, the default port is 4455, and the protocol uses JSON-RPC style request names such as SetCurrentProgramScene.

Why Use OBS WebSocket Automation?

OBS Studio is already one of the most powerful tools for livestreaming, screen recording, online teaching, video production, and content creation. Most people use OBS manually by clicking buttons, changing scenes, muting microphones, starting streams, stopping recordings, and enabling or disabling sources from the interface. That works perfectly for basic use, but once your production becomes more advanced, manual control can become limiting.

This is where OBS WebSocket becomes extremely useful. OBS WebSocket allows external applications, scripts, browser dashboards, Twitch bots, stream decks, automation tools, and custom control panels to communicate with OBS Studio in real time. Instead of clicking everything manually, you can send commands to OBS from code.

With OBS WebSocket, you can change scenes automatically, show or hide overlays, monitor streaming status, react to scene changes, mute audio sources, trigger media playback, update text sources, and build advanced production workflows. This is especially useful for streamers, developers, churches, podcasts, sports productions, online events, remote operators, and anyone who wants to make OBS behave like a programmable broadcast system.

In this article, I will focus on practical examples using Python and JavaScript. Python is excellent for simple automation scripts, local tools, scheduled tasks, and backend workflows. JavaScript is ideal for web dashboards, Node.js apps, Twitch bots, browser-based control panels, and interactive stream tools.

OBS WebSocket turns OBS Studio from a manual broadcasting tool into a programmable production environment that can react to code, events, buttons, chat commands, APIs, and external systems.

What Is OBS WebSocket 5.x?

OBS WebSocket is a control interface that allows other applications to connect to OBS Studio over a WebSocket connection. A WebSocket is a persistent communication channel between two applications. In this case, your script or app connects to OBS, authenticates with a password, and sends requests.

OBS WebSocket 5.x is the modern version of this API. It replaced the older v4.x protocol and introduced different request names, better structure, more consistent event handling, and improved compatibility with newer OBS versions. This is why old tutorials can be confusing. A script written for OBS WebSocket v4.x may fail even if your connection settings are correct.

For example, older examples often use: 

SetCurrentScene

In OBS WebSocket 5.x, the correct request for changing the live program scene is: 

SetCurrentProgramScene

This distinction matters because OBS Studio has different concepts such as preview scenes and program scenes, especially when Studio Mode is enabled. The program scene is the scene currently live/outputting to the stream or recording. The preview scene is the scene being prepared before transition when Studio Mode is active.

If you only want to switch what viewers currently see, you usually want SetCurrentProgramScene.

Prerequisites

Before writing any automation code, make sure your OBS setup is ready. You need a modern version of OBS Studio. OBS WebSocket became built into OBS Studio starting with OBS 28, so if you are using OBS 28, 29, 30, or newer, you do not need to install the old standalone WebSocket plugin.

For best results, I recommend using a current stable OBS Studio version. Newer versions include security improvements, bug fixes, encoder updates, and better compatibility with modern plugins and APIs.

You will need:

  • OBS Studio 28 or newer, preferably OBS Studio 30+.
  • WebSocket server enabled inside OBS.
  • A secure WebSocket password.
  • Python if you want to use Python examples.
  • Node.js if you want to use JavaScript examples.
  • Basic knowledge of scenes and sources in OBS.

You also need to install the client libraries used in this guide.

Python Library

For Python, install obsws-python: 

pip install obsws-python

JavaScript Library

For JavaScript or Node.js, install obs-websocket-js: 

npm install obs-websocket-js

These libraries make it much easier to work with OBS WebSocket because they handle the connection process, authentication, requests, responses, and event subscriptions in a developer-friendly way.

Setting Up OBS WebSocket

To enable the WebSocket server, open OBS Studio and go to: 

Tools → WebSocket Server Settings

In this window, enable the WebSocket server. The default port is usually 4455. Unless you have a specific reason to change it, I recommend keeping this default port because most modern OBS WebSocket examples and tools expect it.

Next, enable authentication and set a strong password. Authentication is very important because OBS WebSocket can control your entire OBS session. Anyone with access to the WebSocket server and password could potentially switch scenes, stop your stream, start recording, hide sources, change audio states, or interfere with your production.

After enabling the server and setting your password, click Apply and then OK. OBS should now be ready to accept WebSocket connections from local scripts or applications.

Tip: Keep OBS WebSocket restricted to localhost for local automation whenever possible. Only expose it to a network or the internet if you fully understand the security risks.

Understanding the Connection Details

Most local OBS WebSocket scripts use the following connection details:

  • Host: localhost
  • Port: 4455
  • Password: the password you configured in OBS

The host localhost means the script is running on the same computer as OBS Studio. This is the safest and simplest setup.

If you want another computer on your local network to control OBS, you need to use the OBS machine’s local IP address instead of localhost. You may also need firewall rules that allow access to port 4455. However, for beginners, I strongly recommend starting with local-only access.

A typical JavaScript WebSocket URL looks like this: 

ws://localhost:4455

The ws:// prefix means a normal WebSocket connection. If you expose OBS WebSocket through a secure reverse proxy, you may use wss://, but that is an advanced setup and should be handled carefully.

Python: Change the Current OBS Scene

Python is one of the easiest ways to automate OBS Studio. It is simple, readable, and works well for quick scripts. I often use Python when I want to trigger OBS actions from local tools, scheduled tasks, hardware buttons, monitoring scripts, or small desktop utilities.

Here is a basic Python example that connects to OBS and changes the current program 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()

Replace your_password with your actual OBS WebSocket password. Replace YourSceneName with the exact name of your OBS scene. Scene names are case-sensitive, so Starting Soon and starting soon are treated as different names.

This script performs four basic actions:

  • Creates a WebSocket client.
  • Connects to OBS Studio.
  • Sends a request to change the current program scene.
  • Disconnects from OBS.

This is a good starting point because scene switching is one of the most common automation tasks. Once this works, you can expand the same pattern to control sources, audio, streaming, recording, transitions, and more.

Python: Safer Version with Error Handling

The previous Python example is intentionally simple. For real projects, I recommend adding basic error handling so your script does not fail silently or leave you wondering what went wrong. 

from obsws_python import obsws, requests

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

ws = obsws(host, port, password)

try:
    ws.connect()
    ws.call(requests.SetCurrentProgramScene(scene_name))
    print(f"Changed OBS scene to: {scene_name}")
except Exception as error:
    print(f"OBS WebSocket error: {error}")
finally:
    try:
        ws.disconnect()
    except Exception:
        pass

This version is better for practical use because it catches connection errors, authentication errors, invalid request errors, and scene name problems. If the scene does not exist or the password is wrong, you will see an error message in the terminal.

For production automation, you can also add logging, retries, configuration files, command-line arguments, or environment variables for the password. Avoid hardcoding passwords in scripts that you plan to publish or share.

JavaScript: Change the Current OBS Scene

JavaScript is a great choice when you want to build web dashboards, Node.js tools, browser-based control panels, Twitch bots, Discord bots, or custom interfaces for stream production.

Here is a simple Node.js example using obs-websocket-js: 

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 successfully.');

    await obs.disconnect();
  } catch (err) {
    console.error('OBS WebSocket Error:', err);
  }
}

changeScene();

This example connects to OBS, authenticates with your password, sends the SetCurrentProgramScene request, and disconnects. It uses async and await because WebSocket operations are asynchronous.

JavaScript is especially useful if you want to build a control panel with buttons such as Starting Soon, Gameplay, Be Right Back, and Ending. Each button can call OBS WebSocket and switch scenes instantly.

JavaScript: Simple Scene Switcher Function

If you are building a larger Node.js app, it is cleaner to create reusable functions instead of writing all logic in one place. 

import OBSWebSocket from 'obs-websocket-js';

const obs = new OBSWebSocket();

async function connectObs() {
  await obs.connect('ws://localhost:4455', 'your_password');
}

async function switchScene(sceneName) {
  await obs.call('SetCurrentProgramScene', { sceneName });
  console.log(`Switched to scene: ${sceneName}`);
}

async function main() {
  try {
    await connectObs();

    await switchScene('Starting Soon');

    setTimeout(async () => {
      await switchScene('Gameplay');
      await obs.disconnect();
    }, 5000);
  } catch (error) {
    console.error('OBS automation failed:', error);
  }
}

main();

This script connects to OBS, switches to a Starting Soon scene, waits 5 seconds, and then switches to a Gameplay scene. This is a simple example, but the same idea can be expanded into timed intros, event sequences, automatic breaks, or stream startup routines.

Listening for OBS Events

OBS WebSocket is not only useful for sending commands. It can also listen for events. Events are notifications sent by OBS when something changes. This makes it possible to build reactive systems that respond automatically to OBS state changes.

For example, you can listen for scene changes, stream state changes, recording state changes, source visibility changes, input mute changes, replay buffer state changes, and more. 

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

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

obs.on('RecordStateChanged', state => {
  console.log(`Recording active: ${state.outputActive}`);
});

Event listeners are extremely useful when you want another application to know what OBS is doing. For example, a dashboard can update its active scene button when the scene changes. A Twitch bot can post a message when the stream starts. A local app can start logging when recording begins.

This is one of the biggest advantages of OBS WebSocket. It allows two-way communication: your app can control OBS, and OBS can report changes back to your app.

Advanced OBS WebSocket Use Cases

Once basic scene switching works, you can start controlling more detailed OBS features. This is where automation becomes much more powerful.

Toggle Source Visibility

You can show or hide specific sources inside a scene. This is useful for overlays, alerts, webcam frames, sponsor banners, stream labels, lower thirds, countdown timers, and temporary graphics. 

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

The important detail here is sceneItemId. In OBS WebSocket 5.x, many source operations require the scene item ID, not just the source name. A source can appear multiple times in different scenes, so OBS needs to know exactly which scene item you want to control.

Get the Scene List

You can request all available scenes from OBS: 

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

This is useful when building dynamic dashboards. Instead of hardcoding scene names, your app can load the current scene list from OBS and generate buttons automatically.

Get Scene Item IDs

To toggle sources reliably, first request the items inside a scene: 

const items = await obs.call('GetSceneItemList', {
  sceneName: 'YourSceneName'
});

console.log(items.sceneItems);

The response contains scene items and their IDs. You can use those IDs with SetSceneItemEnabled to show or hide the correct item.

Controlling Audio Sources

OBS WebSocket can also control audio. This is useful for muting microphones, enabling desktop audio, switching between commentary and break music, or creating automated production states.

Mute an Audio Input

await obs.call('SetInputMute', {
  inputName: 'Mic/Aux',
  inputMuted: true
});

Unmute an Audio Input

await obs.call('SetInputMute', {
  inputName: 'Mic/Aux',
  inputMuted: false
});

Check If an Input Is Muted

const muteState = await obs.call('GetInputMute', {
  inputName: 'Mic/Aux'
});

console.log(muteState.inputMuted);

Audio automation is very useful for professional workflows. For example, when switching to a break scene, your script could mute the microphone and enable music. When switching back to gameplay, it could unmute the microphone and lower the music volume.

Starting and Stopping Streaming or Recording

OBS WebSocket can control output states such as streaming and recording. This allows you to create custom start buttons, automated recording workflows, or remote production tools.

Start Streaming

await obs.call('StartStream');

Stop Streaming

await obs.call('StopStream');

Start Recording

await obs.call('StartRecord');

Stop Recording

await obs.call('StopRecord');

Be careful with these commands. Accidentally stopping a stream or recording during a live production can cause serious problems. For important workflows, add confirmation dialogs, permissions, or safeguards in your own control app.

Program Scene vs Preview Scene

One common source of confusion in OBS WebSocket 5.x is the difference between the program scene and the preview scene.

The program scene is the scene currently live. This is what your viewers see on stream or what is being recorded.

The preview scene is mainly used when OBS Studio Mode is enabled. It allows you to prepare a scene before transitioning it live.

To change the live scene directly, use: 

SetCurrentProgramScene

To work with preview scenes in Studio Mode, you need preview-related requests. This distinction is important when building production panels. A basic streamer dashboard may only need program scene switching, while a more advanced broadcast control panel may need preview selection and transition execution.

Real-World Applications

OBS WebSocket can be used in many real-world scenarios. It is not limited to simple scene switching. Once you understand the request and event system, you can integrate OBS with almost anything.

Here are practical examples:

  • Twitch bots: Change scenes, trigger alerts, or show overlays based on chat commands.
  • Stream dashboards: Build a custom web panel with buttons for scenes, sources, audio, recording, and stream controls.
  • Game event triggers: React to game state changes and update overlays automatically.
  • Podcast production: Switch camera angles, mute guests, or start recording from a custom interface.
  • Church livestreams: Allow a volunteer to control lower thirds, scenes, and cameras from a simplified interface.
  • Online events: Automate intros, speaker scenes, sponsor slides, break screens, and ending screens.
  • Education and tutorials: Automatically switch between webcam, screen share, slides, and demonstration scenes.
  • Remote control: Let a producer control OBS from another device on the local network.

In my experience, the best OBS automation tools are not the most complicated ones. They are the ones that remove repetitive actions and reduce mistakes during live production.

Security Tips

OBS WebSocket is powerful, so it must be secured properly. If someone gains unauthorized access to your WebSocket server, they may be able to control OBS. That means they could change scenes, stop your stream, start recording, mute audio, or interfere with your live production.

  • Always use a strong password.
  • Do not expose OBS WebSocket to the public internet without protection.
  • Use localhost for local-only scripts whenever possible.
  • Use firewall rules if allowing local network access.
  • Restrict access by IP address when controlling OBS remotely.
  • Do not publish your WebSocket password in GitHub repositories.
  • Store passwords in environment variables for serious projects.
  • Keep OBS Studio and client libraries updated.
  • Use a secure reverse proxy only if you understand WSS and authentication.

For most creators, the safest setup is simple: keep OBS WebSocket enabled only for local connections and connect from scripts running on the same computer.

Common Errors and Fixes

OBS WebSocket automation is usually reliable, but beginners often run into a few common problems. Most of them are easy to fix once you know what to check.

Connection Refused

This usually means your script cannot reach the OBS WebSocket server.

  • Make sure OBS Studio is running.
  • Make sure the WebSocket server is enabled.
  • Confirm the port is 4455.
  • Check firewall settings.
  • Use localhost if the script runs on the same PC.

Authentication Failed

This means the connection reached OBS, but the password was incorrect.

  • Re-enter the password in OBS WebSocket settings.
  • Update the password in your script.
  • Check for extra spaces or wrong characters.

Invalid Request

This often happens when using old OBS WebSocket v4.x method names with the modern v5.x API.

  • Use SetCurrentProgramScene instead of SetCurrentScene.
  • Check that the request name exists in OBS WebSocket 5.x.
  • Make sure your client library is updated.

Scene Not Found

OBS scene names are case-sensitive. Make sure the scene name in your script exactly matches the scene name inside OBS.

  • Check uppercase and lowercase letters.
  • Check spaces and special characters.
  • Use GetSceneList to list available scene names.

Source Does Not Toggle

In OBS WebSocket 5.x, source visibility often requires the correct sceneItemId. The source name alone may not be enough.

  • Use GetSceneItemList first.
  • Find the correct sceneItemId.
  • Pass that ID to SetSceneItemEnabled.

Best Practices for OBS WebSocket Projects

If you plan to build a serious OBS automation project, it is worth following a few best practices from the beginning. This will make your code easier to maintain and safer during live productions.

  • Use clear scene names: Avoid confusing names like Scene 1 or New Scene 2.
  • Handle errors properly: Always log connection and request errors.
  • Do not hardcode secrets: Store passwords outside public source code.
  • Test before going live: Never test new automation for the first time during an important stream.
  • Add safeguards: Use confirmations for dangerous actions like stopping a stream.
  • Keep dependencies updated: OBS and client libraries can change over time.
  • Build small first: Start with scene switching before adding advanced controls.
  • Use events wisely: Event-driven dashboards feel much more responsive and accurate.

Good OBS automation should make production easier, not more fragile. The goal is to reduce manual work and avoid mistakes, not create a system that becomes difficult to operate under pressure.

Example Automation Workflow

A practical OBS automation workflow might look like this:

  1. Connect to OBS WebSocket.
  2. Check the current streaming and recording state.
  3. Switch to the Starting Soon scene.
  4. Start streaming.
  5. Wait for the intro countdown to finish.
  6. Switch to the Main scene.
  7. Enable the microphone.
  8. Listen for scene changes and update a dashboard.
  9. Switch to BRB during breaks.
  10. Switch to Ending before stopping the stream.

This kind of workflow can save time and reduce stress. Instead of manually clicking multiple buttons, one script or dashboard button can execute a complete sequence consistently every time.

Useful Resources

When building OBS WebSocket tools, it is useful to keep official references and library documentation nearby. Method names, request fields, and event names must match the current protocol, so guessing usually leads to errors.

Conclusion

OBS WebSocket 5.x makes OBS Studio far more flexible than a normal manual broadcasting application. With WebSocket control, OBS can become part of a larger automated workflow that reacts to scripts, dashboards, chat commands, events, APIs, buttons, timers, and external tools.

The most important thing to remember is that modern OBS versions use the WebSocket 5.x API. Old v4.x examples may not work correctly, especially if they use methods such as SetCurrentScene. For changing the live scene in modern OBS, use SetCurrentProgramScene.

Python is a great option for small automation scripts and local production tools. JavaScript is a strong choice for Node.js apps, web dashboards, Twitch bots, and interactive control panels. Both approaches can connect to OBS, send commands, listen for events, and build real-time production workflows.

Start simple. First connect to OBS, then change a scene, then listen for an event, then control a source. Once those basics are working, you can build more advanced tools such as full stream control panels, automated intro sequences, audio routing helpers, remote production systems, or custom livestream dashboards.

OBS WebSocket is one of the best ways to make your stream or production more professional, consistent, and automated. With the examples in this guide, you now have a strong foundation for controlling OBS Studio with Python and JavaScript using the modern WebSocket 5.x protocol.

View all →