Skip to content
Compare
Choose a tag to compare
Pre-release

THIS IS A PRE-RELEASE. UNLESS YOU KNOW EXACTLY WHAT YOU ARE DOING, DOWNLOAD 4.9.1

Important Notes

  • Only use this release with OBS Studio 27.1.0 or above.
  • All plugin components have been finished, however there are some events and requests which have not yet been implemented. See the event and request sheets to find out what has been implemented.

Resources

  • The protocol specification is available here
  • Breaking changes to the protocol specification performed during the development process are available here
  • The planned requests sheet is available here
  • The planned events sheet is available here
  • To aid developers, I've updated simpleobsws (a client library I maintain) for the latest 5.0.0 protocol spec. This should help with testing and as an implementation example. See the branch here

Changes since 5.0.0-alpha1

  • obs-websocket now reports the extended plugin version in the log and around the plugin (5.0.0-alpha2 instead of just 5.0.0)
  • The QR code format has been updated from obswebsocket|[host]:[port]|[password] to obsws://[host]:[port]/[password]. obswss:// is to be used for WSS connections.
  • Fixed the global data realm functionality for persistent data requests.
  • eventIntent is now a key in event payload data.
  • The header for specifying JSON vs MsgPack has been changed from Content-Type to the Sec-WebSocket-Protocol standard. obswebsocket.json and obswebsocket.msgpack are the currently supported subprotocols.
  • The RequestStatus enum has been refactored and heavily simplified. For example, InputNotFound and SceneNotFound are now just ResourceNotFound.
  • (minor) RemoveScene now makes sure you are not removing the last scene.
  • Added these requests:
    • GetInputAudioMonitorType
    • SetInputAudioMonitorType
    • GetInputPropertiesListPropertyItems (this one is really dope)
    • PressInputPropertiesButton
    • ToggleStream
    • GetSceneItemList
    • GetGroupSceneItemList
    • CreateSceneItem
    • RemoveSceneItem

About groups...

I've gotten many questions about whether groups will officially be supported in OBS. Today I spent a bunch of time looking into what will be possible for interacting with groups in obs-websocket. Unfortunately, we are very restricted due to how groups work in OBS. However, I can say that what is and is not possible will be clearly defined in 5.x.

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-5.0.0-alpha2-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (C:\Program Files\obs-studio).

Debian / Ubuntu (64-bit)

Download obs-websocket-5.0.0-alpha2-Ubuntu64.deb (provided below) and install it on your system.

macOS

Sorry, but no binaries are available for macOS right now.

Compare
Choose a tag to compare
Pre-release

Important Notes

  • Only use this release with OBS Studio 27.1.0 or above.
  • All plugin components have been finished, however there are some events and requests which have not yet been implemented. See the event and request sheets to find out what has been implemented.
  • We've changed a lot about the low-level protocol since first announcing it. If you are developing software and do not know about the changes (like OpCodes), please check it out.

Resources

  • The protocol specification is available here
  • Breaking changes to the protocol specification performed during the development process are available here
  • The planned requests sheet is available here
  • The planned events sheet is available here
  • To aid developers, I've updated simpleobsws (a client library I maintain) for the latest 5.0.0 protocol spec. This should help with testing and as an implementation example. See the branch here

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-5.0.0-alpha1-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (C:\Program Files\obs-studio).

Debian / Ubuntu (64-bit)

Download obs-websocket-5.0.0-alpha1-Ubuntu64.deb (provided below) and install it on your system.

macOS

Sorry, but no binaries are available for macOS right now.

Compare
Choose a tag to compare

Only use this release with OBS Studio 27.0.0 or above!

Changes since 4.9.0

New Features

Enhancements

  • Added scale.filter field to the SceneItemTransform typedef.
  • The playPause parameter of the PlayPauseMedia request is now optional.
  • The volumeDb parameter has been added to the SourceVolumeChanged event.
  • Added support for obs-websocket to be built inline with OBS-Studio. (Versus out of tree)

Fixes

  • Fixed an issue where not all image file formats were supported in 4.9.0.
  • Fixed multiple scenarios where OBS could crash during shutdown with obs-websocket installed.
  • Fixed an issue causing the Ubuntu deb package to have an incorrect version.
  • Fixed an issue where creating a scene with CreateScene then deleting it would require an OBS restart in order to use the name again.
  • The Windows and MacOS binaries are now built against Qt 5.15.2, just like OBS. This helps fix a number of issues.
  • Fixed some memory leaks in SetSceneTransitionOverride, SetTBarPosition, and ReleaseTBar.

Important Notice!

This is the last planned release of obs-websocket v4.x.x. All future releases (5.x.x) will not be backwards-compatible with 4.x.x!

Over the years, obs-websocket has gone from a simple way for techies to quickly automate things to an advanced software suite with a plethora of applications that rely on it, and over 100,000 users. To say the least, there have been some growing pains in the process. Without going into too much technical detail, the plugin was originally based OBSRemote protocol which was created in early 2013. As time has progressed, more and more functionality has been built on that original design, and it was only a matter of time before it needed a complete redo.

What this means for normal users:

This means that when 5.0.0 comes out, your client software (Touch Portal, LioranBoard, etc) will also need to be updated when using them with the upcoming 5.0.0. 5.0.0 will be an exciting release, with lots of new features and performance improvements. If you're interested in seeing the kind of things in store, check out our dev updates discussion here. Here is a list of applications that plan to support v5.0.0 when it comes out:

  • Touch Portal
  • LioranBoard
  • Streamer.bot
  • StreamControl (Android App)
  • obs-web (Website)
  • obs-tablet-remote (Website)
  • WebCaptioner (Website)
  • obs-websocket-http (HTTP Server)
  • simpleobsws (Python Client Library)
  • obws (Rust Client Library)
  • obs-java-client (Java Client Library)
  • websocket-obs-java (Java Client Library)
  • obs-websocket-js (JS Client Library)
    (If you are a developer planning to release an update to your software along with 5.0.0, shoot me a message on the Discord to be added here.)

What this means for developers

Ah yes, there's no better feeling than updating your software in order to not break because one of your main dependencies decided to do a full rewrite (/s). We understand that there are developers out there who make heavy usage of obs-websocket to build incredible productions, and that updating this software can be difficult. That is why I highly encourage developers to join our Discord where we are more than happy to answer your questions as you update your software to support 5.x. We also post dev preview builds there any time there has been a notable update. Here are some helpful links for 5.x that may help you:

A final note

While Palakis and I absolutely love working on obs-websocket, it's a big piece of software that requires constant upkeep and attention. We've dedicated countless hours of our time to making sure that obs-websocket keeps working reliably so that people can continue to use it to make stunning content. However, we both also have other life obligations, meaning limited amounts of time to work on obs-websocket. If you appreciate obs-websocket and would like to contribute financially in order to help keep the project going, I encourage you to visit to our OpenCollective page. Contributing helps go towards the time we put into maintaining the plugin, along with the occasional expense which would normally be paid for out-of-pocket by one of us. I would also like to thank our code contributors as well for giving us a hand with furthering development.

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.9.1-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (either C:\Program Files\obs-studio or C:\Program Files (x86)\obs-studio).

Debian / Ubuntu (64-bit)

Download obs-websocket_4.9.1-1_amd64.deb (provided below) and install it on your system.

macOS

Download and run obs-websocket-4.9.1-macOS.pkg (provided below).

Compare
Choose a tag to compare

Only use this release with OBS Studio 26.1 or above!

Changes since 4.8.0

New Features

Enhancements

  • Made password authentication enabled by default and added a new popup asking to set a new password on first startup (#657)
  • Added the ability to lock obs-websocket to only using an IPv4 address to bind to (#559)
  • Added recordingFilename field to the response of GetRecordingStatus and the various Recording events (#621)
  • Added scene item ID support to SetSceneItemRender (#628)
  • Changed the position datatype in GetSceneItemProperties to a double instead of an integer (#533)
  • TakeSourceScreenshot now defaults to the current scene if no source name is provided (#557)
  • SetCurrentSceneCollection and SetCurrentProfile now check if the provided sc/profile name is valid (#560)
  • More detailed state information for various events. More details in PR description (#619)
  • Added more translations provided through Crowdin (#636)

Fixes

  • Fixed a crash that can happen when OBS exits with existing websocket clients (#644)
  • Fixed a crash that can happen when notifications are enabled in obs-websocket (#571)
  • Fixed useDecibel parameter of GetVolume when the volume is -INFINITY (#529)
  • Fixed missing request parameters response when performing GetOutputInfo, StartOutput, StopOutput (#618)
  • Fixed the file permissions of the Ubuntu deb release file. (Previously were 777) (#627)
  • Reenabled captions requests for MacOS (#546)
  • SetVolume now allows mul values higher than 1.0 and dB values higher than 0.0 (#629)

Notes

  • The README has been updated with some new libraries and web clients that can be used to interface with obs-websocket
  • Added a new guide for enabling SSL access with ngrok: SSL-TUNNELlING.md

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.9.0-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (either C:\Program Files\obs-studio or C:\Program Files (x86)\obs-studio).

Debian / Ubuntu (64-bit)

Download obs-websocket_4.9.0-1_amd64.deb (provided below) and install it on your system.

macOS

Download and run obs-websocket-4.9.0-macOS.pkg (provided below).

Compare
Choose a tag to compare

Only use this release with OBS Studio 25 or above!

Changes since 4.7.0

New Features

Enhancements

Fixes

  • Fixed crashes when calling EnableStudioMode, DisableStudioMode or ToggleStudioMode
  • Fixed an issue where SetStreamSettings wouldn't apply if switching service type
  • Any event that returns transition duration now returns -1 if the transition is fixed (Eg. Cut, Stinger)
  • SetSyncOffset now allows negative offsets
  • Removed from-scene from TransitionEnd since it isnt actually available
  • Fixed JPEG support in TakeSourceScreenshot on Windows
  • Fixed a crash when sending an event on OBS exit
  • Fixed source recognition on GDI+ and Freetype 2 sources
  • Fixed the OBS log getting spammed with unnecessary messages on Linux (regardless of whether debug logging was enabled)
  • Fixed an issue where the plugin failed to load on MacOS
  • Fixed a bunch of memory leaks in GetCurrentProfile, GetCurrentSceneCollection and the Heartbeat event

Important Notes

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.8.0-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (either C:\Program Files\obs-studio or C:\Program Files (x86)\obs-studio).

Debian / Ubuntu (64-bit)

Download obs-websocket_4.8.0-1_amd64.deb (provided below) and install it on your system.

macOS

Download and run obs-websocket-4.8.0-macOS.pkg (provided below).

Compare
Choose a tag to compare

Only use this release with OBS 23 or above!

Changes since 4.6.1

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.7.0-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (either C:\Program Files\obs-studio or C:\Program Files (x86)\obs-studio).

Debian / Ubuntu (64-bit)

  • Manual install: Download obs-websocket_4.7.0-1_amd64.deb and install it on your system.

macOS

Download and run obs-websocket-4.7.0-macOS.pkg.
Note: the installer package is now digitally signed, so macOS shouldn't complain. However, if it is the case and a security alert pops up when trying to launch the installer, go to the "Security & Privacy" panel under macOS Settings and click "Open Anyway".

585f845
Compare
Choose a tag to compare

Only use this release with OBS 23 or above!

4.6.1 Hotfix Changes

  • Bugfix: TransitionBegin event not triggering at all

4.6.0 Changes

  • Revamped WebSockets server: the WebSockets server backend was completely rewritten. Instead of Qt's WebSockets library, starting with 4.6 obs-websocket now uses websocketpp by zaphoyd. Other benefits include:
    • Requests are received and processed in a separate dedicated threads. The old server processed everything in the UI/main window thread.
    • Everything (main plugin + server dependencies) is now in a single binary file.
  • Server settings are now per-profile settings instead of global settings: the server is automatically started, stopped or restarted when switching profiles. New profiles inherit settings from the previously selected profile.
  • New request types:
    • TakeSourceScreenshot: take an image snapshot of a source (either an input or a scene) and save it straight to a file and/or receive it in the response as base64-encoded Data URI
    • SendCaptions (Windows/macOS only): send closed captions text to the streaming output. For instance, Twitch's player supports closed captions sent through SendCaptions
    • GetStats: provides most of the metrics found in OBS' Stats window.
    • GetVideoInfo: Fetch information about OBS' video output settings: base/canvas size and output size, pixel format, YUV settings, ...
  • New event types:
  • Feature: StreamStatus and Heartbeat events now include data from OBS' stats and a replay-buffer-active property (for StreamStatus)
  • Feature: GetSceneItemProperties and SetSceneItemProperties now have support for a locked property that allows users to lock or unlock a scene item and get its current lock state
  • Feature: the response from GetSceneItemProperties now includes width and height values computed from the item's base dimensions and current scaling settings.
  • Source and Scene Item events enhancements:
    • Source and Scene Item events will also be triggered for the current preview scene (in Studio Mode) and scenes not currently visible on program or preview
    • All scene item events now include an item-id property
    • SourceOrderChanged now includes a list of the reordered scene items
  • Fixed incompatibilites with Groups:
    • Scene Item requests can now target items nested in groups
    • Scene item data now includes two new properties:
      • parentGroupName on scene items that belong to a group
      • children on groups
  • Bugfix: crash on startup when the "port already in use" message shows up
  • Bugfix: error with SetSceneItemProperties when trying to set the bounds type of a scene item
  • Bugfix: plugin not loading on Ubuntu when installing through the .deb file (wrong plugin path)
  • Bugfix (docs): GetSourcesTypesList is supposed to be GetSourceTypesList
  • Docs: the Protocol Specification now includes type definitions that can be shared among several request types. These encourage reusing existing response formats, and allows obs-websocket-js to provide type definitions in their TypeScript bindings.

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.6.1-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (either C:\Program Files\obs-studio or C:\Program Files (x86)\obs-studio).

Debian / Ubuntu (64-bit)

  • Manual install: Download obs-websocket_4.6.1-1_amd64.deb and install it on your system.

macOS

Download and run obs-websocket-4.6.1.pkg.
Note: the installer package is now digitally signed, so macOS shouldn't complain. However, if it is the case and a security alert pops up when trying to launch the installer, go to the "Security & Privacy" panel under macOS Settings and click "Open Anyway".

Compare
Choose a tag to compare

Changes since 4.5.1

  • Revamped WebSockets server: the WebSockets server backend was completely rewritten. Instead of Qt's WebSockets library, starting with 4.6 obs-websocket now uses websocketpp by zaphoyd. Other benefits include:
    • Requests are received and processed in a separate dedicated threads. The old server processed everything in the UI/main window thread.
    • Everything (main plugin + server dependencies) is now in a single binary file.
  • Server settings are now per-profile settings instead of global settings: the server is automatically started, stopped or restarted when switching profiles. New profiles inherit settings from the previously selected profile.
  • New request types:
    • TakeSourceScreenshot: take an image snapshot of a source (either an input or a scene) and save it straight to a file and/or receive it in the response as base64-encoded Data URI
    • SendCaptions (Windows/macOS only): send closed captions text to the streaming output. For instance, Twitch's player supports closed captions sent through SendCaptions
    • GetStats: provides most of the metrics found in OBS' Stats window.
    • GetVideoInfo: Fetch information about OBS' video output settings: base/canvas size and output size, pixel format, YUV settings, ...
  • New event types:
  • Feature: StreamStatus and Heartbeat events now include data from OBS' stats and a replay-buffer-active property (for StreamStatus)
  • Feature: GetSceneItemProperties and SetSceneItemProperties now have support for a locked property that allows users to lock or unlock a scene item and get its current lock state
  • Feature: the response from GetSceneItemProperties now includes width and height values computed from the item's base dimensions and current scaling settings.
  • Source and Scene Item events enhancements:
    • Source and Scene Item events will also be triggered for the current preview scene (in Studio Mode) and scenes not currently visible on program or preview
    • All scene item events now include an item-id property
    • SourceOrderChanged now includes a list of the reordered scene items
  • Fixed incompatibilites with Groups:
    • Scene Item requests can now target items nested in groups
    • Scene item data now includes two new properties:
      • parentGroupName on scene items that belong to a group
      • children on groups
  • Bugfix: crash on startup when the "port already in use" message shows up
  • Bugfix: error with SetSceneItemProperties when trying to set the bounds type of a scene item
  • Bugfix: plugin not loading on Ubuntu when installing through the .deb file (wrong plugin path)
  • Bugfix (docs): GetSourcesTypesList is supposed to be GetSourceTypesList
  • Docs: the Protocol Specification now includes type definitions that can be shared among several request types. These encourage reusing existing response formats, and allows obs-websocket-js to provide type definitions in their TypeScript bindings.

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.6.0-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder (either C:\Program Files\obs-studio or C:\Program Files (x86)\obs-studio).

Debian / Ubuntu (64-bit)

  • Manual install: Download obs-websocket_4.6.0-1_amd64.deb and install it on your system.

macOS

Download and run obs-websocket-4.6.0.pkg.
Note: the installer package is now digitally signed, so macOS shouldn't complain. However, if it is the case and a security alert pops up when trying to launch the installer, go to the "Security & Privacy" panel under macOS Settings and click "Open Anyway".

Compare
Choose a tag to compare

Only use this release with OBS 22 or above!

4.5.1 bugfix release

  • Bugfix: plugin not loading on Ubuntu (misplaced binary)
  • Bugfix: improper control flow in filter management requests (missing return statements)

4.5.0 changes

  • New request types:
    • Filter management:
      • GetSourceFilters
      • AddFilterToSource
      • RemoveFilterFromSource
      • ReorderSourceFilter
      • MoveSourceFilter
      • SetSourceFilterSettings
    • Scene Items:
      • DeleteSceneItem
      • DuplicateSceneItem
      • ReorderSceneItems
    • Source settings:
      • GetTextFreetype2Properties
      • SetTextFreetype2Properties
  • Updated request types:
    • Breaking changes in GetTextGDIPlusProperties, SetTextGDIPlusProperties, GetBrowserSourceProperties and SetBrowserSourceProperties:
      • Removed the scene-name parameter: deemed useless on sources, which are independent from scenes
      • Removed the render request parameter and response property
    • GetVolume: fix typo in protocol specification ( mute ; ✔️ muted)
  • Refactored authentication code:
    • If you have authentication enabled and your current password doesn't work anymore, try setting it again.
  • macOS Bugfix: Qt version mismatch
  • Fixed various typos in the protocol specification

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.5.1-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder.

Debian (64-bit)

  • Manual install: Download obs-websocket_4.5.1-1_amd64.deb and install it on your system.

macOS

Download and run obs-websocket-4.5.1.pkg.
Note: the installer package is now digitally signed, so macOS shouldn't complain. However, if it is the case and a security alert pops up when trying to launch the installer, go to the "Security & Privacy" panel under macOS Settings and click "Open Anyway".

Compare
Choose a tag to compare
Pre-release

Only use this release with OBS 22 or above!

Foreword

This is a Release Candidate for obs-websocket 4.5.0. Some things may be broken, so please test it before using it in production.
Minor non-backwards-compatible changes are in 4.5.0, detailed below in the changelog. Check if your code is affected by one of the changes, and update your code accordingly.
If you're using a ready-made tool/software that uses obs-websocket, test it and report any issue to the developer/publisher of the aforementioned software.

Changes since 4.4.0

  • New request types:
    • Filter management:
      • GetSourceFilters
      • AddFilterToSource
      • RemoveFilterFromSource
      • ReorderSourceFilter
      • MoveSourceFilter
      • SetSourceFilterSettings
    • Scene Items:
      • DeleteSceneItem
      • DuplicateSceneItem
      • ReorderSceneItems
    • Source settings:
      • GetTextFreetype2Properties
      • SetTextFreetype2Properties
  • Updated request types:
    • Breaking changes in GetTextGDIPlusProperties, SetTextGDIPlusProperties, GetBrowserSourceProperties and SetBrowserSourceProperties:
      • Removed the scene-name parameter: deemed useless on sources, which are independent from scenes
      • Removed the render request parameter and response property
    • GetVolume: fix typo in protocol specification ( mute ; ✔️ muted)
  • Refactored authentication code:
    • If you have authentication enabled and your current password doesn't work anymore, try setting it again.
  • macOS Bugfix: Qt version mismatch
  • Fixed various typos in the protocol specification

Install instructions

Windows

  • Using the installer (recommended, works only with combined 32/64-bit installations) : download it, launch it and follow the instructions.
  • Using the obs-websocket-4.5.0-Windows.zip archive : copy the contents of the archive to the root of your OBS Studio installation folder.

Debian (64-bit)

  • Manual install: Download obs-websocket_4.5.0-1_amd64.deb and install it on your system.

macOS

Download and run obs-websocket-4.5.0.pkg.
Note: OS X may show you a security alert when launching the installer, preventing your from installing obs-websocket. If this happens, go to the "Security & Privacy" panel in OS X Settings and click "Open Anyway".