niri-touchscreen-gestures
A lightweight Python daemon that reads multi-touch events from a touchscreen via evdev, detects 2/3/4-finger swipe gestures, and dispatches configurable actions to the niri Wayland compositor.
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 and movement vectors
- Classifying swipes (up/down/left/right) once they exceed a configurable pixel threshold
- Looking up the gesture in a TOML config and sending an
Actioncommand to niri's Unix socket ($NIRI_SOCKET)
Features
- Pure event-driven: No polling, uses
evdev.InputDevice.read_loop() - Multi-finger support: Automatically counts active fingers (2–4+)
- Configurable mappings: TOML file maps gestures like
3-finger-leftto niri actions - 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)
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
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)
The program must run with access to /dev/input/event* devices (typically via the input group) and with the NIRI_SOCKET environment variable set.
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:
# Example config for niri-touchscreen-gestures
#
# Keys are "<N>-finger-<direction>" where:
# N = 2, 3, 4 (or more)
# direction = up | down | left | right
#
# Values are niri actions. See https://github.com/YaLTeR/niri/blob/main/src/niri/config.rs
# for the full list of available actions.
"3-finger-up" = "FocusWorkspaceDown"
"3-finger-down" = "FocusWorkspaceUp"
"3-finger-left" = "FocusColumnRight"
"3-finger-right" = "FocusColumnLeft"
"4-finger-up" = "ToggleOverview"
"4-finger-down" = "ToggleOverview"
These exact mappings are now the built-in defaults. You can map gestures to any niri action that accepts no parameters.
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 and current coordinates.
- Gesture Detection: On finger lift (
TRACKING_ID == -1), computes delta and classifies direction if movement exceeds threshold. - Action Dispatch: Looks up
"{finger_count}-finger-{direction}"in config and sends JSON command to niri's IPC socket.
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.