Crate hotkey_listener 

Cross-platform global hotkey listener with native Wayland support.

This crate provides a simple API for listening to global hotkeys on Linux and macOS. Unlike other crates, it uses evdev directly on Linux, making it compatible with both X11 and Wayland.

Features

• Native Wayland support on Linux - Uses evdev directly (reads /dev/input)
• Automatic keyboard reconnection - Handles USB keyboard disconnect/reconnect
• Modifier key support - Parse and detect Shift+F8 style hotkey combinations
• Simple push-to-talk API - Clean pressed/released event model
• Automatic cleanup - Background thread stops when handle is dropped
• Cross-platform - Linux (evdev) + macOS (rdev) with unified API

Example

use hotkey_listener::{parse_hotkey, HotkeyListenerBuilder, HotkeyEvent};
use std::time::Duration;

fn main() -> anyhow::Result<()> {
    let hotkey = parse_hotkey("Shift+F8")?;

    // Build and start the listener - no manual shutdown flag needed
    let handle = HotkeyListenerBuilder::new()
        .add_hotkey(hotkey)
        .build()?
        .start()?;

    // Receive hotkey events
    loop {
        match handle.recv_timeout(Duration::from_millis(100)) {
            Ok(HotkeyEvent::Pressed(idx)) => println!("Hotkey {} pressed", idx),
            Ok(HotkeyEvent::Released(idx)) => println!("Hotkey {} released", idx),
            Err(_) => { /* timeout, check exit conditions */ }
        }
    }

    // Background thread stops automatically when `handle` is dropped
}

Linux Requirements

On Linux, the user must have permission to read from /dev/input/event* devices. This typically means running as root or being a member of the input group.

Structs

Hotkey

A hotkey consisting of a key and optional modifiers.

HotkeyListener

A hotkey listener that runs in a background thread.

HotkeyListenerBuilder

Builder for creating a hotkey listener.

HotkeyListenerHandle

Handle for receiving hotkey events.

Modifiers

Modifier keys that can be combined with a hotkey.

Enums

HotkeyEvent

Events emitted when a registered hotkey is pressed or released.

Key

Platform-agnostic key representation.

Functions

find_keyboards

Find all keyboard devices in /dev/input.

parse_hotkey

Parse a hotkey string like “Shift+F8” or “F10” into a Hotkey.