Repository navigation
v0.1
HPR Idle Detection Extension
Important
- This release is linux only currently
A native C++ & Lua extension for HPR (Human Pattern Recorder) that monitors system idle status and automatically manages tracking lifecycle events.
Developed by: Plexescor
Support Matrix
| Platform / Desktop Environment | Support Status |
|---|---|
| Windows | ✅ Supported |
| Linux (GNOME) | ✅ Supported |
| Linux (KDE Plasma) | 🚧 In Progress |
| Linux (Hyprland) | ✅ Supported |
| Linux (niri) | ✅ Supported |
| Linux (Cinnamon) | 🚧 In Progress |
Structure
src/— Native C++ module source code.include/— C++ header files.external/— Embedded dependencies (sol2,lua).idle_detection.lua— Extension entry point script.
Installation & Deployment Note
Important
- Both
idle_detection.luaand the compiled dynamic library (HPR_Idle_Detection_Extension.dllon Windows orHPR_Idle_Detection_Extension.soon Linux) must reside in the exact same folder inside your extensions directory. - The filename of
HPR_Idle_Detection_Extension.dll/HPR_Idle_Detection_Extension.somust be kept exactly as named in the release without renaming.
Placement directories:
- Windows:
%APPDATA%\HPR\HPR_Config\extensions\ - Linux:
~/.config/HPR/HPR_Config/extensions/
Configuring Idle Time Threshold
Idle time is configured via idle_detection_config.csv in the extension directory alongside idle_detection.lua.
CSV File Format
HPR expects a simple key-value CSV format where the threshold value is specified in milliseconds:
idle-threshold,<time_in_milliseconds>Conversion Examples
- 1 Minute:
idle-threshold,60000 - 5 Minutes:
idle-threshold,300000 - 8 Minutes (Default):
idle-threshold,480000 - 10 Minutes:
idle-threshold,600000 - 15 Minutes:
idle-threshold,900000
Tip
If idle_detection_config.csv is missing on launch, the extension will automatically create it with the default 8-minute threshold (480000 ms).
How It Works
- Initialization: On startup,
idle_detection.luaresolves its absolute directory viaHPR.getExtensionAbsoluteDir(), then dynamically loadsHPR_Idle_Detection_Extension.dll(or.so) usingpackage.loadlib()to expose native system idle detection (getIdleStatus). - Config Management: Reads
idle_detection_config.csvforidle-threshold(defaulting to 8 minutes /480000ms if missing). - System Monitoring: On every tick (
onTick), it checks user idle time against the configured threshold. - Auto Pause & Resume:
- If idle time exceeds the threshold and the active window title is not ignored (e.g. YouTube), tracking pauses automatically via
HPR.stopTracking(). - When user activity resumes, tracking automatically starts again via
HPR.startTracking().
- If idle time exceeds the threshold and the active window title is not ignored (e.g. YouTube), tracking pauses automatically via
Idle Detection Backends
The native library selects the appropriate idle detection method at runtime based on the current platform and desktop environment:
| Platform | Backend | How it works |
|---|---|---|
| Windows | GetLastInputInfo (Win32 API) |
Queries the timestamp of the last input event directly from the OS |
| Linux — GNOME | org.gnome.Mutter.IdleMonitor (D-Bus) |
Calls the Mutter compositor's D-Bus GetIdletime method |
| Linux — other Wayland | ext-idle-notify-v1 (Wayland protocol) |
Subscribes to compositor idle/resumed events in a background thread; elapsed time since the idled event is the idle duration |
The Wayland backend works with any compositor that implements the standard ext-idle-notify-v1 protocol, including KDE/KWin, Hyprland, Sway, niri, and others.
Warning
X11 sessions are not supported. If you are running a desktop on X11 (e.g. KDE on X11, Openbox, i3 on X), the extension will load successfully but idle detection will always return "not idle" and tracking will never be paused automatically. Only Wayland sessions are supported on non-GNOME Linux desktops.