diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..fe59bfd --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# breaktimer + +Break reminder for Linux/Wayland. A small Bash daemon that nudges you to take +micro-pauses while working at the PC, with desktop notifications, sounds, and a +[Waybar](https://github.com/Alexays/Waybar) module showing a live countdown. + +Notifications and tooltips are in Italian. + +## How it works + +State machine: **working β micro-pause β working**, and every 4th block a +**long pause** instead. The countdown freezes when you pause manually and +outside your work-hours window, so breaks never eat into work time and the +Waybar number stays honest. + +| Phase | Default | Notification | +|-----------|---------|--------------------------| +| working | 30 min | β | +| breaking | 3 min | "πΆ Micro-pausa" | +| longbreak | 10 min | "βΈοΈ Pausa lunga" (every 4th) | + +## Dependencies + +- `dunst` (or any `notify-send` provider) +- `pipewire` β `pw-play`, falls back to `paplay` (PulseAudio) +- coreutils, Bash +- [Waybar](https://github.com/Alexays/Waybar) (optional, for the bar module) +- A Nerd Font for the Waybar glyphs (optional) + +## Install + +The Waybar config calls the scripts from `~/bin`. Put both there and make them +executable: + +```bash +mkdir -p ~/bin +cp breaktimer.sh waybar-breaktimer.sh ~/bin/ +chmod +x ~/bin/breaktimer.sh ~/bin/waybar-breaktimer.sh +``` + +Make sure `~/bin` is on your `PATH` (or call the scripts by full path). + +### Sounds + +Defaults use the [Modern Minimal UI](https://github.com/cadecomposer/modern-minimal-ui-sounds) sound set at: + +``` +~/.local/share/sounds/modern-minimal-ui-sounds/stereo/ +``` + +Three events map to `message-new-instant.oga` (micro), `alarm-clock-elapsed.oga` +(long), `service-login.oga` (back to work). Don't have that set? Either install +it there, or edit the `SOUND_DIR` / `SYS_SOUND_*` variables at the top of +`breaktimer.sh` to point at any `.oga`/`.wav` you like (e.g. the freedesktop +sounds in `/usr/share/sounds/freedesktop/stereo/`). A missing file is simply +silent β no error. + +## Usage + +```bash +breaktimer.sh start # start the daemon in the background +breaktimer.sh stop # stop it +breaktimer.sh restart # stop + start +breaktimer.sh pause # freeze the countdown +breaktimer.sh resume # unfreeze +breaktimer.sh toggle # pause/resume in one command +breaktimer.sh status # print state, phase, seconds remaining +``` + +(`breaktimer.sh run` is the internal loop β don't call it directly; it will +refuse if a daemon is already running.) + +Auto-start on login by adding `breaktimer.sh start` to your compositor's +autostart (e.g. Hyprland `exec-once`, Sway `exec`). + +## Configuration + +Edit the variables at the top of `breaktimer.sh`: + +| Variable | Meaning | +|-------------------------------|-------------------------------------------| +| `MICRO_MIN` / `BREAK_MIN` | work block / micro-pause length (minutes) | +| `LONG_MIN` / `LONG_EVERY` | long-pause length / every N-th block | +| `WORK_START` / `WORK_STOP` | work-hours window (`HH:MM`); outside it the work countdown freezes | +| `URGENCY_MICRO` / `URGENCY_LONG` | dunst urgency (`low`/`normal`/`critical`) | +| `SOUND_DIR`, `SOUND_*`, `SYS_SOUND_*` | sound files (see above) | + +## Waybar integration + +Three pieces: + +- **`waybar-breaktimer.sh`** β emits JSON (`{text, class, tooltip}`) that Waybar + renders. Reads the daemon's state files; no recalculation. +- **`waybar-breaktimer.config.jsonc`** β the `custom/breaktimer` module. +- **`breaktimer.css`** β phase colors (Catppuccin). + +### 1. Add the module + +Paste the inner block of `waybar-breaktimer.config.jsonc` into your +`~/.config/waybar/config` modules, then add `"custom/breaktimer"` to one of your +`modules-left/center/right` arrays: + +```jsonc +"custom/breaktimer": { + "exec": "~/bin/waybar-breaktimer.sh", + "return-type": "json", + "interval": 5, + "on-click": "~/bin/breaktimer.sh toggle", // left-click: pause/resume + "on-click-right": "~/bin/breaktimer.sh restart", // right-click: restart + "tooltip": true +} +``` + +### 2. Add the styling + +Append `breaktimer.css` to `~/.config/waybar/style.css`. It colors the module by +phase: + +| Class | Color | Meaning | +|-------------|--------|-------------------| +| `working` | green | working | +| `breaking` | blue | micro-pause | +| `longbreak` | purple | long pause | +| `paused` | yellow | manually paused | +| `stopped` | grey | daemon not running | + +### 3. Reload + +```bash +breaktimer.sh start +killall -SIGUSR2 waybar # reload Waybar +``` + +Left-click the module to pause/resume, right-click to restart. |