#obs #streaming #websocket

app obs-do

WebSocket control utility for OBS Studio

1 unstable release

0.1.0 Jul 16, 2023

#487 in Command line utilities


94 lines

obs-do is a simple control utility that triggers OBS operations when invoked on the command line. It's particularly handy when used in combination with global system hotkeys that can invoke commands.

The motivation for build it for me is that OBS does not (yet) support global hotkeys under Wayland. Which is unfortunate, given that they're pretty much essential to doing streaming where you can't switch over to the OBS window all the time. Some Wayland compositors support global hotkey pass-through, which are often enough to get by. In my case though, the combination of this bug in Hyprland and this bug in OBS meant that I simply could not get the global shortcuts I wanted that way.

Which brings me to obs-do. This super-simple CLI connects to OBS over WebSocket and issues commands that way, and can then simply be invoked by whatever means you want (including Wayland compositor global shortcuts) to trigger the desired OBS effect. For example, I'm using the following hyprland configuration to use my numpad for stream control:

bind = SHIFT, KP_SUBTRACT, exec, obs-do toggle-stream
bind = SHIFT, KP_ADD, exec, obs-do toggle-record
bind = , KP_DELETE, exec, obs-do toggle-mute
bind = , KP_BEGIN, exec, obs-do set-scene 'Desktop (Q&A)'
bind = , KP_INSERT, exec, obs-do set-scene 'Desktop (code)'
bind = , KP_MULTIPLY, exec, obs-do set-scene 'Break'
bind = , KP_END, exec, obs-do set-scene 'Webcam'

Note that for this to work you must have an installation of OBS that includes WebSocket functionality. If you see Tools -> WebSocket Server Settings in the OBS menu then you're set — just copy the "Server Password" from the "Show Connect Info" popup into ~/.config/obs-do/websocket-token. Otherwise, grab a different OBS install that does. For example, on Arch Linux at the moment, the obs-studio package does not include WebSocket support. Instead, you need to install one of the other OBS packages from the AUR (like obs-studio-git).


Licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


~242K SLoC