StreamDeck – Custom Touchscreen Stream Deck

A native macOS Stream Deck replacement for HDMI touchscreens. Built with Electron, it stays on a dedicated secondary monitor and sends keystrokes/clipboard/shell commands to whatever app you're working in — without stealing focus.

Features

Full grid of programmable buttons – 6×3 configurable per page
Multiple pages – swipe or tap arrows/dots to navigate
Realtime system monitor page – CPU usage (overall + per-core), memory usage, uptime, load
Native macOS actions:
- keystroke – sends keyboard shortcuts to your currently active app (e.g. cmd+v, ctrl+up, space)
- copy / paste / cut – clipboard operations via NSPasteboard
- shell – runs shell commands
- osascript – runs AppleScript
- app – opens any macOS application
- url – opens URLs in default browser
- sleep – puts Mac to sleep
Touchscreen-optimized – large touch targets, frameless window, auto-fullscreen
No focus stealing – app hides itself before sending keystrokes, so clipboard and shortcuts go to your previous app, not the StreamDeck

Requirements

macOS (tested on Sequoia 15.x)
Node.js 18+ (for development / npm install)
Touchscreen with USB touch controller (e.g. WCH USB2IIC_CTP_CONTROL)
Touch-Base / UPDD touch driver – required separately! The touchscreen will not work without this driver on macOS. Download and install from touch-base.com. After installation, use the UPDD Commander to map the touch device to your secondary monitor.

Quick Start

# 1. Install dependencies
cd streamdeck
npm install

# 2. Copy config template and customize
cp config.template.json config.json
# Edit config.json to set up your buttons

# 3. Run!
./start.sh             # Electron app (touchscreen)
# or
./start.sh server      # Web-based mode for testing in browser

For the Electron app:

The window opens automatically on your second monitor (touchscreen)
Fullscreen is enabled automatically on start
Press F11 to toggle fullscreen
Press F2 to show the debug event overlay

Button Configuration

Edit config.json. Each button can have:

{
  "label": "Button Name",
  "icon": "🔔",
  "color": "blue",
  "actions": [
    { "type": "keystroke", "value": "cmd+v" },
    { "type": "shell", "value": "open -a Safari" }
  ]
}

Available action types

Type	Value	Effect
`keystroke`	`cmd+v`, `ctrl+shift+z`, `space`, `f2`	Sends keyboard shortcut to active app
`shell`	`open -a Safari`	Runs shell command in background
`osascript`	`set volume 50`	Runs AppleScript
`app`	`Visual Studio Code`	Opens application
`url`	`https://github.com`	Opens URL in browser
`copy`	none	Copies selected text (Cmd+C)
`paste`	`optional text`	Pastes text (Cmd+V)
`cut`	none	Cuts selected text (Cmd+X)
`sleep`	none	Puts Mac to sleep

Key syntax

Modifiers: cmd, ctrl, alt, shift
Special keys: up, down, left, right, space, return, tab, escape, f1–f12
Combine with + (e.g. cmd+shift+z, ctrl+up)
Regular characters are typed literally (e.g. a, 1, Hello)

Project Structure

streamdeck/
├── config.json              # Your button configuration (local, not in git)
├── config.template.json     # Template for config
├── electron-main.js         # Electron main process (window, IPC, actions)
├── preload.js               # Context bridge (renderer ↔ main)
├── server.js                # Node.js web server for browser mode
├── package.json
├── start.sh                 # Convenience launcher
├── public/
│   ├── index.html
│   ├── app.js               # Frontend logic
│   └── style.css            # Touch-optimized UI
└── README.md

License

MIT

4.0 KiB Raw Blame History Unescape Escape