OBS WebSocket is a Remote Procedure Call (RPC) protocol that lets external applications control OBS Studio over a WebSocket connection. It enables developers to switch scenes, start and stop streams, manage sources, and automate streaming workflows programmatically. The protocol uses a structured message system with OpCodes for identification, requests, and events, supporting both JSON and MessagePack encoding.
Introduction
If you have ever streamed to Twitch, YouTube, or any live platform using OBS Studio, you already know how powerful its scene system, source management, and output controls are. But what if you want to control all of that from outside the application? Maybe you want a mobile app that switches scenes with a tap, a custom dashboard that pulls live chat and adjusts overlays in real time, or a bot that starts and stops recording based on a schedule. That is where OBS WebSocket comes in.
OBS WebSocket is the de facto standard for remote-controlling OBS Studio. Since OBS 28, it ships bundled with the application, making it accessible to every streamer and developer without installing additional plugins. Whether you are building a streaming automation tool, a hardware controller integration, or a custom production dashboard, understanding how OBS WebSocket works gives you programmatic control over nearly every feature OBS exposes.
Understanding OBS WebSocket: Core Concepts
OBS WebSocket is defined as a Remote Procedure Call (RPC) layer built on top of the WebSocket protocol that allows external clients to communicate with a running OBS Studio instance. Instead of interacting with OBS through its graphical interface, you send structured messages over a WebSocket connection to trigger actions and receive real-time updates.
The protocol operates on a request-response and publish-subscribe model. Clients send requests to OBS, and OBS responds with results. Simultaneously, OBS broadcasts events to connected clients whenever something changes internally, such as a scene switch, a stream starting, or an input volume change.
Key terminology you will encounter includes OpCode, which is a numeric identifier that categorizes each message type. The Hello message (OpCode 0) is sent by the server immediately after a client connects, containing authentication parameters and the negotiated RPC version. The Identify message (OpCode 1) is the client's response, carrying credentials and event subscription preferences. Requests (OpCode 6) are outbound commands from the client, and Events (OpCode 5) are inbound notifications from the server.
Design Goals Behind the Protocol
The OBS WebSocket protocol was redesigned for version 5.x with several clear architectural goals in mind. The first is clean abstraction: identification, event broadcasting, and request handling are separated into distinct message categories, each with its own OpCode and payload structure. This makes it easier for client library authors to implement parsers and handlers without conflating message types.
Naming consistency is another priority. Request names follow predictable patterns like Get and Set for property access, and Start and Stop for output control. This reduces the learning curve when exploring new API categories.
The protocol supports both JSON and MessagePack encoding. JSON is the default and is ideal for debugging and rapid prototyping. MessagePack offers a more compact binary representation, which matters when you are sending high-frequency events like input volume meter updates over constrained networks.
Version negotiation is built into the handshake itself. The server advertises its RPC version in the Hello message, and the client specifies which version it wants during identification. This pub/sub and version negotiation system ensures that clients and servers can gracefully handle compatibility gaps rather than failing silently.
Setting Up OBS WebSocket in OBS Studio
Starting with OBS Studio 28, the OBS WebSocket plugin is included by default, so you do not need to download or install anything separately. For older versions, the plugin must be installed manually from the OBS WebSocket GitHub repository.
To enable and configure it, open OBS Studio and navigate to the Tools menu, then select WebSocket Server Settings. In the configuration panel, you will find options to enable the server, set the port number (the default is 4455), configure the server password, and specify which IP addresses the server binds to.
For local development, binding to localhost is sufficient and is the safest option. If you need to control OBS from another machine on your network, you can bind to all interfaces, but this exposes the server to every device on that network. Only do this on trusted networks.
Security best practices include always setting a strong password, even for local-only setups. The password prevents unauthorized applications on your machine from sending commands to OBS. If you open the port through your firewall for remote access, consider using a VPN or SSH tunnel instead of exposing the port directly to the internet. The OBS WebSocket protocol does not use TLS by default, so traffic between client and server is unencrypted unless you add a reverse proxy with SSL termination.
Connecting to OBS WebSocket: Step-by-Step Guide
Connecting to OBS WebSocket follows a structured handshake process that every client must complete before sending requests or receiving events. Understanding this flow is essential because skipping or mishandling any step results in a failed connection.
Step 1: Open the WebSocket Connection
The client initiates a standard WebSocket connection to the OBS server using the configured IP address and port. This is a plain WebSocket upgrade from HTTP, not an authenticated session yet. The server accepts the connection and immediately sends its first protocol message.
Step 2: Receive the Hello Message
Upon connection, the server sends a Hello message (OpCode 0). This message contains the OBS WebSocket version, the RPC version the server supports, and, if authentication is enabled, a challenge string and a salt value. The challenge and salt are used later in the authentication step.
Step 3: Send the Identify Message
The client responds with an Identify message (OpCode 1). This message includes the RPC version the client wants to use, the authentication string (if required), and a bitmask specifying which event categories the client wants to subscribe to. If the authentication string is missing or incorrect, the server responds with an error and closes the connection.
Step 4: Receive Identification Confirmation
If the credentials are valid and the RPC version is acceptable, the server sends an Identified message (OpCode 2) back to the client. This confirms that the handshake is complete and the client can now send requests and receive subscribed events.
This handshake ensures that both parties agree on the protocol version and that the client is authorized before any control messages are exchanged. The event subscription bitmask in the Identify message is particularly useful for reducing traffic: if you only care about scene changes, you can subscribe to just that category and ignore volume meters, output state changes, and other high-frequency events.
Authentication Mechanics
Authentication is enabled by default in OBS WebSocket 5.x, and for good reason. Without it, any application running on your machine (or on your network if you have bound to all interfaces) can send commands to OBS Studio. That includes starting streams, changing scenes, or modifying sources, all without your knowledge.
The authentication process uses a SHA-256 challenge-response mechanism. When the server sends the Hello message, it includes a random challenge string and a salt value. The client must combine these with the user-configured password to produce an authentication string that proves the client knows the password without ever sending it in plaintext.
Here is how the process works conceptually. First, the client concatenates the password and the salt, then computes a SHA-256 hash of that combination and encodes the result in base64. Next, the client takes that base64-encoded string, concatenates it with the challenge from the Hello message, computes another SHA-256 hash, and base64-encodes the result again. This final string is the authentication string sent in the Identify message.
The server performs the same computation using its stored password and the challenge it generated. If the two strings match, authentication succeeds. This approach means the password never travels over the WebSocket connection in readable form, and the challenge changes with every connection attempt, making replay attacks ineffective.
For developers building client libraries or custom integrations, the key takeaway is that you need access to a SHA-256 hashing function and base64 encoding in your chosen language. Most standard libraries provide both. You also need to handle the case where authentication is disabled, in which case the Hello message will not include a challenge or salt, and the Identify message should omit the authentication string entirely.
Working with Requests and Events
Once the handshake is complete, the client enters the operational phase where it sends requests and receives events. Understanding the structure and categories of these messages is where the real power of OBS WebSocket becomes apparent.
Request Categories
Requests are organized into several categories that mirror OBS Studio's internal architecture. General requests provide information about the server, such as GetVersion, which returns the OBS WebSocket version, OBS Studio version, and supported request types. Output requests control streaming and recording, including StartOutput, StopOutput, and ToggleOutput. Scene requests manage scene collections and scene items, such as GetSceneList, SetCurrentScene, and CreateScene. Source and input requests handle individual sources, including volume control, mute toggling, and property modification.
Each request includes a unique request ID that the client generates. This ID is echoed back in the response, allowing clients to match responses to their originating requests, which is especially important when sending multiple asynchronous requests in rapid succession.
Subscribing to Events
Events are server-to-client notifications that fire when something changes in OBS. The event categories you subscribe to are controlled by the bitmask in your Identify message. Common events include CurrentProgramSceneChanged (fires when the active scene switches), StreamStateChanged (fires when streaming starts or stops), and InputVolumeMeters (fires at regular intervals with audio level data for all inputs).
The InputVolumeMeters event deserves special attention because it is high-frequency. If you are building a live audio visualizer, this event is your data source. However, if you do not need it, unsubscribing from this category reduces message traffic significantly, which matters on slower connections or when running many concurrent clients.
Batch Requests
OBS WebSocket 5.x introduced batch requests, which let you send multiple individual requests in a single message. The server processes them according to an execution type you specify: serial (one after another, in order) or parallel (all at once, with no guaranteed ordering). Batch requests reduce the number of round trips between client and server, which is valuable for operations like initializing a dashboard that needs to query scene lists, output states, and source properties all at once.
Client Libraries Overview
Building an OBS WebSocket client from scratch is entirely possible, but using an existing library saves time and handles edge cases like reconnection, message parsing, and type safety. Several community-maintained libraries cover the most popular programming languages.
For Python, two primary options exist. simpleobsws is an asyncio-based library that works well for modern asynchronous Python applications. obsws-python takes a more synchronous, straightforward approach that is easier for beginners and scripting scenarios. Both support OBS WebSocket 5.x and handle the authentication handshake automatically.
For JavaScript and Node.js, obs-websocket-js is the standard library. It works in both browser and Node environments, making it suitable for web-based dashboards and Electron applications. It provides a clean event emitter API for handling server events and a promise-based interface for sending requests.
For Rust developers, obws provides a fully typed, async client that leverages Rust's strong type system to catch protocol errors at compile time. It is ideal for building high-performance tools or integrations where reliability and memory safety are priorities.
When choosing a library, consider your application's architecture. If you are building a web dashboard, obs-websocket-js is the natural choice. If you are writing a Python automation script, obsws-python offers the simplest path. For production-grade tools where you want compile-time guarantees, obws in Rust is worth the steeper learning curve.
Practical Use Cases
OBS WebSocket opens up a wide range of automation and integration possibilities for streamers, developers, and production teams.
Remote Scene Switching
One of the most common use cases is building a remote control interface for scene switching. A mobile app or web page connected to OBS WebSocket can list available scenes and switch between them with a single tap. This is particularly useful for solo streamers who need to manage their own scene transitions while away from their primary computer, or for production teams where a director controls scenes while the streamer focuses on content.
Automating Stream Overlays
Developers can use OBS WebSocket to dynamically control text sources, image sources, and browser sources based on live data. For example, a custom integration could pull the latest follower or donation from an API and update a text source in OBS in real time. This eliminates the need for manual overlay updates and keeps on-screen information current without interrupting the stream.
Integrating with Macro Tools
Several popular streaming tools rely on OBS WebSocket under the hood. Macro Deck, Touch Portal, and Streamer.bot all use the protocol to provide button-based control surfaces, automated actions, and conditional logic for stream management. If you are building your own macro tool or extending an existing one, OBS WebSocket is the communication layer you will build on.
Building a Custom Streaming Dashboard
For developers who want full control, building a custom streaming dashboard with OBS WebSocket gives you a tailored interface for your specific workflow. You can combine scene management, output controls, audio mixing, and source visibility toggles into a single panel. If your dashboard also needs real-time video calling capabilities for remote co-hosts or guest interviews, you can integrate a solution like VideoSDK's video calling API alongside OBS WebSocket to create a complete production environment. For broader real-time communication needs, VideoSDK's interactive live streaming capabilities complement OBS workflows for multi-participant broadcasts.
Troubleshooting Common Issues
Even with a solid understanding of the protocol, you will likely encounter a few common issues when working with OBS WebSocket.
AuthenticationFailed errors are the most frequent problem. They occur when the authentication string does not match what the server expects. Double-check that you are using the correct password, that your SHA-256 and base64 encoding steps follow the exact order specified in the protocol, and that you are reading the challenge and salt values correctly from the Hello message.
UnsupportedRpcVersion mismatches happen when the client and server cannot agree on a protocol version. This typically occurs when a client library built for OBS WebSocket 4.x tries to connect to a 5.x server, or vice versa. Check the RPC version your library targets and compare it with the server's advertised version in the Hello message.
Port conflicts arise when another application is already using the configured port (default 4455). Change the port in OBS WebSocket Server Settings and update your client configuration accordingly. Firewall blocks prevent external clients from reaching the server. Ensure the port is open in your operating system's firewall and that you are connecting to the correct IP address.
Version incompatibility between OBS Studio and the OBS WebSocket plugin can cause unexpected behavior. If you are running an older version of OBS Studio (pre-28) with a manually installed plugin, make sure the plugin version matches your OBS version. The OBS WebSocket GitHub repository provides compatibility information for each release.
Future Outlook and Migration Path
The transition from OBS WebSocket 4.x to 5.x represented a significant protocol redesign. The 5.x protocol introduced stronger typing, batch requests, event subscriptions, and a more consistent naming convention. For developers still maintaining 4.x clients, migration involves updating request and event names, implementing the new authentication flow, and adapting to the new OpCode structure. The official protocol documentation provides a detailed migration guide.
Looking forward, the OBS WebSocket community is exploring features like a vendor API for third-party plugin integration, persistent data storage for client state, and improved error reporting. The community is active on Discord and GitHub, where developers can ask questions, report issues, and contribute to the protocol's evolution.
Definitions Glossary
OpCode: A numeric identifier that categorizes each WebSocket message type in the OBS WebSocket protocol, such as 0 for Hello, 1 for Identify, and 6 for Request.
Hello Message: The first message sent by the OBS WebSocket server after a client connects, containing the RPC version, authentication challenge, and salt.
Identify Message: The client's response to the Hello message, carrying the authentication string, desired RPC version, and event subscription bitmask.
RPC (Remote Procedure Call): A protocol model where a client sends commands to a server and receives structured responses, which is the foundational architecture of OBS WebSocket.
Event Subscription Bitmask: A numeric value sent during identification that specifies which categories of events the client wants to receive from the server.
Batch Request: A single OBS WebSocket message that contains multiple individual requests, processed either serially or in parallel by the server.
Challenge-Response Authentication: A security mechanism where the server sends a random challenge string and the client must prove knowledge of the password by combining it with the challenge in a verifiable way.
Key Takeaways
- OBS WebSocket is the standard RPC protocol for remote-controlling OBS Studio, bundled by default since OBS 28.
- The connection handshake follows a strict sequence: WebSocket connect, receive Hello, send Identify, receive Identified confirmation.
- Authentication uses a SHA-256 challenge-response mechanism that never transmits the password in plaintext.
- The protocol supports both JSON and MessagePack encoding, with event subscription bitmasks to reduce unnecessary traffic.
- Client libraries exist for Python, JavaScript, and Rust, each suited to different application architectures and developer preferences.
- Batch requests allow multiple operations in a single round trip, useful for dashboard initialization and bulk scene configuration.
Conclusion
OBS WebSocket gives developers programmatic control over nearly every aspect of OBS Studio, from scene switching and output management to real-time overlay automation. Its structured RPC protocol, strong authentication model, and growing ecosystem of client libraries make it the foundation for any serious streaming automation project. Whether you are building a mobile remote control, a custom production dashboard, or integrating OBS into a larger broadcast pipeline, mastering OBS WebSocket is the key to flexible, automated stream management. Explore the official documentation, try out a client library in your preferred language, and join the OBS community on Discord to connect with other developers building streaming tools. What are you building with OBS WebSocket? Drop a comment and share your streaming automation projects.
Security Considerations
Security is crucial when using OBS WebSocket, as it involves remote control capabilities that could be exploited if not properly secured. Follow these steps to enhance security:
- Enable Password Protection: Always set a strong password for the WebSocket server. This can be done in the WebSocket Server Settings within OBS Studio.
- Use SSL/TLS: For an added layer of security, use SSL/TLS to encrypt WebSocket traffic. This requires setting up a reverse proxy with tools like Nginx or Apache to handle SSL termination.
- Firewall Configuration: Ensure that only trusted devices can access the WebSocket server by configuring your firewall to restrict access to the port used by OBS WebSocket (default 4455).
- Regular Updates: Keep OBS Studio and the OBS WebSocket plugin updated to the latest versions to benefit from security patches and new features.
By following these steps, you can significantly reduce the risk of unauthorized access and ensure a secure streaming environment.
Troubleshooting Common Issues
Despite its robust functionality, users might encounter issues when using OBS WebSocket. Here are some common problems and solutions:
Connection Errors
If you cannot connect to the WebSocket server, ensure that OBS Studio is running and the WebSocket server is enabled. Check the server port and authentication settings.
Authentication Failures
Verify that the password is correctly set and matches the client application configuration. If issues persist, reset the password in the WebSocket Server Settings.
Lag or Delays
Network latency can affect performance. Ensure that both the client and server are on the same local network to minimize delays. For remote connections, optimize network settings and use a wired connection if possible.
Incompatible Tools
Some third-party tools may not support the latest OBS WebSocket protocol. Ensure that your tools are updated or consider using the compatibility version of OBS WebSocket (4.9.1-compat).
For additional support, users can refer to the OBS forums or join the dedicated OBS WebSocket Discord server where community members and developers can offer assistance.
This detailed guide should help you get started with OBS WebSocket, utilize its powerful features, and troubleshoot common issues effectively.
Conclusion
OBS WebSocket is a transformative tool for anyone using OBS Studio for streaming or recording. Its ability to enable remote control and automation of OBS functions opens up numerous possibilities for streamers, content creators, and technical setups. By following this guide, users can easily install, configure, and utilize OBS WebSocket to enhance their streaming experience. Whether you're automating scene switches, managing overlays, or controlling OBS from your mobile device, OBS WebSocket provides the flexibility and power to make your streaming setup more efficient and professional.
Free $20 Balance for AI Voice Agents & Video Calls
FAQ