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

python -m venv venv

2. Activate the virtual environment

source venv/bin/activate

3. Install Python dependencies

pip install evdev websockets

4. Install Node dependencies

npm install

---

Finding your keyboard input device

Run:

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:

DEVICE_PATH = "/dev/input/event8"

---

Running

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

python input.py

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

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:

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