linux-mid-scroll

Windows-style middle-click autoscroll for Linux.
A lightweight, zero-dependency background daemon written in C that brings seamless middle-click autoscrolling to both X11 and Wayland.

---

Warning

Beta Release / Under Active Development
linux-mid-scroll is currently in active beta. While it runs purely in userspace and is designed with kernel-level fail-safes, hardware quirks across different laptop touchpads and mice may exist. If you encounter any issues or have feedback, please open an Issue or pull request!

---

⚡ Highlights & Features

• Windows-Style Click-Toggle: Click the middle button (or laptop gesture) once to anchor the cursor; move your mouse or slide your finger across the trackpad to scroll dynamically.
• Accidental Click Prevention (Click Consumption): Clicking any button or tapping the trackpad deactivates autoscroll immediately. The dismissing click is consumed so you never accidentally click links, close tabs, or move text cursors.
• Built for Both Desktop Mice & Laptop Touchpads:
  • Mice: Uses standard middle click (BTN_MIDDLE).
  • Touchpads / Laptops:
    • Three-Finger Tap: Native Windows Precision Touchpad gesture (BTN_TOOL_TRIPLETAP).
    • Left + Right Click Chord: Click left and right buttons simultaneously to toggle autoscroll (for laptop trackpads without physical middle buttons).
• High-Resolution Smooth Scrolling: Supports kernel 5.0+ high-resolution wheel events (REL_WHEEL_HI_RES / REL_HWHEEL_HI_RES) for buttery-smooth scrolling.
• Ultra-Lightweight & Efficient:
  • Written in clean C11.
  • Consumes 0.00% CPU while idle (sleeps on kernel hardware interrupts).
  • Uses only ~30 KB to 50 KB of private RAM.
  • Zero runtime dependencies beyond standard glibc and pthreads.
• Display Server Agnostic: Operates at the kernel input subsystem layer (evdev & uinput), working identically across X11, Wayland, GNOME, KDE Plasma, Sway, Hyprland, etc.

---

📋 Requirements

• Linux kernel with /dev/uinput enabled (default on virtually all modern distributions)
• gcc and make
• User membership in the input group (sudo usermod -aG input $USER)

---

🚀 Quick Start

1. Build from Source

git clone https://github.com/sakibreza229/linux-mid-scroll.git
cd linux-mid-scroll
make

2. Manual Testing (Optional)

Run directly in foreground to test with your hardware:

sudo ./build/midscroll-bin

3. Install as a Systemd User Service

Install the binary, udev rules, and systemd service:

sudo make install

Ensure your user is in the input group:

sudo usermod -aG input $USER
sudo udevadm control --reload-rules && sudo udevadm trigger

Log out and back in once (to apply group membership), then enable and start the user service:

systemctl --user enable --now midscroll.service

To view live logs:

journalctl --user -u midscroll -f

---

🧹 Uninstallation

To cleanly stop the service and remove all installed files:

systemctl --user stop midscroll.service
sudo make uninstall

---

⚙️ Configuration & Tuning

Configuration follows standard precedence (lowest to highest):
Compiled defaults $\rightarrow$ ~/.config/midscroll/config.conf $\rightarrow$ MIDSCROLL_* Environment Variables

You can copy the provided example configuration file:

mkdir -p ~/.config/midscroll
cp midscroll.conf.example ~/.config/midscroll/config.conf

Available Settings

Key	Environment Variable	Default	Description
DEADZONE_RADIUS	MIDSCROLL_DEADZONE_RADIUS	40	Radius in pixels around anchor before scrolling starts
SENSITIVITY	MIDSCROLL_SENSITIVITY	1.0	Global speed multiplier
MAX_SPEED	MIDSCROLL_MAX_SPEED	45	Maximum scroll speed cap (units/tick)
CURVE	MIDSCROLL_CURVE	quadratic	Acceleration curve: linear, quadratic, cubic, or smoothstep
EMULATE_MIDDLE	MIDSCROLL_EMULATE_MIDDLE	1	1 = Enable 3-finger tap & Left+Right chord for laptops; 0 = physical middle button only
AXIS_LOCK	MIDSCROLL_AXIS_LOCK	both	both, vertical_only, horizontal_only, or dominant_snap
INVERT_V	MIDSCROLL_INVERT_V	1	Vertical scroll direction (1 = normal, -1 = inverted)
INVERT_H	MIDSCROLL_INVERT_H	1	Horizontal scroll direction (1 = normal, -1 = inverted)
TICK_HZ	MIDSCROLL_TICK_HZ	60	Scroll injection update rate in Hz
USE_HIRES_WHEEL	MIDSCROLL_USE_HIRES_WHEEL	1	1 = Attempt high-resolution wheel events first
DEVICE_PATH	MIDSCROLL_DEVICE_PATH	"" (auto)	Explicit path like /dev/input/event3 (skips auto-detection)

---

🛠️ How It Works Under the Hood

1. Device Discovery & Scoring: Automatically scans /dev/input/event* nodes and scores pointer devices. It intelligently selects desktop mice (BTN_MIDDLE) or laptop touchpads (BTN_LEFT + BTN_TOOL_TRIPLETAP).
2. Exclusive Hardware Grab: Takes an exclusive grab (EVIOCGRAB) on the physical pointer so raw middle-clicks or drag gestures aren't forwarded directly to the desktop.
3. Virtual Pointer Device: Creates a virtual mouse via /dev/uinput that re-emits standard pointer movements, clicks, and synthetic scroll events.
4. Anchor & Velocity Calculation: When autoscroll is activated, physical cursor coordinates freeze in place, and displacement relative to the anchor calculates scroll speed based on the selected acceleration curve.
5. Kernel Fail-Safe Protection: The device grab is strictly tied to the open file descriptor in the Linux kernel. If the daemon stops, exits, or is terminated (kill -9), the kernel immediately and automatically drops the grab and restores full native mouse control.

---

🤝 Contributing & Collaboration

Contributions, feedback, and hardware reports are warmly welcomed!

Ways You Can Help:

• Hardware Testing: Test on various laptop trackpads (Synaptics, ELAN, ALPS, Apple) and desktop mice across different Linux distros (Arch, Debian, Ubuntu, Fedora, NixOS).
• Packaging: Help create packages for popular package managers (AUR/PKGBUILD, .deb, .rpm, COPR, Flatpak).
• Feature Ideas:
  • Visual HUD / on-screen scroll anchor icon (Wayland layer-shell / X11 overlay).
  • Dynamic config hot-reloading (without service restart).
  • Momentum / inertia scrolling on release.
• Code Optimization: Help refine input chording and edge-case handling.

Pull Requests:

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License.