Skip to content
This repository was archived by the owner on Oct 26, 2026. It is now read-only.

v0.1

Choose a tag to compare

@plexescor plexescor released this 08 Aug 11:32
· 10 commits to main since this release

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.lua and the compiled dynamic library (HPR_Idle_Detection_Extension.dll on Windows or HPR_Idle_Detection_Extension.so on Linux) must reside in the exact same folder inside your extensions directory.
  • The filename of HPR_Idle_Detection_Extension.dll / HPR_Idle_Detection_Extension.so must 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

  1. Initialization: On startup, idle_detection.lua resolves its absolute directory via HPR.getExtensionAbsoluteDir(), then dynamically loads HPR_Idle_Detection_Extension.dll (or .so) using package.loadlib() to expose native system idle detection (getIdleStatus).
  2. Config Management: Reads idle_detection_config.csv for idle-threshold (defaulting to 8 minutes / 480000 ms if missing).
  3. System Monitoring: On every tick (onTick), it checks user idle time against the configured threshold.
  4. 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().

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.