scroll-throttle

Rate-limits X11 scroll-wheel events. Fixes unusably fast scrolling caused by a high-resolution trackpad (e.g. a Mac's) relayed through a remote desktop protocol (RDP, VNC, etc.) to a Linux X11 session.

The problem

Real trackpad hardware reports finger position at high frequency with sub-pixel precision, and the client OS turns that into smooth, physics-based scrolling (velocity tracking, momentum, deceleration). When a trackpad gesture is relayed over RDP to a remote X11 session, none of that velocity-aware smoothing survives the trip - the client just translates the raw high-resolution motion into a flood of discrete scroll-wheel "click" events (X11 button 4/5), sometimes hundreds of them for a single gesture. The remote session has no way to tell "one deliberate scroll notch" apart from "the tail end of a fast swipe," so scrolling ends up flying past whatever you're trying to read.

A fixed drop ratio (e.g. "only keep 1 in 10 events") doesn't reliably fix this, because burst size varies - keeping 10% of an enormous burst can still be a lot of events landing in a tight cluster. This tool instead enforces a minimum time interval between forwarded events, independent of how many raw events arrive in a burst, which caps the perceived scroll speed to a consistent, tunable rate.

Ctrl/Shift/Alt+scroll (e.g. zoom) is passed through untouched, since that's normally a deliberate, discrete action rather than continuous scrolling.

Build

Requires libX11 development headers (libx11-dev on Debian/Ubuntu, libX11-devel on Fedora).

make

Run

./scroll-throttle              # default: 70ms between events (~14/sec)
./scroll-throttle -i 40        # faster: 40ms (~25/sec)
./scroll-throttle -i 150       # slower: 150ms (~6/sec)
./scroll-throttle -v           # print periodic stats to stderr

Tune -i to taste - there's no universally correct value since it depends on the client trackpad's resolution and how aggressively the RDP client translates gestures into wheel clicks. Start around 70ms and adjust.

Install

sudo make install

Installs the binary to /usr/local/bin/scroll-throttle.

Autostart

The simplest, most portable option is XDG autostart, which works across desktop environments and correctly inherits the session's DISPLAY:

mkdir -p ~/.config/autostart
cp scroll-throttle.desktop ~/.config/autostart/

Edit the Exec= line in the copied file if you want a non-default -i value.

A systemd --user unit (scroll-throttle.service) is also included for systemd-centric setups, but see the note inside it about DISPLAY inheritance on sessions (like xrdp) that don't run a full systemd --user login.

License

MIT - see LICENSE.