Initial V3 commit
This commit is contained in:
TutorialsGHG
218
README.md
Normal file
218
README.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user