Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

libscroll-speed

Non-linear touchpad scroll speed optimizer for Linux (Wayland/GNOME)

An LD_PRELOAD library that intercepts libinput scroll events and applies a Hill function curve for macOS-like natural touchpad scrolling — slow movements stay precise, fast flicks are softly capped instead of flying off the page.

Developed and tuned for the ThinkPad X1 Carbon Gen 13, but configurable for any Linux laptop running libinput + GNOME/Wayland.

The Problem

The ThinkPad X1 Carbon Gen 13 (and other modern laptops) produces large raw scroll deltas through libinput, causing three issues that can't be fixed with a simple linear scroll-factor:

  1. Kinetic scrolling is uncontrollable — A fast flick sends you 50+ pages. The raw delta values are too high.
  2. Chrome scrolls 2-3x faster than other apps — Chromium-based browsers apply an internal scroll multiplier on top of Wayland's wl_pointer.axis events.
  3. No good uniform fix — Lowering scroll speed globally makes Chrome comfortable but Firefox/VSCode become painfully slow.

The Solution

libscroll-speed applies a non-linear curve (Hill function) that:

  • Slow finger movements → nearly 1:1 mapping for precise positioning (code review, text selection)
  • Fast flicks → soft speed cap that tames kinetic scrolling
  • Chrome/Chromium → automatic per-app correction detected via Mutter API
Gesture Before After
Precise positioning Overshoots Fine-grained, controlled
Fast flick Flies past content Soft cap, stays readable
Chrome vs Firefox Chrome 2-3x faster Equalized across apps

Quick Start

git clone https://github.com/mimimiku778/libscroll-speed.git
cd libscroll-speed
bash setup.sh     # builds, installs, registers in ld.so.preload

Then log out and back in to activate (gnome-shell needs to load the new library).

To tune parameters (changes apply in 3 seconds, no logout needed):

sudo nano /etc/scroll-speed.conf

How It Works

Kernel → libinput → [ libscroll-speed: Hill curve ] → Mutter → wl_pointer.axis → Apps
                                                         ↑
                                                  Chrome focused?
                                                  → apply chrome-scroll-factor

Interception

The library is registered in /etc/ld.so.preload, loading into every process. Inside Mutter (the GNOME Wayland compositor), it interposes libinput_event_pointer_get_scroll_value() via dlsym(RTLD_NEXT) and transforms the raw scroll delta before Mutter sends it to applications.

In non-Mutter processes, the interposed functions simply pass through — no libinput symbols to resolve, so the library is effectively a no-op.

Non-linear Curve (Hill Function)

f(delta) = base-speed × scroll-cap × x^n / (1 + x^n) × low-cut-filter(delta)

where:
  x = |delta| / scroll-cap
  n = ramp-softness
  low-cut-filter = delta^4 / (low-cut^4 + delta^4)    (when low-cut > 0)

The Hill function x^n / (1 + x^n) gives a sigmoid-like response:

  • At low deltas: output grows roughly proportional to input
  • At high deltas: output saturates toward base-speed × scroll-cap
  • ramp-softness > 1 further suppresses low-speed output (more "dead zone" feel)
  • low-cut adds an extra high-pass filter to eliminate jitter from resting fingers

Per-App Chrome Detection

When running inside gnome-shell, the library resolves Mutter/GNOME Shell API functions at startup:

  1. shell_global_get() → GNOME Shell singleton
  2. meta_display_get_focus_window() → Currently focused window
  3. meta_window_get_pid() → Process ID
  4. readlink("/proc/PID/exe") → Executable path

If the exe path contains chrome, chromium, or electron, chrome-scroll-factor is applied. Results are cached per PID. In non-GNOME processes, the API resolves to NULL and the feature is silently skipped.

Note: VSCode is Electron-based but its exe path doesn't contain "electron", so it's treated as a normal app. This is intentional — testing confirmed VSCode doesn't have the same internal multiplier issue as Chrome.

Hot-Reload

Every 3 seconds, the config file's modification time is checked. When it changes, all parameters are reloaded automatically. This means you can edit /etc/scroll-speed.conf, save, wait 3 seconds, and immediately feel the difference — no logout required.

Note: Updating the .so library itself (after recompilation) still requires logout/login since gnome-shell must reload the shared library.

Installation

Requirements

  • Linux with GNOME 44+ / Wayland (Ubuntu 24.04+, Fedora 40+, etc.)
  • gcc
  • libinput-dev

Option A: setup.sh (recommended)

bash setup.sh

This will:

  1. Install build dependencies if missing (gcc, libinput-dev)
  2. Build libscroll-speed.so
  3. Atomically install to /usr/local/lib/<arch>/
  4. Register in /etc/ld.so.preload
  5. Copy default config to /etc/scroll-speed.conf

Option B: Manual

make
sudo make install

Uninstall

sudo make uninstall
# or
bash uninstall.sh

Then log out and back in.

Configuration

Edit /etc/scroll-speed.conf. Changes are hot-reloaded within 3 seconds.

Parameters

Parameter Default Description
base-speed 0.76 Overall sensitivity multiplier. Max output = base-speed × scroll-cap
scroll-cap 21.0 Soft speed ceiling. At delta = scroll-cap, output is 50% of maximum
ramp-softness 1.65 Curve exponent. 1.0 = uniform, >1.0 = suppress low-speed more
low-cut 1.8 High-pass threshold (0 = disabled). Suppresses tiny movements
discrete-scroll-factor 1.0 Mouse wheel multiplier (linear, no curve)
chrome-scroll-factor 0.376 Extra multiplier when Chrome/Chromium is focused

Output Values (Default Parameters)

Input delta Output Chrome (×0.376) Feel
2 0.20 0.07 Delicate finger movement (low-cut suppressed)
5 1.34 0.51 Precise positioning
8 2.69 1.01 Casual swipe
10 3.62 1.36 Light flick
15 5.82 2.19 Fast flick
20 7.66 2.88 Strong flick
∞ 15.96 6.00 Ceiling (base-speed × scroll-cap)

Tuning Guide

Save the config file and wait 3 seconds — changes apply immediately.

sudo nano /etc/scroll-speed.conf
Goal What to change
Everything too slow/fast base-speed — scales all speeds uniformly
Low-speed jitter is annoying low-cut — increase to suppress more (try 2.0-3.0)
Want more/less acceleration feel ramp-softness — 1.0 = flat, 2.0+ = very curved
Fast flicks too fast/slow scroll-cap — higher = allows more speed
Chrome too fast vs other apps chrome-scroll-factor — lower = slower Chrome
Disable Chrome detection chrome-scroll-factor=1.0
Speed up non-Chrome, keep Chrome same Raise base-speed + lower chrome-scroll-factor proportionally

Examples

Make everything 20% faster:

sudo sed -i 's/base-speed=.*/base-speed=0.91/' /etc/scroll-speed.conf

Make Chrome even slower:

sudo sed -i 's/chrome-scroll-factor=.*/chrome-scroll-factor=0.30/' /etc/scroll-speed.conf

Speed up non-Chrome apps without changing Chrome:

# Chrome effective speed = base-speed × chrome-scroll-factor
# Current: 0.76 × 0.376 = 0.286
# Keep product constant: 0.90 × 0.318 = 0.286
sudo sed -i 's/base-speed=.*/base-speed=0.90/' /etc/scroll-speed.conf
sudo sed -i 's/chrome-scroll-factor=.*/chrome-scroll-factor=0.318/' /etc/scroll-speed.conf

Conservative defaults (for other laptops):

base-speed=0.5
scroll-cap=20.0
ramp-softness=1.0
low-cut=0
chrome-scroll-factor=1.0

Safety

  • Atomic install — The .so is installed via cp to .tmp then mv (inode swap). This prevents crashing processes that have the old library memory-mapped. Direct cp overwrites can cause a system-wide crash cascade (we learned this the hard way).
  • Graceful degradation — In non-GNOME processes, Mutter API resolves to NULL and per-app detection is silently skipped.
  • Safe fallback — If real libinput functions can't be resolved, returns 0.0.
  • Hot-reload only — Config changes are picked up automatically; the .so binary update requires re-login (no hot-swap of code).

Debugging

Set the environment variable to enable init logging:

LIBSCROLL_SPEED_DEBUG=1 gnome-shell  # writes to /tmp/scroll-speed-init.log

Compatibility

Component Requirement
Display server Wayland (X11 not supported)
Compositor GNOME/Mutter (per-app detection requires GNOME Shell API)
libinput Any version with get_scroll_value API
Architecture x86_64, aarch64 (auto-detected)

Tested Distros

Distro GNOME Status
Ubuntu 25.04 (Plucky) 48 Developed on this
Ubuntu 24.04 LTS (Noble) 46 Compatible
Fedora 40+ 46+ Compatible

The library depends only on stable, distro-independent interfaces: the libinput C API (libinput_event_pointer_get_scroll_value), /etc/ld.so.preload (glibc), and the Mutter/GNOME Shell API (shell_global_get, meta_display_get_focus_window, meta_window_get_pid). These have been unchanged across GNOME 44–48+, so any GNOME/Wayland distro should work out of the box.

The non-linear curve also works with any Wayland compositor that uses libinput (Sway, wlroots-based, etc.), but the per-app Chrome detection is GNOME-specific. On non-GNOME compositors, chrome-scroll-factor is ignored and all apps get the same curve.

Files

scroll-speed.c         Library source (libinput hook + Mutter API + hot-reload)
scroll-speed.conf      Config template (-> /etc/scroll-speed.conf)
test-interposer.c      Test harness (curve math + symbol interposition)
Makefile               Build & install automation
setup.sh               One-command setup script
uninstall.sh           Removal script

License

MIT — see LICENSE


libscroll-speed (日本語)

Linux (Wayland/GNOME) 向け非線形タッチパッドスクロール速度オプティマイザ

libinput のスクロールイベントをインターセプトし、Hill関数カーブを適用する LD_PRELOAD ライブラリ。遅い指の動きは精密に、速いフリックはソフトキャップで制御し、macOS のような自然なスクロール体験を実現します。

ThinkPad X1 Carbon Gen 13 向けに開発・チューニングしていますが、libinput + GNOME/Wayland 環境であればどのノート PC でも設定変更により利用可能です。

問題

ThinkPad X1 Carbon Gen 13(および近年の高精度タッチパッド搭載ノート PC)は libinput 経由で大きなスクロール生値を出力するため、単純な線形 scroll-factor では解決できない 3 つの問題があります:

  1. 慣性スクロールが暴走する — 速いフリックで 50 ページ以上飛ぶ。生のデルタ値が大きすぎる
  2. Chrome が他アプリより 2-3 倍速い — Chromium 系ブラウザは Wayland の wl_pointer.axis 値に内部倍率を追加適用する
  3. 均一な補正では解決不能 — Chrome に合わせると Firefox/VSCode が極端に遅くなる

解決策

libscroll-speed は 非線形カーブ(Hill 関数)を適用します:

  • 遅い指の動き → ほぼ 1:1 のマッピング(コードレビュー、テキスト選択に最適)
  • 速いフリック → ソフトな速度上限(慣性スクロール暴走を防止)
  • Chrome/Chromium → Mutter API によるアプリ別自動補正
操作 導入前 導入後
精密な位置合わせ オーバーシュート 細かく制御可能
速いフリック ページが飛ぶ ソフトキャップで読める範囲に
Chrome vs Firefox Chrome が 2-3 倍速い アプリ間で体感統一

クイックスタート

git clone https://github.com/mimimiku778/libscroll-speed.git
cd libscroll-speed
bash setup.sh     # ビルド、インストール、ld.so.preload 登録

ログアウト→再ログイン で有効化(gnome-shell がライブラリを読み込む)。

パラメータ調整(3 秒でホットリロード、ログアウト不要):

sudo nano /etc/scroll-speed.conf

動作原理

カーネル → libinput → [ libscroll-speed: Hill カーブ ] → Mutter → wl_pointer.axis → 各アプリ
                                                            ↑
                                                     Chrome フォーカス中?
                                                     → chrome-scroll-factor を適用

インターセプト

/etc/ld.so.preload に登録することで全プロセスにロードされます。Mutter(GNOME Wayland コンポジタ)内部で libinput_event_pointer_get_scroll_value() を dlsym(RTLD_NEXT) 経由でインターポーズし、生のスクロールデルタを Hill 関数で変換してからアプリケーションに渡します。

Mutter 以外のプロセスでは libinput シンボルが存在しないため、ライブラリは実質的にノーオペレーションです。

非線形カーブ(Hill 関数)

f(d) = base-speed × scroll-cap × x^n / (1 + x^n) × d^4 / (t^4 + d^4)

x = |d| / scroll-cap
n = ramp-softness
t = low-cut(0 のとき右項は省略)

Hill 関数 x^n / (1 + x^n) はシグモイド型の応答を生成:

  • 低デルタ: 出力は入力にほぼ比例(精密制御)
  • 高デルタ: base-speed × scroll-cap に漸近(飽和)
  • ramp-softness > 1: 低速域をさらに抑制(「遊び」を増やす)
  • low-cut: 指の微細な動き(慣性末端)を追加抑制する 4 次ハイパスフィルタ

アプリ別 Chrome 検出

gnome-shell プロセス内部で起動時に Mutter/GNOME Shell API を解決:

  1. shell_global_get() → GNOME Shell シングルトン
  2. meta_display_get_focus_window() → フォーカスウィンドウ
  3. meta_window_get_pid() → プロセス ID
  4. readlink("/proc/PID/exe") → 実行ファイルパス

exe パスに chrome、chromium、electron が含まれる場合、chrome-scroll-factor を適用。結果は PID ごとにキャッシュ。GNOME 以外のプロセスでは API が NULL に解決されるため、この機能は自動スキップされます。

注: VSCode は Electron ベースですが exe パスに "electron" を含まないため検出対象外。検証の結果、VSCode は Chrome ほどの内部倍率増幅がないことを確認済みです。

ホットリロード

3 秒ごとに設定ファイルの更新時刻をチェック。変更があればパラメータを自動リロード。保存→3 秒待つだけで即座に反映されます。

注: .so ライブラリ自体の更新(再コンパイル後)はログアウト→再ログインが必要です。

インストール

必要環境

  • Linux + GNOME 44+ / Wayland(Ubuntu 24.04+、Fedora 40+ 等)
  • gcc
  • libinput-dev

方法 A: setup.sh(推奨)

bash setup.sh

方法 B: 手動

make
sudo make install

アンインストール

sudo make uninstall
# または
bash uninstall.sh

ログアウト→再ログインで元のスクロール動作に戻ります。

設定

/etc/scroll-speed.conf を編集。変更は 3 秒以内にホットリロード されます。

パラメータ

パラメータ デフォルト 説明
base-speed 0.76 全体感度。最大出力 = base-speed × scroll-cap
scroll-cap 21.0 ソフトな速度上限。delta = cap で出力は最大値の 50%
ramp-softness 1.65 カーブ指数。1.0 = 均一減衰、>1.0 = 低速域をより抑制
low-cut 1.8 低域カット閾値(0 = 無効)。微細な動きを抑制
discrete-scroll-factor 1.0 マウスホイール倍率(線形、カーブ無し)
chrome-scroll-factor 0.376 Chrome/Chromium フォーカス時の追加倍率

デフォルトパラメータでの出力値

入力デルタ 出力 Chrome (×0.376) 体感
2 0.20 0.07 繊細な指の動き(low-cut で抑制)
5 1.34 0.51 精密な位置合わせ
8 2.69 1.01 さっと指を滑らせる
10 3.62 1.36 軽い弾き
15 5.82 2.19 速い弾き
20 7.66 2.88 強い弾き
∞ 15.96 6.00 天井(base-speed × scroll-cap)

チューニングガイド

設定ファイルを保存して 3 秒待つだけで即座に反映されます。

sudo nano /etc/scroll-speed.conf
やりたいこと 調整するパラメータ
全速度域を均一に変更 base-speed
低速域のジッター抑制 low-cut(2.0-3.0 を試す)
加速感の増減 ramp-softness(1.0 = フラット、2.0+ = 強カーブ)
高速フリックの天井変更 scroll-cap
Chrome だけ調整 chrome-scroll-factor
Chrome 検出を無効化 chrome-scroll-factor=1.0
Chrome 維持で他を変更 base-speed ↑ + chrome-scroll-factor ↓(積を一定に)

例

全体を 20% 速く:

sudo sed -i 's/base-speed=.*/base-speed=0.91/' /etc/scroll-speed.conf

Chrome をさらに遅く:

sudo sed -i 's/chrome-scroll-factor=.*/chrome-scroll-factor=0.30/' /etc/scroll-speed.conf

Chrome は維持、他のアプリだけ速く:

# Chrome 実効速度 = base-speed × chrome-scroll-factor
# 現在: 0.76 × 0.376 = 0.286
# 積を維持: 0.90 × 0.318 = 0.286
sudo sed -i 's/base-speed=.*/base-speed=0.90/' /etc/scroll-speed.conf
sudo sed -i 's/chrome-scroll-factor=.*/chrome-scroll-factor=0.318/' /etc/scroll-speed.conf

他のノート PC 向け控えめな設定:

base-speed=0.5
scroll-cap=20.0
ramp-softness=1.0
low-cut=0
chrome-scroll-factor=1.0

安全性

  • アトミックインストール — .so は cp → .tmp → mv(inode スワップ)で配置。直接上書きすると mmap 中のプロセスが一斉クラッシュする(実証済み)
  • グレースフルデグラデーション — GNOME 以外のプロセスでは Mutter API が NULL に解決され、アプリ別検出は自動スキップ
  • 安全なフォールバック — libinput 関数が解決できない場合は 0.0 を返す
  • ホットリロードのみ — 設定変更は自動反映。.so バイナリの更新は再ログイン必要

デバッグ

環境変数を設定して初期化ログを有効化:

LIBSCROLL_SPEED_DEBUG=1 gnome-shell  # /tmp/scroll-speed-init.log に出力

互換性

要素 要件
ディスプレイサーバ Wayland(X11 非対応)
コンポジタ GNOME/Mutter(アプリ別検出に GNOME Shell API が必要)
libinput get_scroll_value API を持つ任意のバージョン
アーキテクチャ x86_64, aarch64(自動検出)

動作確認済みディストロ

ディストロ GNOME 状態
Ubuntu 25.04 (Plucky) 48 開発環境
Ubuntu 24.04 LTS (Noble) 46 互換
Fedora 40+ 46+ 互換

依存するのは安定したディストロ非依存のインターフェースのみ: libinput C API (libinput_event_pointer_get_scroll_value)、/etc/ld.so.preload (glibc)、Mutter/GNOME Shell API (shell_global_get, meta_display_get_focus_window, meta_window_get_pid)。これらは GNOME 44–48+ で変更がないため、GNOME/Wayland 環境であればどのディストロでも動作します。

非線形カーブ自体は libinput を使う任意の Wayland コンポジタ(Sway、wlroots 系等)で動作しますが、アプリ別 Chrome 検出は GNOME 固有です。GNOME 以外では chrome-scroll-factor は無視され、全アプリに同じカーブが適用されます。

ファイル構成

scroll-speed.c         ライブラリ本体(libinput フック + Mutter API + ホットリロード)
scroll-speed.conf      設定テンプレート(→ /etc/scroll-speed.conf)
test-interposer.c      テストハーネス(カーブ数学 + シンボルインターポジション)
Makefile               ビルド・インストール自動化
setup.sh               ワンコマンドセットアップ
uninstall.sh           アンインストールスクリプト

ライセンス

MIT — LICENSE を参照

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages