anvil-dev-framework 0.1.6

package/docs/hooks-tts.md

@@ -0,0 +1,368 @@
+# Hooks: Text-to-Speech (TTS) Configuration
+
+> Audio notifications for Claude Code session events.
+
+---
+
+## Overview
+
+Anvil hooks include TTS (text-to-speech) capabilities to announce when Claude needs your input or when tasks complete. This provides an audio cue so you can multitask while Claude works.
+
+**TTS Priority Order:**
+
+| Priority | Engine | Platform | Latency | Cost |
+|----------|--------|----------|---------|------|
+| 1 | MLX Audio (Kokoro) | Apple Silicon only | ~300ms | Free (local) |
+| 2 | ElevenLabs | All platforms | ~500ms | API costs |
+| 3 | OpenAI TTS | All platforms | ~400ms | API costs |
+| 4 | pyttsx3 | All platforms | ~50ms | Free (local) |
+| 5 | macOS `say` | macOS only | ~10ms | Free (system) |
+
+The system automatically selects the best available option based on your platform and configured API keys.
+
+---
+
+## MLX Audio (Kokoro) - Recommended for Mac
+
+MLX Audio with the Kokoro-82M model provides high-quality, natural-sounding speech at ~300ms latency, running entirely locally on Apple Silicon Macs.
+
+### Installation
+
+**1. Install espeak (required dependency):**
+
+```bash
+brew install espeak
+```
+
+**2. First run downloads the model:**
+
+The Kokoro-82M model (~330MB) downloads automatically on first use to `~/.cache/huggingface/`.
+
+**3. Dependencies are managed by uv:**
+
+The script uses inline dependencies with uv, so no manual pip install is needed.
+
+### How It Works
+
+The `mlx_audio_tts.py` script:
+1. Loads the Kokoro-82M model via MLX framework
+2. Generates audio using the `af_heart` voice at 1.1x speed
+3. Plays audio via macOS `afplay`
+4. Falls back to macOS `say` on any error
+
+### Configuration
+
+Located at: `project/hooks/utils/tts/mlx_audio_tts.py`
+
+```python
+# Default settings
+voice = "af_heart"  # American female, warm voice
+speed = 1.1         # Slightly faster than normal
+lang_code = "a"     # American English
+```
+
+**Available voices:**
+- `af_heart` - American female (default, warm)
+- `af_bella` - American female (clear)
+- `af_nicole` - American female (professional)
+- `am_adam` - American male
+- `am_michael` - American male
+- `bf_emma` - British female
+- `bm_george` - British male
+
+### Manual Testing
+
+```bash
+# Test MLX Audio directly
+uv run project/hooks/utils/tts/mlx_audio_tts.py "Test complete"
+
+# Test with different voice
+uv run project/hooks/utils/tts/mlx_audio_tts.py --voice am_adam "Hello world"
+
+# Test with different speed
+uv run project/hooks/utils/tts/mlx_audio_tts.py --speed 1.3 "Faster speech"
+```
+
+### Resource Usage
+
+- **Model size**: ~330MB download (cached)
+- **Memory**: ~4.4GB peak during generation
+- **Latency**: ~300ms for short phrases
+- **CPU/GPU**: Uses Metal acceleration on Apple Silicon
+
+---
+
+## ElevenLabs (API)
+
+High-quality cloud-based TTS with natural voices.
+
+### Setup
+
+1. Get API key from [ElevenLabs](https://elevenlabs.io)
+2. Set environment variable:
+
+```bash
+export ELEVENLABS_API_KEY="your_api_key_here"
+```
+
+### Configuration
+
+Located at: `project/hooks/utils/tts/elevenlabs_tts.py`
+
+---
+
+## OpenAI TTS (API)
+
+OpenAI's text-to-speech API.
+
+### Setup
+
+1. Get API key from [OpenAI](https://platform.openai.com)
+2. Set environment variable:
+
+```bash
+export OPENAI_API_KEY="your_api_key_here"
+```
+
+### Configuration
+
+Located at: `project/hooks/utils/tts/openai_tts.py`
+
+---
+
+## pyttsx3 (Fallback)
+
+Offline TTS using system voices. Works on all platforms but sounds robotic.
+
+### Setup
+
+No configuration needed. Installed automatically via uv dependencies.
+
+### Configuration
+
+Located at: `project/hooks/utils/tts/pyttsx3_tts.py`
+
+---
+
+## TTS Events
+
+TTS is triggered by multiple Claude Code hooks for different events:
+
+### Event Reference
+
+| Hook | Event | TTS Message | When |
+|------|-------|-------------|------|
+| `SessionStart` | Session begins | "Claude Code session started" | New session, resume, or clear |
+| `Stop` | Claude finishes | "Work complete!" (varies) | Claude stops responding |
+| `Notification` | Needs input | "Your agent needs your input" | Waiting for user |
+| `PostToolUse` | Plan complete | "Planning complete. Ready for your review." | After `ExitPlanMode` |
+| `PreToolUse` | Question asked | "I have a question for you." | Before `AskUserQuestion` |
+| `PostToolUse` | Tests run | "Tests passed." / "Tests failed." | After test commands |
+| `PostToolUse` | Build run | "Build complete." / "Build failed." | After build commands |
+| `PostToolUse` | Lint run | "Lint passed." / "Lint issues found." | After lint commands |
+| `PostToolUse` | Agent done | "Agent task finished." | After `Task` tool |
+
+### Enabling TTS Events
+
+TTS is controlled by flags in `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{
+      "hooks": [{
+        "command": "uv run .claude/hooks/session_start.py --announce"
+      }]
+    }],
+    "PreToolUse": [{
+      "hooks": [{
+        "command": "uv run .claude/hooks/pre_tool_use.py --announce"
+      }]
+    }],
+    "PostToolUse": [{
+      "hooks": [{
+        "command": "uv run .claude/hooks/post_tool_use.py --announce"
+      }]
+    }],
+    "Notification": [{
+      "hooks": [{
+        "command": "uv run .claude/hooks/notification.py --notify"
+      }]
+    }],
+    "Stop": [{
+      "hooks": [{
+        "command": "uv run .claude/hooks/stop.py --chat --cleanup-agent"
+      }]
+    }]
+  }
+}
+```
+
+**Note:** The `Stop` hook always announces completion (no flag needed).
+
+### Detected Commands
+
+The `PostToolUse` hook detects these command patterns:
+
+**Test commands:**
+- `npm test`, `npm run test`
+- `pytest`, `vitest`, `jest`
+- `cargo test`, `go test`
+
+**Build commands:**
+- `npm run build`, `npm build`
+- `cargo build`, `go build`
+- `make build`, `tsc`
+
+**Lint commands:**
+- `npm run lint`, `eslint`
+- `prettier`, `cargo clippy`
+
+### Relevant Files
+
+| File | Purpose |
+|------|---------|
+| `hooks/session_start.py` | Session start announcement |
+| `hooks/pre_tool_use.py` | Pre-tool announcements (AskUserQuestion) |
+| `hooks/post_tool_use.py` | Post-tool announcements (tests, builds, etc.) |
+| `hooks/stop.py` | Completion announcement |
+| `hooks/notification.py` | Input needed announcement |
+| `hooks/utils/tts/mlx_audio_tts.py` | MLX Audio engine |
+| `hooks/utils/tts/elevenlabs_tts.py` | ElevenLabs engine |
+| `hooks/utils/tts/openai_tts.py` | OpenAI engine |
+| `hooks/utils/tts/pyttsx3_tts.py` | pyttsx3 engine |
+
+### TTS Selection Logic
+
+All hooks use the same priority order:
+
+```python
+def get_tts_script_path():
+    # 1. MLX Audio for Apple Silicon (free, fast, local)
+    if is_apple_silicon():
+        if mlx_script.exists():
+            return mlx_script
+
+    # 2. ElevenLabs if API key set (highest quality)
+    if os.getenv('ELEVENLABS_API_KEY'):
+        return elevenlabs_script
+
+    # 3. OpenAI TTS if API key set
+    if os.getenv('OPENAI_API_KEY'):
+        return openai_script
+
+    # 4. pyttsx3 as offline fallback
+    return pyttsx3_script
+
+    # 5. If none available, use macOS `say`
+```
+
+---
+
+## Disabling TTS
+
+To disable TTS entirely, remove the `--notify` flag from the notification hook in `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "notification": [".claude/hooks/notification.py"]
+  }
+}
+```
+
+The `--notify` flag enables TTS:
+
+```json
+{
+  "hooks": {
+    "notification": [".claude/hooks/notification.py --notify"]
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### MLX Audio not working
+
+**Symptom**: Falls back to macOS `say`
+
+**Solutions:**
+1. Verify Apple Silicon: `uname -m` should show `arm64`
+2. Install espeak: `brew install espeak`
+3. Check Python version: Requires Python 3.11-3.13 (not 3.14+)
+4. Test directly: `uv run project/hooks/utils/tts/mlx_audio_tts.py "test"`
+
+### Model download failed
+
+**Symptom**: Network error during first run
+
+**Solutions:**
+1. Check internet connection
+2. Clear cache: `rm -rf ~/.cache/huggingface/hub/models--prince-canuma--Kokoro-82M`
+3. Try again
+
+### High memory usage
+
+**Symptom**: System slows during TTS
+
+**Solutions:**
+1. Expected: MLX Audio uses ~4.4GB during generation
+2. Close other memory-intensive apps
+3. Or use pyttsx3/macOS say (lower quality, lower memory)
+
+### No audio output
+
+**Symptom**: Script runs but no sound
+
+**Solutions:**
+1. Check system volume
+2. Verify audio device: `afplay /System/Library/Sounds/Ping.aiff`
+3. Check for audio routing issues (headphones, Bluetooth)
+
+---
+
+## Adding Custom TTS Engines
+
+To add a new TTS engine:
+
+1. Create `project/hooks/utils/tts/your_engine.py`:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["your-tts-library"]
+# ///
+
+import sys
+import subprocess
+
+def speak(text: str) -> bool:
+    try:
+        # Your TTS implementation
+        return True
+    except Exception:
+        subprocess.run(['say', text], capture_output=True)
+        return False
+
+def main():
+    text = sys.argv[1] if len(sys.argv) > 1 else "Task complete"
+    speak(text)
+
+if __name__ == "__main__":
+    main()
+```
+
+2. Update `notification.py` to include your engine in the priority chain.
+
+---
+
+## References
+
+- [MLX Audio GitHub](https://github.com/Blaizzy/mlx-audio)
+- [Kokoro Model](https://huggingface.co/prince-canuma/Kokoro-82M)
+- [ElevenLabs API](https://elevenlabs.io/docs)
+- [OpenAI TTS API](https://platform.openai.com/docs/guides/text-to-speech)