WebSockets API for OBS Studio.
Follow the main author on Twitter for news & updates : @LePalakis
Binaries for Windows, MacOS, and Linux are available in the Releases section.
A web client and frontend made by t2t2 (compatible with tablets and other touch interfaces) is available here : http://t2t2.github.io/obs-tablet-remote/
It is highly recommended to protect obs-websocket with a password against unauthorized control. To do this, open the "Websocket server settings" dialog under OBS' "Tools" menu. In the settings dialogs, you can enable or disable authentication and set a password for it.
Before doing this, secure the WebSockets server first by enabling authentication with a strong password!
If you want to expose the WebSockets server of obs-websocket over a secure TLS connection (or to connect remotely), the easiest approach is to use a localhost tunneling service like ngrok or pagekite.
Please bear in mind that doing this will expose your OBS instance to the open Internet and the security risks it implies. You've been warned!
Install the ngrok CLI tool, then start ngrok bound to port 4444 like this:
ngrok http 4444The ngrok command will output something like this:
ngrok by @inconshreveable
Tunnel Status online
Version 2.0/2.0
Web Interface http://127.0.0.1:4040
Forwarding http://TUNNEL_ID.ngrok.io -> localhost:4444
Forwarding https://TUNNEL_ID.ngrok.io -> localhost:4444
Where TUNNEL_ID is, as the name implies, the unique name of your ngrok tunnel. You'll get a new one every time you start ngrok.
Then, use wss://TUNNEL_ID.ngrok.io to connect to obs-websocket over TLS.
See the ngrok documentation for more tunneling options and settings.
Install the PageKite CLI tool, then start PageKite bound to port 4444 like this (replace NAME with one of your choosing):
$ python pagekite.py 4444 NAME.pagekite.meThen, use wss://NAME.pagekite.me to connect to obs-websocket over TLS.
- Remote control OBS from a phone or tablet on the same local network
- Change your stream overlay/graphics based on the current scene
- Automate scene switching with a third-party program (e.g. : auto-pilot, foot pedal, ...)
The server is a typical Websockets server running by default on port 4444 (the port number can be changed in the Settings dialog). The protocol understood by the server is documented in PROTOCOL.md.
Here's a list of available language APIs for obs-websocket :
- Javascript (browser & nodejs): obs-websocket-js by Brendan Hagan
- C#/VB.NET: obs-websocket-dotnet
- Python 2 and 3: obs-websocket-py by Guillaume Genty a.k.a Elektordi
- Python 3.5+ with asyncio: obs-ws-rc by Kirill Mysnik
- Python 3.6+ with asyncio: simpleobsws by tt2468
- Java 8+: obs-websocket-java by TwasiNET
- Golang: go-obs-websocket by Chris de Graaf
- HTTP API: obs-websocket-http by tt2468
I'd like to know what you're building with or for obs-websocket. If you do something in this fashion, feel free to drop me an email at stephane /dot/ lepin /at/ gmail /dot/ com !
See the build instructions.
Development happens on 4.x-current
Pull Requests must never be based off your fork's main branch (in this case, 4.x-current). Start your work in a new branch
based on the main one (e.g.: cool-new-feature, fix-palakis-mistakes, ...) and open a Pull Request once you feel ready to show your work.
If your Pull Request is not ready to merge yet, create it as a Draft Pull Request (open the little arrow menu next to the "Create pull request" button, then select "Create draft pull request").
Source code is indented with tabs, with spaces allowed for alignment.
Regarding protocol changes: new and updated request types / events must always come with accompanying documentation comments (see existing protocol elements for examples). These are required to automatically generate the protocol specification document.
Among other recommendations: favor return-early code and avoid wrapping huge portions of code in conditionals. As an example, this:
if (success) {
return req->SendOKResponse();
} else {
return req->SendErrorResponse("something went wrong");
}is better like this:
if (!success) {
return req->SendErrorResponse("something went wrong");
}
return req->SendOKResponse();Your help is welcome on translations. Please join the localization project on Crowdin: https://crowdin.com/project/obs-websocket
In (almost) order of appearance:
- Brendan H.: Code contributions and gooder English in the Protocol specification
- Mikhail Swift: Code contributions
- Tobias Frahmer: Initial German localization
- Genture: Initial Simplified Chinese and Traditional Chinese localizations
- Larissa Gabilan: Initial Portuguese localization
- Andy Asquelt: Initial Polish localization
- Marcel Haazen: Initial Dutch localization
- Peter Antonvich: Code contributions
- yinzara: Code contributions
- Chris Angelico: Code contributions
- Guillaume "Elektordi" Genty: Code contributions
- Marwin M: Code contributions
- Logan S.: Code contributions
- RainbowEK: Code contributions
- RytoEX: CI script and code contributions
- Theodore Stoddard: Code contributions
- Philip Loche: Code contributions
- Patrick Heyer: Code contributions and CI fixes
- Alex Van Camp: Code contributions
- Freddie Meyer: Code contributions
- Casey Muller: CI fixes
- Chris Angelico: Documentation fixes
And also: special thanks to supporters of the project!
They have contributed financially to the project and made possible the addition of several features into obs-websocket. Many thanks to them!
Support Class designs and develops professional livestreams, with services ranging from broadcast graphics design and integration to event organization, along many other skills.
MediaUnit is a Norwegian media company developing products and services for the media industry, primarly focused on web and events.
