D̲e̲s̲c̲r̲i̲p̲t̲i̲o̲n̲
This tool acts as a simple HTTP gateway to the obs-websocket interface. The idea is that more tools can trigger simple HTTP interfaces instead of opening a websocket connection and sending JSON. Also from user perspective it's easier to use, because formatting URL query parameters is a bit easier to do than formatting JSON.
The format of URL calls looks like this: http://localhost:57297/xObsSimpleHttpControl/OBS-Instance/Request?param1=value - where "OBS-Instance" is the name of an OBS instance as you configured it and Request would be the obs-websocket request method to be sent, followed by necessary parameters.
Changing the scene in the OBS instance "MyOBS" to "Game" would work like this: http://localhost:57297/xObsSimpleHttpControl/MyOBS/SetCurrentScene?scene-name="Game"
In theory every request that is listed here can be sent.
A few examples that have already been tested: Change current scene, show/hide sources, set audio volumes or mute/unmute, rename sources, enable/disable filters...
By default all of these calls are fire and forget, they will finish immediately and don't return any data from obs-websocket.
If you want to retrieve data and/or wait for the result then you need to use the /Get method, e.g. to get the current scene shown in "MyOBS" you would use:
Note that this returns the raw JSON response from obs-websocket, so the data still needs parsing.
Another feature it has is that it can call a web hook configured by you for each event it receives from obs-websocket, see: https://github.com/obsproject/obs-websocket/blob/4.x-compat/docs/generated/protocol.md#events
However, with this webhook it will send the original JSON and not query parameters, so your receiving tool must be able to parse JSON.
You only need to run one instance of this tool to manage multiple instances of OBS, each instance is addressed as part of the URL.
I've written this for myself but thought I'd share it here, because I am sure others will find it useful too. Therefore if you have feature requests your best chance is that it's something I also want for myself, otherwise I might not be willing to invest the time.
L̲i̲m̲i̲t̲a̲t̲i̲o̲n̲s̲
- all requests with only simple data types (int, double, string, bool) should work fine, as soon as you have some kind of nesting (indicated by "object" data type) it either doesn't work or needs ugly hacks, like cramping URL-encoded JSON into a query parameter value
- requests are not encrypted or protected by a password
- the tool doesn't indicate the connection status to each OBS instance, in OBS activate "Tools -> WebSockets Server Settings -> [X] Enable System Tray Alerts" to see if the tool is connecting to a particular OBS instance
- the webhook sends the original JSON, the data is NOT formatted as query parameters
- this will always depend on obs-websocket, it just wouldn't make sense to do all the work that is going into obs-websocket again only with HTTP queries instead of JSON
- each webhook call for each event is happening on its own thread, but request handling is currently not multi-threaded
-> since all requests are handled very quickly this should still scale up even for high numbers of requests, but let me know if the tool has become a bottleneck for you, I am still thinking about making request-handling multi-threaded too
O̲p̲e̲r̲a̲t̲i̲n̲g̲ ̲S̲y̲s̲t̲e̲m̲
This software has only been tested on Windows 10 Pro (64 bit). In theory it could also work on other Windows versions and using the Mono Framework even on MacOS or Linux, but this hasn't been tested and no guarantees whatsoever can be given.
Feel free to let me know what worked for you and what didn't.
P̲r̲e̲r̲e̲q̲u̲i̲s̲i̲t̲e̲s̲
- .NET Framework 4.5.2 (Windows)
- OBS 27.0.1 or higher
- obs-websocket 4.9.1 installed and enabled in OBS, get it from here
- tools that can trigger HTTP requests, some examples it has been tested with: Node-RED, Chataigne, Stream Deck, curl, various Browsers...
I̲n̲s̲t̲a̲l̲l̲a̲t̲i̲o̲n̲
- make sure the obs-websocket plug-in is enabled in OBS (Main menu -> Tools -> WebSockets Server Settings -> Enable WebSockets Server)
- extract all files from the ZIP to an empty folder
- make a copy of xObsSimpleHttpControl.conf.example and rename it to xObsSimpleHttpControl.conf
- open xObsSimpleHttpControl.conf with a text editor and configure everything to your needs
-> if you want to configure more than one OBS instance make a copy of the lines from <Instance> to </Instance> (including these lines)
- create a shortcut to xObsSimpleHttpControl.exe if you wish, e.g. on your desktop
U̲p̲d̲a̲t̲e̲
- overwrite all files in the existing folder with the files from the ZIP file
- open xObsSimpleHttpControl.conf.example with a text editor and check for potential new configuration settings, copy them over to xObsSimpleHttpControl.conf as needed
U̲s̲a̲g̲e̲
- run the OBS instance(s) xObsSimpleHttpControl is configured to connect to
- run xObsSimpleHttpControl.exe directly or the shortcut you have created during installation
-> a new tray icon will appear in the start menu tray area, this tool doesn't have a window
- xObsSimpleHttpControl will automatically try to connect to the configured OBS WebSocket address(es)
- in cases it loses connection to OBS it will automatically try to reconnect every few seconds
- to exit the program right click the tray icon and select "Exit" from the menu
In the file Examples.txt included in the download package you will find several examples that have already been successfully tested with the tool.
C̲h̲a̲n̲g̲e̲l̲o̲g̲
v0.1 Beta (2021-07-23):
- initial release as beta software only given to a select few testers
v1.0 (2021-07-26):
- initial public release
- added a feature to have webhook calls filtered for only specified events specified in a text file
- some code clean-up
v1.1 (2022-05-01):
- sped up program start-up in situations where not all configured OBS instances are reachable
- added Get mode that will 1. wait for the response 2. return the raw JSON response from OBS
- URL parameters now use UTF-8 encoding
- updated URL call encryption standard to TLS v1.2, fixing "Could not create SSL/TLS secure channel" errors
This tool acts as a simple HTTP gateway to the obs-websocket interface. The idea is that more tools can trigger simple HTTP interfaces instead of opening a websocket connection and sending JSON. Also from user perspective it's easier to use, because formatting URL query parameters is a bit easier to do than formatting JSON.
The format of URL calls looks like this: http://localhost:57297/xObsSimpleHttpControl/OBS-Instance/Request?param1=value - where "OBS-Instance" is the name of an OBS instance as you configured it and Request would be the obs-websocket request method to be sent, followed by necessary parameters.
Changing the scene in the OBS instance "MyOBS" to "Game" would work like this: http://localhost:57297/xObsSimpleHttpControl/MyOBS/SetCurrentScene?scene-name="Game"
In theory every request that is listed here can be sent.
A few examples that have already been tested: Change current scene, show/hide sources, set audio volumes or mute/unmute, rename sources, enable/disable filters...
By default all of these calls are fire and forget, they will finish immediately and don't return any data from obs-websocket.
If you want to retrieve data and/or wait for the result then you need to use the /Get method, e.g. to get the current scene shown in "MyOBS" you would use:
Note that this returns the raw JSON response from obs-websocket, so the data still needs parsing.
Another feature it has is that it can call a web hook configured by you for each event it receives from obs-websocket, see: https://github.com/obsproject/obs-websocket/blob/4.x-compat/docs/generated/protocol.md#events
However, with this webhook it will send the original JSON and not query parameters, so your receiving tool must be able to parse JSON.
You only need to run one instance of this tool to manage multiple instances of OBS, each instance is addressed as part of the URL.
I've written this for myself but thought I'd share it here, because I am sure others will find it useful too. Therefore if you have feature requests your best chance is that it's something I also want for myself, otherwise I might not be willing to invest the time.
L̲i̲m̲i̲t̲a̲t̲i̲o̲n̲s̲
- all requests with only simple data types (int, double, string, bool) should work fine, as soon as you have some kind of nesting (indicated by "object" data type) it either doesn't work or needs ugly hacks, like cramping URL-encoded JSON into a query parameter value
- requests are not encrypted or protected by a password
- the tool doesn't indicate the connection status to each OBS instance, in OBS activate "Tools -> WebSockets Server Settings -> [X] Enable System Tray Alerts" to see if the tool is connecting to a particular OBS instance
- the webhook sends the original JSON, the data is NOT formatted as query parameters
- this will always depend on obs-websocket, it just wouldn't make sense to do all the work that is going into obs-websocket again only with HTTP queries instead of JSON
- each webhook call for each event is happening on its own thread, but request handling is currently not multi-threaded
-> since all requests are handled very quickly this should still scale up even for high numbers of requests, but let me know if the tool has become a bottleneck for you, I am still thinking about making request-handling multi-threaded too
O̲p̲e̲r̲a̲t̲i̲n̲g̲ ̲S̲y̲s̲t̲e̲m̲
This software has only been tested on Windows 10 Pro (64 bit). In theory it could also work on other Windows versions and using the Mono Framework even on MacOS or Linux, but this hasn't been tested and no guarantees whatsoever can be given.
Feel free to let me know what worked for you and what didn't.
P̲r̲e̲r̲e̲q̲u̲i̲s̲i̲t̲e̲s̲
- .NET Framework 4.5.2 (Windows)
- OBS 27.0.1 or higher
- obs-websocket 4.9.1 installed and enabled in OBS, get it from here
- tools that can trigger HTTP requests, some examples it has been tested with: Node-RED, Chataigne, Stream Deck, curl, various Browsers...
I̲n̲s̲t̲a̲l̲l̲a̲t̲i̲o̲n̲
- make sure the obs-websocket plug-in is enabled in OBS (Main menu -> Tools -> WebSockets Server Settings -> Enable WebSockets Server)
- extract all files from the ZIP to an empty folder
- make a copy of xObsSimpleHttpControl.conf.example and rename it to xObsSimpleHttpControl.conf
- open xObsSimpleHttpControl.conf with a text editor and configure everything to your needs
-> if you want to configure more than one OBS instance make a copy of the lines from <Instance> to </Instance> (including these lines)
- create a shortcut to xObsSimpleHttpControl.exe if you wish, e.g. on your desktop
U̲p̲d̲a̲t̲e̲
- overwrite all files in the existing folder with the files from the ZIP file
- open xObsSimpleHttpControl.conf.example with a text editor and check for potential new configuration settings, copy them over to xObsSimpleHttpControl.conf as needed
U̲s̲a̲g̲e̲
- run the OBS instance(s) xObsSimpleHttpControl is configured to connect to
- run xObsSimpleHttpControl.exe directly or the shortcut you have created during installation
-> a new tray icon will appear in the start menu tray area, this tool doesn't have a window
- xObsSimpleHttpControl will automatically try to connect to the configured OBS WebSocket address(es)
- in cases it loses connection to OBS it will automatically try to reconnect every few seconds
- to exit the program right click the tray icon and select "Exit" from the menu
In the file Examples.txt included in the download package you will find several examples that have already been successfully tested with the tool.
C̲h̲a̲n̲g̲e̲l̲o̲g̲
v0.1 Beta (2021-07-23):
- initial release as beta software only given to a select few testers
v1.0 (2021-07-26):
- initial public release
- added a feature to have webhook calls filtered for only specified events specified in a text file
- some code clean-up
v1.1 (2022-05-01):
- sped up program start-up in situations where not all configured OBS instances are reachable
- added Get mode that will 1. wait for the response 2. return the raw JSON response from OBS
- URL parameters now use UTF-8 encoding
- updated URL call encryption standard to TLS v1.2, fixing "Could not create SSL/TLS secure channel" errors
