113 lines
2.4 KiB
Markdown
113 lines
2.4 KiB
Markdown
# 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
|