OBS WebSocket: Automate Your Stream

What Is OBS WebSocket?

OBS WebSocket is a plugin (now built into OBS Studio 28+) that enables remote control of OBS Studio via the WebSocket protocol. It exposes a comprehensive API for programmatically controlling every aspect of OBS �?scenes, sources, filters, transitions, streaming, recording, and more.

Originally a community plugin by Palakis, obs-websocket was so widely adopted that it was merged into OBS Studio core starting with version 28.0 in September 2022. This integration means every OBS installation now includes WebSocket support out of the box, making it the standard interface for automation, remote control, and integration with external tools.

Core Features

API Coverage

The WebSocket API provides complete control over OBS:

• Scenes: List, switch, create, remove, reorder scenes.
• Sources: Get/set properties, visibility, mute state, volume, position, scale.
• Filters: List, add, remove, configure source filters.
• Transitions: Set current transition, configure duration, trigger studio mode.
• Streaming/Recording: Start, stop, toggle, get status.
• Virtual Camera: Start, stop, toggle.
• Replay Buffer: Start, stop, save, get status.
• Hotkeys: Trigger hotkeys by name.
• Events: Subscribe to scene changes, stream status, source updates, and more.

Authentication

• Password Protection: Optional password for WebSocket connections.
• No Authentication: Disable password for local-only connections (default).
• Configuration: Tools �?WebSocket Server Settings �?enable/disable, set port, set password.

Protocol

• WebSocket: Standard WebSocket protocol (RFC 6455).
• JSON Messages: Request/response pattern with typed events.
• Port: Default 4455 (configurable).
• Event Subscriptions: Subscribe to specific event types to reduce bandwidth.

Installation & Setup

OBS 28+ (Built-in)

No installation required. Enable in OBS:

1. Tools �?WebSocket Server Settings.
2. Check “Enable WebSocket server.”
3. Set port (default: 4455).
4. Optionally set a password.
5. Click OK.

OBS 27 and Earlier

Install the plugin manually:

1. Download from github.com/obsproject/obs-websocket/releases.
2. Run installer (Windows) or copy plugin files (macOS/Linux).
3. Restart OBS.
4. Configure in Tools �?WebSocket Server Settings.

Client Libraries

Official and community client libraries are available for multiple languages:

Language	Library	Install
JavaScript/TypeScript	obs-websocket-js	npm install obs-websocket-js
Python	obsws-python	pip install obsws-python
Go	goobs	go get github.com/andreykaipov/goobs
C#	obs-websocket-dotnet	NuGet package
Java	obs-websocket-java	Maven/Gradle
Rust	obws	Cargo crate

Practical Workflows

Stream Deck Integration

The most common use case �?control OBS from an Elgato Stream Deck:

1. Install the Stream Deck software.
2. Add OBS Studio actions to buttons.
3. Configure actions: Switch Scene, Toggle Source, Start/Stop Stream, etc.
4. Create multi-action buttons: Switch to “Gameplay” scene + unmute mic + start stream.
5. Use folders to organize controls by category.

Automated Scene Switching with Python

import obsws_python as obs
import time

client = obs.ReqClient(host='localhost', port=4455)

# Switch to "Starting Soon" scene
client.set_current_program_scene('Starting Soon')

# Wait 5 minutes, then switch to gameplay
time.sleep(300)
client.set_current_program_scene('Gameplay')

# Toggle webcam visibility
client.set_source_enabled('Webcam', False)

# Start recording
client.start_record()

Chat-Controlled Scene Switching

Integrate with Twitch/YouTube chat bots to let viewers control scenes:

1. Set up a chatbot (Streamlabs Chatbot, Nightbot, custom).
2. Configure chat commands: !scene gameplay, !scene brb.
3. Chatbot sends WebSocket command to OBS.
4. OBS switches to requested scene.
5. Add cooldowns and moderator-only restrictions.

MIDI Controller Integration

Use a MIDI controller (like a Korg nanoKONTROL or Behringer X-Touch) as a physical mixing console:

1. Install a MIDI-to-WebSocket bridge (e.g., midi-obs, OBS-MIDI).
2. Map faders to audio source volumes.
3. Map buttons to mute/unmute sources.
4. Map knobs to filter parameters (gain, noise gate threshold).
5. Get tactile control over your stream’s audio mix.

Home Automation Integration

Trigger OBS actions from smart home events:

1. Use Home Assistant with the OBS WebSocket integration.
2. Automations: “When doorbell rings �?switch to doorbell camera scene.”
3. “When stream starts �?dim smart lights to preset brightness.”
4. “When stream ends �?restore lights to normal.”

Community & Ecosystem

Tools Built on OBS WebSocket

• Stream Deck: Hardware control surface with OBS integration.
• Touch Portal: Turn tablets/phones into macro control surfaces.
• LioranBoard: Free Stream Deck alternative with powerful scripting.
• SAMMI: Advanced stream automation with visual programming.
• OBS Blade: Mobile app for monitoring and controlling OBS.
• OBS.Ninja: Bring remote guests into OBS via WebRTC.

Development Resources

• Protocol Documentation: github.com/obsproject/obs-websocket/blob/master/docs/generated/protocol.md
• Client Libraries: github.com/obsproject/obs-websocket#clients
• Examples: Each client library includes example scripts.
• Community Discord: OBS Discord server has a dedicated #plugin-development channel.

Comparison with Paid Alternatives

Feature	OBS WebSocket	Stream Deck	Touch Portal	LioranBoard
Price	Free (built-in)	$149.99 (hardware)	$13.99	Free
API Access	Full (all OBS features)	Limited (pre-built actions)	Limited (pre-built actions)	Good (scripting)
Custom Automation	Unlimited (code)	Limited (multi-actions)	Limited (macros)	Good (visual scripting)
Hardware Required	None	Stream Deck device	Phone/tablet	None
Learning Curve	Steep (programming)	Easy	Easy	Moderate

OBS WebSocket wins on flexibility and cost �?it is the foundation that all other tools build upon. Stream Deck wins for tactile, reliable hardware control. Touch Portal wins for affordable tablet-based control. LioranBoard wins for free visual automation.

Who Should Use OBS WebSocket?

Perfect For

• Streamers using Stream Deck or similar control surfaces
• Developers building custom streaming tools and integrations
• Power users wanting automated scene switching based on conditions
• Multi-PC streaming setups needing remote control
• Anyone integrating OBS with home automation, chatbots, or custom hardware

Not Ideal For

• Streamers who manually switch scenes and are satisfied with hotkeys
• Users who find programming intimidating (use Stream Deck or Touch Portal instead)
• One-time streamers who do not need automation

Verdict

OBS WebSocket transforms OBS Studio from a manual tool into an automatable platform. Its integration into OBS core means every streamer now has access to a complete remote control API without installing anything extra. While the API itself requires programming knowledge to use directly, the ecosystem of tools built on top of it �?Stream Deck, Touch Portal, chatbots �?makes automation accessible to everyone. For any streamer looking to level up their production, enabling and learning OBS WebSocket is one of the highest-impact changes they can make.

Download: Built into OBS Studio 28+. obsproject.com