/obs-websocket

Remote-control of OBS Studio through WebSocket

Primary LanguageC++GNU General Public License v2.0GPL-2.0

obs-websocket

WebSockets API for OBS Studio.

Follow the main author on Twitter for news & updates : @LePalakis

Build Status - Windows Build Status - Linux

Downloads

Binaries for Windows and Linux are available in the Releases section.

Using obs-websocket

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.

Possible use cases

  • Remote control OBS from a phone or tablet on the same local network
  • Change your stream overlay/graphics based on the current scene (like the AGDQ overlay does)
  • Automate scene switching with a third-party program (e.g. : auto-pilot, foot pedal, ...)

For developers

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 :

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 !

Compiling obs-websocket

See the build instructions.

Contributing

Branches

The two main development branches are:

  • 4.x-current: actively-maintained codebase for 4.x releases. Backwards-compatible (unless stated otherwise) with existing clients until 5.0.
  • 5.x: upcoming 5.0 version

New features and fixes must be based off and contributed to 4.x-current, as obs-websocket 5.0 is not in active development yet.

Pull Requests

Pull Requests must never be based off your fork's main branch (in our case, 4.x-current or 5.x). 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, tag it with the work in progress label. You can also use the help needed label if you have questions, need a hand or want to ask for input.

Code style & formatting

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();

Translations

Your help is welcome on translations. Please join the localization project on Crowdin: https://crowdin.com/project/obs-websocket

Special thanks

In (almost) order of appearance:

And also: special thanks to supporters of the project!

Supporters

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.

Support Class

MediaUnit is a Norwegian media company developing products and services for the media industry, primarly focused on web and events.

MediaUnit