rename user-facing commands and crates to gsf

2026-03-24 12:10:31 +00:00
parent 6ef326188a
commit 3684b24c50
9 changed files with 966 additions and 0 deletions
@@ -0,0 +1,98 @@
+# gotta-scroll-fast
+
+Host-side **scroll acceleration** toolkit for Linux/Wayland.
+
+This project is a fork/reimplementation inspired by [maccel](https://github.com/Gnarus-G/maccel), but it is a **separate tool** focused on scroll acceleration.
+
+## credit and licensing
+
+- Original inspiration/source: https://github.com/Gnarus-G/maccel
+- Attribution details: `NOTICE.md`
+- License: **GPL-2.0-or-later** (`LICENSE`)
+
+## components
+
+- `gsf` - parameter CLI + TUI
+- `gsfd` - evdev -> uinput scroll acceleration daemon
+  - applies acceleration curves to wheel/hwheel (including hi-res wheel events)
+  - suppresses low-res wheel duplicates when hi-res events are present in the same frame
+
+## development
+
+```bash
+nix develop
+cargo build
+```
+
+## quick start (functional)
+
+1) List devices:
+
+```bash
+cargo run -p gsf-daemon -- --list-devices
+```
+
+2) Pick your trackball device and run dry-run first:
+
+```bash
+cargo run -p gsf-daemon -- --device /dev/input/eventX --dry-run
+```
+
+3) Tune parameters (separate terminal):
+
+```bash
+cargo run -p gsf-cli -- set mode natural
+cargo run -p gsf-cli -- set param sens-mult 1.0
+cargo run -p gsf-cli -- set param decay-rate 0.1
+cargo run -p gsf-cli -- set param limit 1.5
+```
+
+or launch TUI:
+
+```bash
+cargo run -p gsf-cli -- tui
+```
+
+4) Run live daemon:
+
+```bash
+cargo run -p gsf-daemon -- --device /dev/input/eventX
+```
+
+Tip: auto-pick by name substring:
+
+```bash
+cargo run -p gsf-daemon -- --match-name ploopy
+```
+
+## config + state paths
+
+Default config path:
+- `~/.config/gsf/config.json`
+- override with `GSF_CONFIG_PATH`
+
+Default speed stats path:
+- `$XDG_RUNTIME_DIR/gsf-speed.txt` (if available)
+- fallback `~/.local/state/gsf/speed.txt`
+- override with `GSF_STATS_PATH`
+
+## runtime requirements
+
+- Linux with evdev/uinput
+- `/dev/uinput` available
+- permissions to read source event device and write uinput
+
+For NixOS notes, see `DEV_SETUP.md`.
+
+## systemd user service
+
+A starting unit file exists at:
+
+- `packaging/systemd/user/gsfd.service`
+
+Copy to `~/.config/systemd/user/gsfd.service`, adjust device selection args, then:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now gsfd
+```