Merge pull request 'docs: add README for talk and crunch packages' (#23) from docs/talk-crunch-readmes into master
Reviewed-on: #23
This commit was merged in pull request #23.
This commit is contained in:
@@ -0,0 +1,130 @@
|
||||
# crunch
|
||||
|
||||
Voice-notified reminders and AI crunch jobs via systemd transient timers. Schedules tasks that fire through `talk` (ElevenLabs TTS) — no NixOS rebuild needed, survives reboots.
|
||||
|
||||
## Usage
|
||||
|
||||
### Simple voice reminders
|
||||
|
||||
```bash
|
||||
crunch at "14:30" "Müll rausbringen"
|
||||
crunch at "2026-07-03 10:00" "Zahnarzttermin"
|
||||
crunch in "30m" "Build checken"
|
||||
crunch daily "09:00" "Daily standup"
|
||||
crunch weekly "Mon 09:00" "Weekly review"
|
||||
crunch weekly "Montag 09:00" "Weekly review" # German day names
|
||||
```
|
||||
|
||||
### AI crunch jobs
|
||||
|
||||
Runs a prompt through `pi` or `opencode` in print mode, pipes result to `talk`:
|
||||
|
||||
```bash
|
||||
crunch ai pi in "1h" "Fasse die neuesten Commits zusammen"
|
||||
crunch ai opencode daily "08:00" "Review offene Issues und gib 3 Key-Points"
|
||||
crunch ai pi weekly "Mon 09:00" "Generiere Weekly Summary aus git log"
|
||||
```
|
||||
|
||||
### Custom script jobs
|
||||
|
||||
Runs any shell script on schedule. Script stdout → `talk`:
|
||||
|
||||
```bash
|
||||
crunch script daily "08:00" ~/scripts/basecamp-daily.sh
|
||||
crunch script in "2h" ~/scripts/deploy-check.sh -- --verbose
|
||||
crunch script weekly "Mon 09:00" ~/scripts/weekly-report.sh
|
||||
```
|
||||
|
||||
Example script:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# ~/scripts/basecamp-daily.sh
|
||||
TODOS=$(basecamp todos --today 2>/dev/null) || exit 0
|
||||
echo "$TODOS" | pi -p "Erstelle Summary als ~/reports/daily.md. Antworte mit Top 3."
|
||||
```
|
||||
|
||||
### Management
|
||||
|
||||
```bash
|
||||
crunch list # List active jobs
|
||||
crunch cancel crunch-mll-rausbringen-12345 # Cancel a job
|
||||
crunch purge # Remove fired one-shot jobs
|
||||
```
|
||||
|
||||
## Command Reference
|
||||
|
||||
```
|
||||
crunch at <time> <message> One-shot (14:30 or "2026-07-03 14:30")
|
||||
crunch in <duration> <message> One-shot after delay (30m, 2h, 1h30m)
|
||||
crunch daily <time> <message> Recurring daily
|
||||
crunch weekly <day> <time> <message> Recurring weekly (Mon/Montag)
|
||||
crunch ai <engine> <type> <time> <prompt> AI crunch (pi|opencode)
|
||||
crunch script <type> <time> <script.sh> [args] Custom script → talk
|
||||
crunch list List active jobs
|
||||
crunch cancel <name> Cancel a job
|
||||
crunch purge Remove fired one-shot jobs
|
||||
```
|
||||
|
||||
## Day Names
|
||||
|
||||
Supports English and German:
|
||||
|
||||
| English | German | systemd |
|
||||
|---|---|---|
|
||||
| Mon, Monday | Mo, Montag | Mon |
|
||||
| Tue, Tuesday | Di, Dienstag | Tue |
|
||||
| Wed, Wednesday | Mi, Mittwoch | Wed |
|
||||
| Thu, Thursday | Do, Donnerstag | Thu |
|
||||
| Fri, Friday | Fr, Freitag | Fri |
|
||||
| Sat, Saturday | Sa, Samstag | Sat |
|
||||
| Sun, Sunday | So, Sonntag | Sun |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `ELEVENLABS_API_KEY` | ✅ | — | Required by `talk` |
|
||||
| `VOICE_NOTIFY` | ❌ | `1` | `0` silences talk globally |
|
||||
| `TALK` | ❌ | `talk` | Override path to talk binary |
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ systemd --user transient timer fires │
|
||||
│ │
|
||||
│ crunch _say "message" │
|
||||
│ └─ talk "message" (TTS via ElevenLabs) │
|
||||
│ │
|
||||
│ crunch _ai pi "prompt" │
|
||||
│ └─ pi -p "prompt" | talk (AI → TTS) │
|
||||
│ │
|
||||
│ crunch _script ~/script.sh │
|
||||
│ └─ bash ~/script.sh | talk (pipe → TTS)│
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Uses `systemd-run --user` to create transient `.timer` + `.service` units. No NixOS rebuild needed — jobs are created and managed at runtime.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `talk` package installed and in PATH
|
||||
- `pi` and/or `opencode` for AI crunch mode
|
||||
- `loginctl enable-linger <username>` — **critical** for timers to fire when logged out
|
||||
- `ELEVENLABS_API_KEY` in environment (or agenix secrets)
|
||||
|
||||
## NixOS Installation
|
||||
|
||||
```nix
|
||||
# home-manager
|
||||
home.packages = [ pkgs.m3ta.crunch pkgs.m3ta.talk ];
|
||||
```
|
||||
|
||||
Verify lingering is enabled:
|
||||
|
||||
```bash
|
||||
loginctl show-user $(whoami) | grep Linger=yes
|
||||
# If not:
|
||||
sudo loginctl enable-linger $(whoami)
|
||||
```
|
||||
@@ -0,0 +1,87 @@
|
||||
# talk
|
||||
|
||||
ElevenLabs TTS voice notifications with a dismissable desktop popup. Generates speech from text via the ElevenLabs API, plays it through `mpv`, and shows a notification with a **⛔ Abbrechen** button to stop playback.
|
||||
|
||||
## Usage
|
||||
|
||||
### Argument
|
||||
|
||||
```bash
|
||||
talk "Build abgeschlossen. Alle Tests erfolgreich."
|
||||
```
|
||||
|
||||
### Stdin (pipe)
|
||||
|
||||
```bash
|
||||
echo "Deployment fertig" | talk
|
||||
nixos-rebuild build 2>&1 | tail -3 | talk
|
||||
pi -p "Fasse zusammen" | talk
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Required | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `ELEVENLABS_API_KEY` | ✅ | — | API key for ElevenLabs |
|
||||
| `ELEVENLABS_VOICE_ID` | ❌ | `KXxZd16DiBqt82nbarJx` | Voice ID to use |
|
||||
| `VOICE_NOTIFY` | ❌ | `1` | Set to `0` to silence all output |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Sends text to ElevenLabs `text-to-speech` API → receives MP3
|
||||
2. Plays audio via `mpv` (background)
|
||||
3. Shows `notify-send` popup with **⛔ Abbrechen** action (background)
|
||||
4. Polls every 0.2s:
|
||||
- If mpv finished → kill notification, exit
|
||||
- If user clicked **Abbrechen** → kill mpv, exit
|
||||
5. Cleans up temp files on exit
|
||||
|
||||
## Cancel Button
|
||||
|
||||
The notification popup has a **⛔ Abbrechen** action button. Clicking it kills `mpv` playback immediately. The popup disappears when audio finishes or is cancelled.
|
||||
|
||||
The poll loop uses `[ -s ]` (non-empty file check) on the action output file. This ensures the loop only reacts when `notify-send` actually writes the action key — not when the empty file is created by the shell redirect.
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### After long-running tasks
|
||||
|
||||
```bash
|
||||
nixos-rebuild switch 2>&1 | tail -5 | talk
|
||||
```
|
||||
|
||||
### With AI agents (print mode)
|
||||
|
||||
```bash
|
||||
# Pi
|
||||
pi -p "Review diesen Code" | talk
|
||||
|
||||
# OpenCode
|
||||
opencode run "Erkläre diese Funktion" -q | talk
|
||||
```
|
||||
|
||||
### With crunch (scheduled jobs)
|
||||
|
||||
```bash
|
||||
crunch ai pi daily "08:00" "Fasse Basecamp Todos zusammen"
|
||||
# → talk speaks the summary at 08:00
|
||||
```
|
||||
|
||||
## NixOS Installation
|
||||
|
||||
```nix
|
||||
# home-manager
|
||||
home.packages = [ pkgs.m3ta.talk ];
|
||||
|
||||
# Requires in environment:
|
||||
environment.sessionVariables.ELEVENLABS_API_KEY = "your-key";
|
||||
# Or via agenix secrets
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `curl` — API calls
|
||||
- `python3` — JSON payload construction
|
||||
- `mpv` — audio playback
|
||||
- `libnotify` — desktop notification
|
||||
- `busybox` — coreutils (rm, cat, grep, sleep, kill, stat)
|
||||
Reference in New Issue
Block a user