68 lines
1.7 KiB
Markdown
68 lines
1.7 KiB
Markdown
# 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.
|
|
|