OBS WebSocket Automation: What It Is and How to Use It

What Is OBS WebSocket?

OBS WebSocket is a protocol built into OBS Studio (since version 28) that lets external programs control OBS over a local network connection. Any tool that speaks the WebSocket protocol can connect to OBS and do everything you can do manually — switch scenes, show/hide sources, start/stop recording, adjust audio, apply filters, and more.

Think of it as a remote control API for OBS. Instead of clicking buttons in the OBS interface, a program sends JSON commands over a WebSocket connection. OBS executes them instantly and sends back results.

This is the foundation for all OBS automation tools. Streamer.bot, Touch Portal, Stream Deck software, VPE, and dozens of other tools all use WebSocket to control OBS. If you've ever used any external tool that controls OBS, it was using this protocol.

How to Enable OBS WebSocket

OBS 28 and later include WebSocket v5 out of the box — no plugin install needed. Here's how to enable it:

Open OBS Studio. Go to Tools > WebSocket Server Settings. Check 'Enable WebSocket server'. Set a Server Password (strongly recommended). Note the Server Port (default: 4455). Click Apply.

That's it. OBS is now listening for WebSocket connections on localhost:4455. Any tool on your machine can connect using that port and password.

If you're on OBS 27 or earlier, you need to install the obs-websocket plugin manually from the OBS plugin directory. But realistically, you should update OBS — version 30+ is stable and has significant performance improvements.

What You Can Control via WebSocket

Scenes: switch active scenes, get the current scene, list all scenes. This is the most common automation use case — switching scenes based on external triggers.

Sources: show/hide sources, change source properties (position, size, crop), get source screenshots. This is how overlays, alerts, and dynamic layouts work.

Audio: mute/unmute sources, set volume levels, get audio monitoring status. Useful for automated audio ducking or source-specific volume control.

Recording and streaming: start/stop recording, start/stop streaming, save replay buffer, get recording/streaming status. This is how auto-clip tools trigger clip saves.

Filters: enable/disable filters, change filter settings. Used for dynamic visual effects — changing color correction, blur intensity, or shader parameters in real time.

Transitions: set the active transition, trigger a transition, configure transition duration. Controls how scene switches look — cuts, fades, stingers.

WebSocket v5 vs. v4 — What Changed

If you've seen older tutorials referencing obs-websocket 4.x, that's the legacy version. OBS 28+ uses WebSocket v5, which is a complete rewrite with a different message format.

Key differences: v5 uses a structured request/response format with unique message IDs. Every request gets a response confirming success or failure. v4 used a simpler fire-and-forget model that could silently fail.

v5 also adds event subscriptions — your tool can subscribe to specific event types (scene changes, source visibility changes, recording state changes) and get notified in real time. This means tools don't need to poll OBS for status updates.

If a tool says it supports 'obs-websocket' without specifying the version, check whether it supports v5. Most actively maintained tools have updated. Abandoned tools may still require v4, which means installing the legacy plugin alongside the built-in v5 server.

Connecting to OBS WebSocket — Practical Examples

Connection flow: open a WebSocket connection to ws://localhost:4455, authenticate with your password (OBS uses a challenge-response auth), then start sending requests.

Switching scenes: send a SetCurrentProgramScene request with the scene name. OBS switches immediately. Response confirms success. Total round-trip: under 10ms on localhost.

Showing/hiding a source: send SetSceneItemEnabled with the scene name, source ID, and enabled (true/false). The source appears or disappears instantly on stream.

Saving a replay buffer clip: send SaveReplayBuffer. OBS saves the buffer contents to your configured output path. This is exactly what auto-clip tools do when they detect a highlight moment.

Listening for events: subscribe to SceneTransitionStarted, InputVolumeChanged, or any other event type. OBS pushes notifications when these happen — your tool reacts without polling.

// Example: Switch scene via WebSocket v5
{
  "op": 6,
  "d": {
    "requestType": "SetCurrentProgramScene",
    "requestId": "switch-1",
    "requestData": {
      "sceneName": "Gameplay"
    }
  }
}

Tools That Use OBS WebSocket

Streamer.bot: event-driven automation. Listens for Twitch/YouTube events and triggers OBS actions via WebSocket. Free, powerful, requires scripting for advanced use.

Touch Portal / Stream Deck: hardware and software control panels. Each button sends a WebSocket command to OBS. Great for manual control without memorizing hotkeys.

Advanced Scene Switcher: OBS plugin that uses internal OBS APIs (not WebSocket), but achieves similar automation within OBS itself. Good for standalone scene switching without external tools.

VPE: full stream automation. Connects to OBS via WebSocket and controls scenes, sources, effects, and clips based on real-time stream analysis. Handles the full production pipeline — not just individual commands.

Custom scripts: if you can write code, you can build your own OBS controller. Libraries exist for Python (obsws-python), JavaScript (obs-websocket-js), C# (OBSWebsocket.NET), and most other languages.

Common WebSocket Issues and Fixes

Connection refused: OBS WebSocket isn't enabled, or the port is wrong. Check Tools > WebSocket Server Settings and verify the port number. Default is 4455 for v5.

Authentication failed: wrong password. The password is case-sensitive. Copy it directly from OBS settings rather than retyping it.

Commands work but nothing happens on stream: you might be controlling the wrong scene. WebSocket operates on the 'Program' output by default. If you're in Studio Mode, make sure you're targeting the correct output.

Lag between command and action: on localhost, WebSocket commands execute in under 10ms. If you're seeing lag, the delay is in the tool sending the command, not in OBS processing it. Check your tool's event processing pipeline.

v4 commands not working: if you upgraded from OBS 27 to 28+, the WebSocket protocol changed. v4 commands won't work on the v5 server. Update your tools or install the legacy v4 plugin alongside v5.

Frequently Asked Questions

Can I control OBS from another computer on my network? Yes. Change the WebSocket bind address from localhost to 0.0.0.0 in OBS settings. Then connect from any machine on your LAN using your computer's IP address. Use a strong password — anyone on your network could connect otherwise.

Does WebSocket add latency to my stream? No. WebSocket commands execute locally in under 10ms. The connection is between processes on the same machine. There's no network latency, encoding delay, or buffering involved.

Can multiple tools connect to OBS WebSocket at the same time? Yes. OBS supports multiple simultaneous WebSocket connections. Streamer.bot, VPE, and a Stream Deck can all be connected at once. Just be careful that two tools don't send conflicting commands (like switching to different scenes simultaneously).

Is OBS WebSocket secure? On localhost, it's as secure as any other local process communication. The password prevents unauthorized connections. If you expose it to your network, use a strong password and consider firewall rules.

Do I need to know programming to use WebSocket? No — for using existing tools like Streamer.bot or VPE, you just enter the port and password in the tool's settings. Programming is only needed if you want to build custom integrations.