Skip to main content

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

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 Cyber Neon theme Warm Mono theme

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:

  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

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-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:

{
  "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-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.

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

License

GPLv3

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)

Source distribution for vial-hud 0.1.0
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)

Table of built distributions (wheels) for vial-hud 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page