# OBS Keyboard Overlay

A real-time keyboard overlay for OBS Studio that highlights keys as you press them. Built for Linux using `evdev` for input capture, a Node.js WebSocket server to relay events, and a browser-based overlay that renders an ANSI keyboard layout.

Designed to work with any game — comes with a Warframe keybind preset out of the box.

---

## How it works

1. `input.py` captures raw keyboard events via `evdev`
2. It looks up each keycode in `keymap.json` and sends the mapped key name over a WebSocket
3. `server.js` receives the event and broadcasts it to all connected browser clients
4. The browser overlay (`index.html`) highlights the corresponding key on screen

Keys not present in `keymap.json` are automatically hidden on the overlay, keeping the layout intact while only showing the keys relevant to your game.

---

## Requirements

- Linux (uses `evdev` for input — not available on Windows/macOS)
- Python 3
- Node.js

---

## Setup

### 1. Python virtual environment

```bash
python -m venv venv
```

### 2. Activate the virtual environment

```bash
source venv/bin/activate
```

### 3. Install Python dependencies

```bash
pip install evdev websockets
```

### 4. Install Node dependencies

```bash
npm install
```

---

## Finding your keyboard input device

Run:

```bash
sudo evtest
```

Select the device that corresponds to your keyboard from the list. It will show the `/dev/input/event*` path — set that path in `input.py`:

```python
DEVICE_PATH = "/dev/input/event8"
```

---

## Running

Start the Python input script first, with the virtual environment active:

```bash
python input.py
```

Then, in a separate terminal, start the Node backend:

```bash
node server.js
```

Add the browser source in OBS pointing to `http://localhost:3000` and set the background to transparent.

---

## Wayland note

On Wayland, raw input access requires your user to be in the `input` group. Run:

```bash
sudo usermod -aG input $USER
```

Then reboot for the change to take effect. Without this, `evdev` will not be able to read keyboard events.

---

## Customizing keys

Edit `public/keymap.json` to control which keys appear on the overlay. Any key not listed in the file will be hidden visually but will still take up space so the keyboard shape stays intact.

A Warframe preset is included by default, covering movement, abilities, combat, and utility keys.

---

## License

MIT