docs: add README for talk and crunch packages

Each README covers usage, environment variables, integration patterns, NixOS installation, and how-it-works diagrams.
2026-07-02 20:00:58 +02:00
parent 9e96e92cfe
commit 75b88553c6
2 changed files with 217 additions and 0 deletions
@@ -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)