niri-touchscreen-gestures
A lightweight Python daemon that reads multi-touch events from a touchscreen via evdev, detects swipe/tap gestures, and either dispatches an action to the niri Wayland compositor or forwards synthetic input (click/scroll) to whatever window currently has focus.
Now with built-in defaults — just run niri-touchscreen-gestures with no arguments to get started with sensible 3- and 4-finger gesture mappings.
It works by:
- Listening to absolute multi-touch (MT) events from an evdev touchscreen device
- Tracking finger start/end positions, timing, and movement vectors
- Classifying swipes (up/down/left/right), taps, double-taps, long-taps, and continuous 2-finger scroll drags
- Looking up the gesture in a TOML config, scoped by the currently-focused app (queried over
niri's IPC socket), and either sending an
Actioncommand to niri or forwarding synthetic input viawlrctl(niri implements thewlr-virtual-pointer-unstable-v1/virtual-keyboard-unstable-v1protocols natively, so noydotool/uinput/root daemon is needed)
Features
- Pure event-driven: No polling, uses
evdev.InputDevice.read_loop() - Multi-finger support: Automatically counts active fingers (2–4+)
- Tap gestures: single tap, double tap, and long-press, forwarded as clicks
- Continuous scroll: 2-finger vertical drags forward live scroll deltas, not just a one-shot action
- Per-app rules: gestures can be scoped to whichever app currently has focus, with a global fallback
- Configurable mappings: TOML file maps gestures like
3-finger-leftto niri actions or forwarded input - Auto device detection: Finds the first touchscreen (or accepts explicit
--device) - Robust state machine: Pure functions for gesture classification with comprehensive tests
- Lightweight: Minimal dependencies (
evdev,pydantic,pydantic-settings,wlrctl)
Installation
This package is provided as a Nix derivation in this repository:
# In your configuration
environment.systemPackages = [
pkgs.niri-touchscreen-gestures
];
Or build it directly:
nix build .#niri-touchscreen-gestures
From PyPI (if published)
pip install niri-touchscreen-gestures
Requires Python 3.10+ and the input group (for raw evdev access).
Usage
The simplest way to run it is with no arguments — it now uses sensible built-in defaults for 3- and 4-finger gestures:
niri-touchscreen-gestures
You can still override the defaults:
# Use a custom config
niri-touchscreen-gestures --config ~/.config/niri/gestures.toml
# Change swipe sensitivity
niri-touchscreen-gestures --threshold 40
# Use a specific device (bypasses auto-detection)
niri-touchscreen-gestures --device /dev/input/event5
# Pick which niri output the touchscreen maps to (only needed with >1 output connected)
niri-touchscreen-gestures --touch-output eDP-1
Command-line options
--config PATH: Path to TOML configuration file (optional — uses built-in defaults)--threshold N(default: 60): Minimum pixels of movement to register a swipe--device /dev/input/eventX: Explicit evdev device (bypasses auto-detection)--touch-output NAME: Name of the niri output the touchscreen is mapped to (e.g.eDP-1, matching niri'sinput { touch { map-to-output "..." } }config). Forwarded clicks are placed at the tapped location by mapping the raw touch coordinate onto this output's logical geometry (queried from niri'sOutputsIPC request). If omitted, the daemon auto-selects the sole enabled output — pass this explicitly once a second monitor is connected.
The program must run with access to /dev/input/event* devices (typically via the input group) and with the NIRI_SOCKET environment variable set.
Forwarded clicks click where you tapped
Since wlrctl pointer move is relative-only (no absolute positioning, and no way to query the
pointer's current position), a forwarded click warps the pointer to the tapped location before
clicking: one large relative move clamps it to niri's logical origin (0, 0), then a second move
by the tap's mapped logical coordinate lands it exactly there. This assumes niri's default
layout (some output at (0, 0), outputs arranged contiguously) — an unusual multi-monitor
arrangement with gaps could make this land in the wrong spot, but this isn't a concern on a
single-display laptop.
Configuration
The tool ships with sensible defaults that match the example below. You only need to provide a config file if you want to customize the mappings.
See example-config.toml:
[global]
"3-finger-up" = "FocusWorkspaceDown"
"3-finger-down" = "FocusWorkspaceUp"
"3-finger-left" = "FocusColumnRight"
"3-finger-right" = "FocusColumnLeft"
"4-finger-up" = "ToggleOverview"
"4-finger-down" = "ToggleOverview"
[apps."dev.zed.Zed"]
"1-finger-tap" = "forward:click-left"
"1-finger-double-tap" = "forward:click-right"
"1-finger-long-tap" = "forward:click-right"
"2-finger-scroll" = "forward:scroll"
The [global] table's mappings are the built-in defaults. [apps."<app-id>"] tables add
rules that only apply while that app has focus (matched by its Wayland app_id, as reported by
niri's FocusedWindow IPC query) and take priority over [global] for the same key.
Gesture keys:
"<N>-finger-<direction>"— swipe,direction=up/down/left/right"1-finger-tap"/"1-finger-double-tap"/"1-finger-long-tap"— tap gestures"<N>-finger-scroll"— continuous drag scroll (currently supported forN = 2)
Action values:
- A niri action name (see below, or niri's config.rs)
"forward:click-left"/"forward:click-right"/"forward:scroll"— synthetic input forwarded to the focused window viawlrctl
Tip: Place a custom config at ~/.config/niri/gestures.toml and launch the daemon from a user systemd service or your niri startup script.
Supported niri Actions
Currently typed for these common actions (more can be added easily):
FocusWorkspaceUpFocusWorkspaceDownFocusColumnLeftFocusColumnRightToggleOverview
See nirictl.py for the list.
How It Works
- Device Selection:
touchscreen_identifier.pyscans/dev/inputfor devices withEV_ABScapabilities that aren't mice or touchpads. - Event Loop: Reads raw
EV_ABSevents (ABS_MT_SLOT,ABS_MT_TRACKING_ID,ABS_MT_POSITION_X/Y). - State Tracking: Maintains per-slot (per-finger) start/current coordinates and start time.
- Gesture Detection: On finger lift (
TRACKING_ID == -1), classifies a tap/long-tap (low movement) or a swipe (movement past threshold). A lone tap is held for a short debounce window (via a background timer) to see if a second tap follows and it becomes a double-tap. 2-finger vertical drags stream continuous scroll deltas on every position update, instead of waiting for lift. - Focused-app resolution: Queries niri's
FocusedWindowIPC request (once per gesture, cached for its duration) and resolves the gesture key against[apps."<app-id>"]first, falling back to[global]. - Dispatch: Niri actions are sent as JSON over niri's IPC socket;
forward:*actions are sent to the focused window viawlrctl pointer click/scroll.
All core logic is in detector/gestures.py and is unit-tested.
Development
# Enter dev shell (includes the package + test deps)
nix develop
# Run tests
pytest
# Run with example config
NIRI_SOCKET=/run/user/$(id -u)/niri/socket \
niri-touchscreen-gestures --config example-config.toml
The project uses:
hatchlingfor buildingpydanticfor config validation- Pure functions where possible for testability
License
MIT. See LICENSE (or the default.nix meta).
See Also
- niri — The scrollable-tiling Wayland compositor
- niri's IPC — JSON socket protocol used
- evdev — Linux input event interface
Part of nixos-setup by Ari Sosnovsky.