obs-opendeck

OBS WebSocket control plugin for OpenDeck — control OBS Studio directly from your deck. Switch scenes, toggle streaming and recording, manage the replay buffer, control the virtual camera, work with filters and sources, and more.

Features

Control 18 OBS actions from your OpenDeck device:

Action	Description
OBS Setup	Configure OBS connection settings (host, port, password). Press to test the connection.
Switch Scene	Switch to a specific OBS scene
Next Scene	Switch to the next scene in the scene list
Previous Scene	Switch to the previous scene in the scene list
Toggle Stream	Start or stop streaming
Toggle Recording	Start or stop recording
Pause Recording	Pause or resume the current recording
Save Replay	Save the current replay buffer clip
Toggle Replay Buffer	Start or stop the replay buffer
Toggle Virtual Camera	Start or stop the virtual camera
Toggle Studio Mode	Enable or disable studio mode
Studio Transition	Cut the preview scene to program (studio mode)
Toggle Source	Show or hide a scene source
Toggle Mute	Mute or unmute an audio input
Set Volume	Set an audio input to a specific volume level
Trigger Hotkey	Trigger an OBS hotkey by name
Toggle Filter	Enable or disable a source filter
Screenshot	Save a screenshot of a source or the current scene

Prerequisites

• OBS Studio (latest version recommended)
• obs-websocket v5 (bundled with OBS 28+)
• OpenDeck (installed on your system)

Supported Platforms

• Windows: x86_64
• macOS: Intel x86_64, Apple Silicon ARM64
• Linux: x86_64, ARM64

Installation

Using make

cd obs-opendeck
make install

This copies the plugin to:

• macOS/Linux: ~/.config/opendeck/plugins/io.pngz.obs.sdPlugin/
• Windows: %APPDATA%\Elgato\StreamDeck\Plugins\io.pngz.obs.sdPlugin\

Manual Installation

1. Build the plugin (see Building from Source below)
2. Copy the built binaries to your OpenDeck plugins directory:
   • macOS/Linux: ~/.config/opendeck/plugins/io.pngz.obs.sdPlugin/bin/
   • Windows: %APPDATA%\Elgato\StreamDeck\Plugins\io.pngz.obs.sdPlugin\bin\

Configuration

Initial Setup

1. Open OpenDeck and add the "OBS Setup" action to a button
2. The Property Inspector appears on the right
3. Enter your OBS WebSocket connection details:
   • Host: IP address or hostname of your OBS instance (default: localhost)
   • Port: WebSocket port (default: 5005)
   • Password: OBS WebSocket password (if configured)
4. Click the button to test the connection

Configurable Actions

Some actions support customization via the Property Inspector:

Action	Configurable Fields
Switch Scene	Scene name
Toggle Source	Scene name, source name
Toggle Mute	Audio input name
Set Volume	Audio input name, volume level (0-100)
Trigger Hotkey	Hotkey name
Toggle Filter	Source name, filter name
Screenshot	Source name (optional, uses current scene if empty)

Building from Source

Prerequisites

• Rust 1.70 or later
• OpenDeck (installed)

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Build and Install

git clone https://github.com/PenguinzTech/obs-opendeck.git
cd obs-opendeck

# Build and install the plugin
make install

# Or build only
make build

# Or build for all supported platforms
make build-all

Build Output

The plugin produces platform-specific binaries:

• obs-opendeck-x86_64-pc-windows-msvc.exe (Windows)
• obs-opendeck-x86_64-apple-darwin (macOS Intel)
• obs-opendeck-aarch64-apple-darwin (macOS ARM64)
• obs-opendeck-x86_64-unknown-linux-gnu (Linux x86_64)
• obs-opendeck-aarch64-unknown-linux-gnu (Linux ARM64)

Important Notes

OBS WebSocket Connection

• Ensure OBS Studio is running with WebSocket enabled
• Default WebSocket address: ws://localhost:5005
• If connecting remotely, ensure proper firewall rules are configured
• The password is stored securely in OpenDeck's encrypted settings

State Indicators

Many actions display state indicators on the button:

• Toggle Stream: Shows "Stream On" or "Stream Off"
• Toggle Recording: Shows "Record On" or "Record Off"
• Pause Recording: Shows "Recording" or "Paused"
• Toggle Replay Buffer: Shows "Replay On" or "Replay Off"
• Toggle Virtual Camera: Shows "VCam On" or "VCam Off"
• Toggle Studio Mode: Shows "Studio On" or "Studio Off"
• Toggle Source: Shows "Visible" or "Hidden"
• Toggle Mute: Shows "Muted" or "Unmuted"
• Toggle Filter: Shows "Filter On" or "Filter Off"

Troubleshooting

"Connection failed" — Verify that OBS Studio is running and WebSocket is enabled in Tools > WebSocket Server Settings. Check that the host, port, and password are correct.

"Scene not found" — Ensure the scene name matches exactly (case-sensitive) an existing scene in OBS. Use the Switch Scene action's Property Inspector to select from available scenes.

"Source/Filter not found" — Verify the source or filter name exists in the scene and matches exactly (case-sensitive).

"Action failed: WebSocket disconnected" — The connection to OBS was lost. Press the Setup button again to reconnect.

"Hotkey not found" — Check that the hotkey name matches a configured OBS hotkey. Use the exact name as shown in OBS settings.

Development

Project Structure

obs-opendeck/
├── src/
│   ├── main.rs              # Plugin entry point and message dispatcher
│   ├── obs.rs               # OBS WebSocket client
│   ├── settings.rs          # OpenDeck property persistence
│   └── actions/             # Individual action implementations
│       ├── setup.rs
│       ├── scenes.rs
│       ├── streaming.rs
│       ├── recording.rs
│       ├── sources.rs
│       └── ... (other actions)
├── plugin/
│   ├── manifest.json        # Plugin metadata
│   ├── pi/                  # Property Inspector HTML/CSS/JS
│   └── actions/             # Action icons
├── Cargo.toml               # Rust dependencies
├── Makefile                 # Build and install targets
└── README.md                # This file

Running Tests

make test

License

This plugin is open source. See LICENSE file for details.

Support

For issues, feature requests, or contributions, visit the GitHub Issues page.