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 {.
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
.vilfile. 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-TapandTap+Holdactions. - 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 |
|---|---|---|
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)
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:
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
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
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:
- A connected Vial keyboard (USB HID)
- The last
.vilfile you used ./current_layout.vil- 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
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:
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-throughto 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:
{
"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/ are worth reading as examples.
KDE Plasma / Wayland notes
- On KDE,
vial-hudinstalls a KWin window rule for you (Keep Above + All Desktops), so the overlay stays on top under Wayland. To install it by hand, runvial-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.
pip install -e '.[test]'
python3 -m unittest discover -s tests
License
Metadata
Release files for vial-hud 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vial_hud-0.1.0.tar.gz | 84.8 kB | Without provenance | Details for vial_hud-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vial_hud-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for vial_hud-0.1.0-py3-none-any.whl |
Total release size: 163.9 kB
Release files / vial_hud-0.1.0.tar.gz
| Download URL | vial_hud-0.1.0.tar.gz |
|---|---|
| Size | 84.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
33f4ebebad06fd7e1b323a30e1bd3069bd6e80d485be9adf0d2e0df2f2af7d60
|
|
BLAKE2b-256 checksum How to use checksums |
1493716731077171ea19ab348c2f2ee2b9dde67adab8e30e1352f10095220573
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / vial_hud-0.1.0-py3-none-any.whl
| Download URL | vial_hud-0.1.0-py3-none-any.whl |
|---|---|
| Size | 79.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dbeeffed6f3633af93e2c41fe9a7223e2f12941258eed43a691a775d216b5dcb
|
|
BLAKE2b-256 checksum How to use checksums |
0de5aaf9316c04686de8c9eaa819e8ab6c4543323a971202a17c6c81bf9fc753
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for vial-hud 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.