219 lines
7.8 KiB
Markdown
219 lines
7.8 KiB
Markdown
# NotifyPulse — Multi-Profile Block Architecture
|
||
|
||
NotifyPulse is a Windows notification engine built around **Usecases** and **Blocks**.
|
||
Each usecase is an isolated profile with its own folder, enabled blocks, and notification list.
|
||
A tray app runs quietly in the background; a local web UI lets you manage everything.
|
||
|
||
---
|
||
|
||
## Folder structure
|
||
|
||
```
|
||
NotifyPulse/
|
||
├── notifier.py ← Main backend
|
||
├── requirements.txt
|
||
├── build.bat
|
||
├── ui/
|
||
│ └── index.html ← Desktop Web UI (usecase manager)
|
||
└── pwa/
|
||
├── index.html ← Mobile PWA (splash + selector + wallpaper)
|
||
├── manifest.json
|
||
└── sw.js
|
||
```
|
||
|
||
Config and assets live in `%APPDATA%\Roaming\NotifyPulse\`:
|
||
|
||
```
|
||
NotifyPulse\
|
||
├── usecases.json ← All usecase definitions
|
||
├── settings.json ← Global settings
|
||
│
|
||
├── icon.png ← Tray icon ──────────────────────────────────┐
|
||
│ Shown in the Windows system tray. │
|
||
│ Recommended: 256×256 px, PNG with │ App Icons
|
||
│ transparency. Falls back to a default │
|
||
│ coloured circle if missing. │
|
||
│ │
|
||
├── icon.ico ← Window / taskbar icon (optional) │
|
||
│ Used when the app is compiled to .exe. │
|
||
│ Recommended: multi-size ICO (16/32/48/256). │
|
||
│ If absent, icon.png is used instead. ┘
|
||
│
|
||
├── main.png ← PWA splash background ──────────────────────┐
|
||
│ Full-screen background shown on the phone │
|
||
│ PWA while it loads. Recommended: your │ PWA Assets
|
||
│ phone's native resolution (e.g. 1170×2532 │
|
||
│ for iPhone 14). JPEG is also accepted. ┘
|
||
│
|
||
└── usecases\
|
||
├── my_profile_abc123\
|
||
│ ├── wallpapers\ ← Desktop wallpapers for this usecase
|
||
│ ├── overlay\ ← Overlay images for this usecase
|
||
│ └── mobile\ ← Mobile wallpapers for this usecase (pushed via PWA)
|
||
└── ...
|
||
```
|
||
|
||
### Placing app icons
|
||
|
||
| File | Where it shows | Recommended size | Notes |
|
||
|------|----------------|-----------------|-------|
|
||
| `icon.png` | Windows system tray | 256 × 256 px | PNG, transparent background |
|
||
| `icon.ico` | Taskbar / .exe (compiled) | Multi-size ICO | 16, 32, 48, 256 px layers |
|
||
| `main.png` | PWA splash screen | Phone native res | JPEG also accepted |
|
||
|
||
Drop these files into `%APPDATA%\Roaming\NotifyPulse\` and restart the app.
|
||
No config change needed — the app picks them up automatically.
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
```bat
|
||
pip install -r requirements.txt
|
||
python notifier.py
|
||
```
|
||
|
||
Or build an `.exe` (bundles everything, no Python required to run):
|
||
|
||
```bat
|
||
build.bat
|
||
```
|
||
|
||
---
|
||
|
||
## Blocks
|
||
|
||
Each usecase can enable any combination of blocks:
|
||
|
||
| Block | What it does |
|
||
|---|---|
|
||
| 🔔 Notifications | Random & scheduled Windows toast notifications |
|
||
| 🖼️ Wallpaper | Changes desktop wallpaper from usecase's `wallpapers\` folder |
|
||
| ✨ Overlay | Fullscreen image overlay from usecase's `overlay\` folder |
|
||
| ⏱️ Timer | Enables time-triggered entries (HH:MM syntax) |
|
||
| 📱 Mobile Wallpaper | Pushes wallpapers to phone via PWA from usecase's `mobile\` folder |
|
||
|
||
---
|
||
|
||
## Creating a Usecase
|
||
|
||
**Desktop UI** → Usecases → `+ New Usecase`
|
||
|
||
1. Give it a name and accent color
|
||
2. Check the blocks you need
|
||
3. Set the min/max notification interval (in minutes)
|
||
4. Add notification entries (supports `| %` weights and `| HH:MM` schedules)
|
||
5. Click **▶ Activate** to start using it
|
||
6. Click **📁 Folder** to open the usecase folder and drop in your images
|
||
|
||
---
|
||
|
||
## notifications.txt syntax (per usecase)
|
||
|
||
```
|
||
# Weighted random
|
||
Take a break! | 35%
|
||
Drink water! | 30%
|
||
change.wallpaper | 20%
|
||
show.overlay | 15%
|
||
show.overlay.10 | 10% ← overlay for 10 seconds
|
||
change.wallpaper.mobile ← push to phone PWA
|
||
|
||
# Scheduled (needs Timer block)
|
||
Morning standup | 09:00
|
||
End of day | 17:30
|
||
```
|
||
|
||
---
|
||
|
||
## Settings reference
|
||
|
||
All settings are saved to `%APPDATA%\Roaming\NotifyPulse\settings.json`
|
||
and editable in the desktop UI under the **Settings** tab.
|
||
|
||
### General
|
||
|
||
| Setting | Default | Description |
|
||
|---|---|---|
|
||
| `app_name` | `"NotifyPulse"` | Name shown in the header before any usecase is selected |
|
||
| `hotkey` | `"F13"` | Global hotkey to pause / resume |
|
||
| `log_max_entries` | `100` | How many log lines to keep in memory |
|
||
| `startup_toast` | `true` | Show a toast notification when the app starts |
|
||
| `notify_sound` | `true` | Play sound with toast notifications |
|
||
| `auto_open_browser` | `true` | Open the web UI automatically on start |
|
||
| `minimize_to_tray` | `true` | Closing the window hides to tray instead of quitting |
|
||
| `run_on_startup` | `false` | Register NotifyPulse in Windows startup |
|
||
| `confirm_delete` | `true` | Show a confirmation dialog before deleting a usecase |
|
||
| `entry_display_mode` | `"percent"` | Default display for entry weights: `percent` or `chance` |
|
||
|
||
### Notifications
|
||
|
||
| Setting | Default | Description |
|
||
|---|---|---|
|
||
| `notification_duration` | `5` | How many seconds a toast stays on screen (1–30) |
|
||
|
||
### Overlay
|
||
|
||
| Setting | Default | Description |
|
||
|---|---|---|
|
||
| `overlay_duration` | `6` | Default overlay display time in seconds |
|
||
| `overlay_opacity` | `0.4` | Overlay transparency (0.05 – 1.0) |
|
||
| `overlay_stretch` | `false` | Stretch to fill (`true`) or letterbox-fit (`false`) |
|
||
| `overlay_monitor` | `0` | Which monitor: `0` = primary, `-1` = all, `1/2/3` = specific |
|
||
|
||
### Wallpaper
|
||
|
||
| Setting | Default | Description |
|
||
|---|---|---|
|
||
| `wallpaper_fit` | `"fill"` | How the image is scaled: `fill` · `fit` · `stretch` · `center` · `tile` |
|
||
|
||
### Network / PWA
|
||
|
||
| Setting | Default | Description |
|
||
|---|---|---|
|
||
| `web_port` | `5000` | Port for the web UI and PWA |
|
||
|
||
---
|
||
|
||
## PWA Splash Screen
|
||
|
||
Drop a `main.png` (or `.jpg`) into `%APPDATA%\NotifyPulse\` to use it as the
|
||
full-screen background when the PWA first loads on your phone.
|
||
|
||
---
|
||
|
||
## PWA Usage
|
||
|
||
1. Start NotifyPulse on your PC
|
||
2. On your phone, open: `http://<your-pc-ip>:5000/pwa`
|
||
3. **iOS**: Share → Add to Home Screen
|
||
4. **Android**: ⋮ → Install App
|
||
|
||
The PWA shows your splash screen, then a list of usecases to switch between.
|
||
Selecting one activates that usecase and shows the wallpaper receiver
|
||
if the Mobile Wallpaper block is enabled.
|
||
|
||
---
|
||
|
||
## API Reference
|
||
|
||
| Method | Endpoint | Description |
|
||
|---|---|---|
|
||
| GET | `/api/usecases` | List all usecases + blocks |
|
||
| POST | `/api/usecases` | Create a usecase |
|
||
| PUT | `/api/usecases/:id` | Update a usecase |
|
||
| DELETE | `/api/usecases/:id` | Delete a usecase |
|
||
| POST | `/api/usecases/:id/activate` | Switch active usecase |
|
||
| POST | `/api/usecases/:id/open_folder` | Open usecase folder in Explorer |
|
||
| GET | `/api/state` | Full app state |
|
||
| POST | `/api/pause` | Toggle pause |
|
||
| POST | `/api/fire_now` | Fire a random entry immediately |
|
||
| GET/POST | `/api/settings` | Read / update global settings |
|
||
| GET | `/api/log` | Event log |
|
||
| POST | `/api/pwa/ping` | PWA heartbeat |
|
||
| GET | `/api/pwa/app_name` | App info + usecase list for PWA |
|
||
| GET | `/api/pwa/splash_image` | Serve main.png as base64 |
|
||
| GET | `/api/pwa/wallpaper` | Poll for pending mobile wallpaper |
|
||
| POST | `/api/pwa/trigger_wallpaper` | Request a new wallpaper push |
|
||
| POST | `/api/pwa/activate_usecase` | Activate a usecase from the PWA |
|