pydeck

A browser-based Stream Deck for Windows. Run it on your PC, open the URL on your phone or tablet on the same Wi-Fi, and tap buttons to drive OBS, monitors, audio, hotkeys, and shell commands.

Features

• OBS — scene switching with live active-scene highlighting; per-scene Sources panel; OBS Audio Mixer with mute toggle and per-input volume sliders, all live over the OBS WebSocket.
• Monitors — switch display topology by loading saved MultiMonitorTool .cfg files (positions, primary, resolution restored, not just enabled/disabled).
• System — global hotkeys, system audio mute and volume, focus a window by title glob, "show desktop", arbitrary .exe/.bat/shell commands.
• Web admin — pages and buttons editable from /admin (no file editing); changes pushed live to every connected deck via WebSocket.
• Status window — small Tk window on the host machine with start/stop and a live log view; closing it stops pydeck.
• One-file exe — pyinstaller pydeck.spec produces dist/pydeck.exe with an embedded UAC manifest.

Requirements

• Windows 10 or 11
• Python 3.10+ (only for running from source — the packaged exe is self-contained)
• OBS Studio 28+ with the built-in WebSocket server enabled (Tools → WebSocket Server Settings)
• MultiMonitorTool (optional — only needed for the display action type)

Quick start

git clone https://github.com/quagtus/pydeck.git
cd pydeck
python -m venv .venv
.venv\Scripts\activate
pip install -e .
pydeck

A status window opens. On your phone (same Wi-Fi), open http://<your-pc-ip>:8765. Find the IP with ipconfig or the Copy URL button in the status window.

Display actions and game-targeted hotkeys require elevation (MultiMonitorTool and the keyboard library both need administrator privileges). Either run the exe (which embeds a UAC manifest) or launch PowerShell as administrator before pydeck.

Building a standalone exe

powershell -ExecutionPolicy Bypass -File scripts\build.ps1

Output: dist\pydeck.exe. Drop a shortcut to it into your Startup folder (Win+R → shell:startup) to auto-start at logon. The exe shows a UAC prompt once per launch because it requests elevation.

Cross-building from Linux

./scripts/build-windows.sh

Uses Docker + Wine + Windows Python (tobix/pywine:3.12) to produce a real Windows exe. Requires Docker. The first run pulls a ~1 GB image. Override the image with PYDECK_BUILD_IMAGE=tobix/pywine:3.11 ./scripts/build-windows.sh.

Admin UI

Open /admin (or tap ⚙ in the deck header). You can:

• Edit server, OBS, and tools settings. Changing server.host / server.port restarts pydeck and redirects the browser to the new URL.
• Add, rename, reorder, and delete pages.
• Add, edit, reorder, and delete buttons. The button editor adapts its form to the chosen action type.
• For display buttons, pick from a dropdown of .cfg files in your configured monitor-configs folder.

All changes save to a SQLite database at %LOCALAPPDATA%\pydeck\pydeck.db and broadcast over WebSocket — phones refresh instantly.

The first OBS Scenes page is auto-generated from the OBS WebSocket — you don't need to (and shouldn't) create obs_scene buttons manually. Adding, renaming, or deleting scenes in OBS reflects on the deck immediately.

Action types

Type	Fields	Notes
obs_mute	source, optional value: true/false	Toggle or set mute of an OBS audio input.
display	load_config: <path> (preferred) or mode: only|all|enable|disable with optional monitors: [1,2,3]	Uses MultiMonitorTool. See Saving display topologies.
shell	cmd, optional cwd	Runs via cmd.exe; supports .bat, PATH lookups, etc.
hotkey	keys: ["ctrl","shift","m"]	Sends a global key combo.
window	focus: "<title-glob>" or minimize_all: true	Brings a matching window forward, or "show desktop".
audio	op: mute_toggle|mute|set|vol_up|vol_down, optional value	System speaker volume / mute.

OBS scenes themselves are handled by the auto-generated Scenes page — no obs_scene action needed.

Saving display topologies

MultiMonitorTool /enable and /disable only toggle the active flag — Windows may renumber monitors, so "all three" can come back in the wrong order. The reliable approach is to save a full topology config once and load it on demand:

1. Pick a folder, e.g. C:\Tools\monitors\.
2. Arrange the topology you want in Windows display settings.
3. Save it:

   MultiMonitorTool.exe /SaveConfig "C:\Tools\monitors\all_3.cfg"

4. Repeat for each topology (only_1.cfg, only_2.cfg, etc.).
5. In the pydeck status window, click Browse… next to "Monitor configs folder" and pick that folder.
6. In the admin UI, create display buttons — each one's "Saved topology" dropdown lists every .cfg in that folder.

Custom CSS

Drop a file at %LOCALAPPDATA%\pydeck\custom.css to override the look of the deck and admin pages. It's loaded last, so your rules take precedence. No restart needed; refresh the browser.

.btn { font-size: 1.2rem; }
body { font-family: "JetBrains Mono", monospace; }

Importing a legacy buttons.yaml

Older versions of pydeck used a YAML config file. To migrate, drop buttons.yaml next to the exe or in the working directory. On first launch pydeck imports it into the database and renames it to buttons.yaml.imported.

Configuration

• Database: %LOCALAPPDATA%\pydeck\pydeck.db (SQLite)
• Log file: %LOCALAPPDATA%\pydeck\pydeck.log (rotating, 4 × 1 MB)
• Custom CSS: %LOCALAPPDATA%\pydeck\custom.css (optional)

Override the database location with pydeck --db <path>.

Troubleshooting

• OBS dot is red — OBS WebSocket server isn't enabled, the port is wrong, or the password is wrong. Fix it in /admin → Settings.
• Display action fails with "requires elevation" — run pydeck from an elevated PowerShell window, or use the packaged exe (which prompts for UAC).
• Display action fails (other) — verify the MultiMonitorTool path in /admin; try running the exe manually.
• Hotkeys don't reach a game — the keyboard library needs admin to inject keys into elevated apps. Run pydeck elevated.
• Phone can't connect — same Wi-Fi network? IP matches ipconfig's output? Windows Firewall set to allow pydeck on private networks?
• Lost configuration — back up %LOCALAPPDATA%\pydeck\pydeck.db.

License

MIT