# 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**.

![screenshot](screenshot.png)

## 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](https://www.touch-base.com/). After installation, use the UPDD Commander to map the touch device to your secondary monitor.

## Quick Start

```bash
# 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:

```json
{
  "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