keyviz

keyviz is a high-performance, minimal-flat keycast overlay designed for streamers, content creators, and educators. It displays recent keyboard shortcuts, combos, and mouse clicks/scroll inputs on a transparent, always-on-top floating window.

Unlike standard tools that use high-level window system input hooks (which often fail silently under modern Wayland compositors due to security restrictions), keyviz reads events directly from Linux /dev/input/event* device nodes. This ensures 100% reliable input capture under both X11 and Wayland (including GNOME, KDE, and Hyprland).

---

Features

• X11 & Wayland Out-of-the-Box: Direct event capture from input devices avoids composite-level restrictions.
• Keyboard Combo Logging: Renders complete shortcuts, merging held modifiers with keys (e.g. Ctrl + Shift + S).
• Layout Remapping: Instantly remaps keys to standard alternative layouts for display (supports qwerty, colemak_dh, and dvorak).
• Mouse Visualizer: Displays left click (L), right click (R), middle click (M), and scroll direction (▲ / ▼).
• Dynamic CSS/Egui Palette: Bold, high-contrast, flat style that remains perfectly legible even when downscaled in screen recordings or live streams.
• Customizable Filtering: Ignore specific keys or combinations (e.g., hiding modifier tap spam like shift).
• Advanced UI Customization:
  • Fully transparent overlay mode (removes panel borders and title bar).
  • Hide keyboard or mouse rows selectively.
  • Configure overlay history limit and fading speed.

---

Prerequisites

Because keyviz accesses Linux input nodes directly, you must configure device permissions:

1. Add your user to the input group:

   sudo usermod -aG input $USER

2. Log out and log back in (or reboot) for the group membership to take effect.

Note: Without this, keyviz will not have permissions to read /dev/input and will print a permission error.

---

Installation & Building

Make sure you have Rust and Cargo installed:

git clone https://github.com/exilonium/keyviz.git
cd keyviz
cargo build --release

The compiled binary will be located at target/release/keyviz.

---

Usage & Options

Run the binary directly:

./target/release/keyviz [OPTIONS]

CLI Command Reference

keyviz shows your recent keypresses and mouse clicks/scroll as a small floating overlay, great for screen recordings and streams.

Reads input directly from /dev/input/event* (Linux), so it works under both X11 and Wayland.

Usage: keyviz [OPTIONS]

Options:
      --ignore <IGNORE>          Comma-separated list of keys to ignore (e.g. "shift,ctrl,capslock")
      --layout <LAYOUT>          Keyboard layout remap to apply for display purposes (qwerty, colemak_dh, dvorak) [default: qwerty]
      --history <HISTORY>        How many recent combos to keep on screen [default: 5]
      --fade-ms <FADE_MS>        How long (ms) an entry stays highlighted before fading [default: 1500]
      --transparent-bg           Hide the panel background/border so only the key/mouse tiles are visible, floating directly over whatever's behind the window
      --show <SHOW>              Which row(s) to display: "both" (default), "keyboard" only, or "mouse" only [possible values: both, keyboard, mouse] [default: both]
  -h, --help                     Print help

Examples

Run with QWERTY layout and default aesthetics

keyviz

Transparent mode (ideal for streaming overlays)

keyviz --transparent-bg

Filter out modifier taps

keyviz --ignore shift,ctrl,alt,super

Dvorak layout with slow fading

keyviz --layout dvorak --fade-ms 3000

Mouse visualizer only

keyviz --show mouse --transparent-bg

---

License

This project is licensed under the MIT License.