Initial commit

README.md

@@ -0,0 +1,68 @@
+# Stall Watcher
+
+Stall Watcher is a small passive Windows desktop app that monitors a selected screen region and sends a notification when that region stays visually still for a configured duration.
+
+It only uses local screenshots and image comparison. It does not click, type, inject code, read another process memory, or interact with the watched application.
+
+## Install
+
+Requires Python 3.12+.
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Configure ntfy
+
+Copy `.env.example` to `.env` and fill in your own values:
+
+```env
+NTFY_URL=https://your.ntfy.server
+NTFY_TOPIC=stall-watcher
+NTFY_TOKEN=your-token
+```
+
+The `.env` file is only for ntfy secrets. App preferences are stored separately with Qt settings.
+
+## Run
+
+From the repository root:
+
+```bash
+python -m src.main
+```
+
+## Use
+
+1. Select the monitor to watch.
+2. Click **Select region**.
+3. Drag a rectangle over the area to monitor. Press Escape to cancel.
+4. Adjust capture interval, alert delay, and movement threshold.
+5. Enable Windows and/or ntfy notifications.
+6. Click **Start monitoring**.
+
+The live motion score helps calibrate the threshold. For example, if motion is around `8.4` while moving and `0.7` while stopped, a threshold around `2.0` is a reasonable starting point.
+
+## Build a Windows exe
+
+Install PyInstaller in your virtualenv:
+
+```bash
+pip install pyinstaller
+pyinstaller --noconsole --name StallWatcher --paths . src/main.py
+```
+
+The executable will be created under `dist/`.
+
+## Development
+
+Run tests:
+
+```bash
+pytest
+```
+
+The detector tests cover motion scoring, still-time accumulation, reset on movement, one alert per still period, and rearming after movement resumes.
+