Metadata-Version: 2.4
Name: vial-hud
Version: 0.1.0
Summary: Translucent always-on-top Vial split keyboard layout & layer HUD overlay for Fedora KDE Plasma 6 (Wayland)
Author: Vial HUD Contributors
License: MIT
Project-URL: Homepage, https://gitlab.com/ykarus117/vial-on-screen
Project-URL: Repository, https://gitlab.com/ykarus117/vial-on-screen.git
Project-URL: Issues, https://gitlab.com/ykarus117/vial-on-screen/-/issues
Keywords: vial,qmk,corne,split-keyboard,keyboard-overlay,hud,wayland,kde-plasma,pyqt6
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.5.0
Requires-Dist: hidapi>=0.14.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# vial-hud

**An on-screen keymap for your Vial split keyboard.**

`vial-hud` shows your keyboard's current layer in a transparent window that stays on top of everything else on your desktop. It reads the layout straight from your keyboard over USB, so the overlay always matches what's actually flashed: every layer, Mod-Tap, Layer-Tap and Tap Dance. It's useful when you're learning a new layout or trying to remember where you put `{`.

![vial-hud showing the base layer of a Corne v4, with two keys highlighted as pressed and the Tap Dance legend along the bottom](docs/screenshots/hud_default.png)

Built with Python and PyQt6, primarily for **Fedora KDE Plasma 6 (Wayland)**.

---

## Features

- **Reads your layout live from the keyboard** over the Vial raw HID protocol: KLE geometry, all layers, Mod-Tap / Layer-Tap and Tap Dance definitions.
- **Hotplug aware.** A Netlink watcher spots USB connect/disconnect and reloads the layout on its own.
- **Works offline** with an exported `.vil` file. If nothing else is available it falls back to a built-in 46-key Corne v4 layout.
- **Highlights keys as you press them** without grabbing input from other apps. It only listens.
- **Layer switching** with `Ctrl+Shift+←/→/↑/↓`, the mouse wheel, right-click, by clicking a layer key, or from a script/global shortcut.
- **Tap Dance legend** listing each Tap Dance's `Tap`, `Hold`, `Double-Tap` and `Tap+Hold` actions.
- **Adjustable split gap:** put the two halves at the screen edges (`100%`) or right next to each other (`0%`).
- **Idle behaviour:** after a period of inactivity it either dims or hides, and comes back when you type or move the mouse.
- **Themeable** through JSON style files. Four themes are included.
- **System tray, Settings window, XDG autostart** and remote-control commands.

## Themes

| `stealth_glass` | `cyber_neon` | `warm_mono` |
| :---: | :---: | :---: |
| ![Stealth Glass theme](docs/screenshots/hud_stealth_glass.png) | ![Cyber Neon theme](docs/screenshots/hud_cyber_neon.png) | ![Warm Mono theme](docs/screenshots/hud_warm_mono.png) |

Pick one with `vial-hud --style <name>` or from the tray menu. The theme shown at the top of this page is `default`.

---

## Installation

### 1. System dependencies (Fedora)

```bash
sudo dnf install python3-pyqt6 python3-hidapi hidapi python3-setuptools python3-wheel
```

### 2. Allow USB HID access without root

This udev rule lets your user talk to the Vial raw HID interface:

```bash
echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{serial}=="*vial:f64c2b3c*", MODE="0660", GROUP="users", TAG+="uaccess", TAG+="udev-acl"' \
  | sudo tee /etc/udev/rules.d/99-vial.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
```

> If the Vial desktop app can already see your keyboard, you probably have this rule set up already.

### 3. Install `vial-hud`

```bash
git clone https://gitlab.com/ykarus117/vial-on-screen.git
cd vial-on-screen
pip install -e .
```

To update, run `git pull`. To uninstall, run `pip uninstall vial-hud`, then remove `~/.config/vial-hud` if you don't want to keep your settings.
---

## Usage

```bash
vial-hud
```

That's all you need. It detaches from the terminal, puts an icon in the system tray and loads your layout from the first available source:

1. A connected Vial keyboard (USB HID)
2. The last `.vil` file you used
3. `./current_layout.vil`
4. The built-in Corne v4 sample

Logs are written to `~/.config/vial-hud/vial-hud.log`. Add `-f` / `--foreground` to keep it attached to the terminal.

### Common options

```bash
vial-hud --settings                   # Open the Settings window
vial-hud --vil my_layout.vil          # Load an exported Vial .vil file
vial-hud --style cyber_neon           # Built-in theme or path/to/style.json
vial-hud --split-gap 80               # Split spacing, 0 (centered) … 100 (screen edges)
vial-hud --auto-dim                   # Dim when idle…
vial-hud --idle-action hide           # …or hide completely ('dim' | 'hide')
vial-hud --click-through              # Let mouse clicks pass through the overlay
vial-hud --no-pressed-keys            # Don't highlight pressed keys
vial-hud --autostart                  # Start on login (--no-autostart to undo)
```

Run `vial-hud --help` to see every option.

### Remote control

When an instance is running, these commands control it. You can bind them to global shortcuts in **KDE System Settings → Shortcuts**:

```bash
vial-hud --toggle                     # Show / hide
vial-hud --next-layer                 # Next layer
vial-hud --prev-layer                 # Previous layer
vial-hud --layer 1                    # Jump to a specific layer
vial-hud --toggle-click-through
vial-hud --toggle-always-on-top
vial-hud --quit
```

### Mouse & keyboard (with the overlay focused)

| Input | Action |
| --- | --- |
| Left-drag | Move the window |
| Drag bottom-right corner | Resize |
| Click a layer key | Jump to that layer |
| Right-click / mouse wheel | Cycle layers |
| `Ctrl` + wheel | Adjust opacity |
| `1`–`9`, `0` | Jump to layer N / base layer |
| `←` `→` / `Tab` | Previous / next layer |
| `+` / `-` | Scale up / down |
| `[` / `]` | Opacity down / up |
| `C` / `P` | Toggle click-through / always-on-top |
| `G` | Toggle showing base-layer labels on transparent keys |
| `R` | Reload layout from USB |
| `S` | Load a style file |
| `H` / `Esc` | Hide |
| `Q` | Quit |

> Mouse input is ignored while click-through is on. Use the tray icon or `vial-hud --toggle-click-through` to turn it off.

---

## Configuration

Settings are saved automatically to `~/.config/vial-hud/settings.json`. The easiest way to change them is the **Settings** window, opened from the tray or with `vial-hud --settings`.

### Custom styles

Styles are JSON files, and `//` comments are allowed. To get the full default template as a starting point, use **tray → Style → Save Default Style** (it is written to `~/.config/vial-hud/style.json`). Then load it with `--style path/to/style.json`.

Your file only needs the keys you want to change. Everything else is filled in from the defaults:

```json
{
  "window": {
    "width": 1440,
    "height": 500,
    "opacity": 0.90
  },
  "auto_dim": {
    "enabled": true,
    "idle_seconds": 6.0,
    "dim_opacity": 0.20
  },
  "keys": {
    "border_width": 1.4,
    "corner_radius_ratio": 0.14,
    "font_family": "Sans Serif"
  },
  "categories": {
    "normal": {
      "bg": "transparent",
      "border": "rgba(226, 232, 240, 0.55)",
      "text": "#f8fafc",
      "badge": "#cbd5e1"
    }
  }
}
```

The bundled themes in [`vial_hud/assets/themes/`](vial_hud/assets/themes/) are worth reading as examples.

---

## KDE Plasma / Wayland notes

- On KDE, `vial-hud` installs a **KWin window rule** for you (Keep Above + All Desktops), so the overlay stays on top under Wayland. To install it by hand, run `vial-hud --install-kwin-rule`.
- Key highlighting is passive: it never grabs or blocks input meant for other windows.

## Development

For detailed architecture diagrams, subsystem deep dives (USB HID protocol, keycode decoding, Wayland/KWin rules, IPC server, input monitoring), and engineering guidelines, see [DEVELOPMENT.md](DEVELOPMENT.md).

```bash
pip install -e '.[test]'
python3 -m unittest discover -s tests
```

## License

[GPLv3](LICENSE)
