@domdhi/claude-code-tts 1.0.0

package/INSTALL.md

@@ -0,0 +1,335 @@
+# claude-code-tts — Installation Reference
+
+Full reference for install options, voice configuration, hooks wiring, and troubleshooting.
+
+---
+
+## Stack
+
+| Package | Role |
+|---------|------|
+| `edge-tts` | Primary TTS — Microsoft neural voices, free, cloud, ~0 RAM |
+| `miniaudio` | Decodes edge-tts MP3 output to PCM for playback |
+| `sounddevice` | Audio playback |
+| `cffi` | sounddevice's C backend (not auto-installed by pip) |
+| `kokoro-onnx` | Optional offline fallback — activates if edge-tts fails |
+| `onnxruntime` | ONNX runtime (auto-installed with kokoro-onnx) |
+
+**Engine priority:** edge-tts (primary) → kokoro-onnx (fallback, if installed)
+
+---
+
+## Install
+
+### Option A — installer script (recommended)
+
+```bash
+git clone https://github.com/domdhi/claude-code-tts
+cd claude-code-tts
+pip install edge-tts miniaudio sounddevice cffi
+python install.py
+```
+
+The installer:
+1. Checks Python version (3.10+ required)
+2. Installs required packages
+3. Copies hook files to `~/.claude/hooks/tts/`
+4. Creates the `on` file (TTS enabled immediately)
+5. Optionally installs kokoro-onnx offline fallback (~82MB)
+6. Prints the `settings.json` snippet to add
+
+### Option B — manual
+
+```bash
+# Install packages
+pip install edge-tts miniaudio sounddevice cffi
+
+# Create install dir
+mkdir -p ~/.claude/hooks/tts
+
+# Copy files
+cp daemon.py stop.py task-hook.py repeat.py voices.json ~/.claude/hooks/tts/
+
+# Enable TTS
+touch ~/.claude/hooks/tts/on
+```
+
+Then add the settings.json snippet below manually.
+
+---
+
+## Claude Code Settings
+
+Add to `~/.claude/settings.json`. If you already have a `"hooks"` key, merge these entries — don't replace the whole object.
+
+**Mac/Linux:**
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"$HOME/.claude/hooks/tts/stop.py\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"$HOME/.claude/hooks/tts/task-hook.py\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"$HOME/.claude/hooks/tts/repeat.py\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Windows** (replace `C:\Users\YourName` with your actual home path):
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\YourName\\.claude\\hooks\\tts\\stop.py\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\YourName\\.claude\\hooks\\tts\\task-hook.py\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python \"C:\\Users\\YourName\\.claude\\hooks\\tts\\repeat.py\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Offline Fallback (kokoro-onnx)
+
+kokoro-onnx is an optional local TTS engine. It activates automatically if edge-tts fails (no internet, rate limit, etc.).
+
+```bash
+pip install kokoro-onnx
+
+# Download model files (~82MB total)
+# Mac/Linux:
+mkdir -p ~/.claude/hooks/tts/models
+curl -L "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx" \
+     -o ~/.claude/hooks/tts/models/kokoro-v1.0.onnx
+curl -L "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin" \
+     -o ~/.claude/hooks/tts/models/voices-v1.0.bin
+
+# Windows (PowerShell):
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\hooks\tts\models"
+Invoke-WebRequest "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/kokoro-v1.0.onnx" `
+    -OutFile "$env:USERPROFILE\.claude\hooks\tts\models\kokoro-v1.0.onnx"
+Invoke-WebRequest "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0/voices-v1.0.bin" `
+    -OutFile "$env:USERPROFILE\.claude\hooks\tts\models\voices-v1.0.bin"
+```
+
+---
+
+## Voice Configuration
+
+Edit `~/.claude/hooks/tts/voices.json`.
+
+### Available voices
+
+| Key | Edge TTS voice | Style |
+|-----|----------------|-------|
+| `af_heart` | en-US-AriaNeural | warm, natural female (default) |
+| `af_bella` | en-US-MichelleNeural | polished female |
+| `af_sarah` | en-US-SaraNeural | professional female |
+| `af_sky` | en-US-JennyNeural | friendly, conversational |
+| `af_nova` | en-US-MonicaNeural | energetic female |
+| `am_michael` | en-US-GuyNeural | natural, authoritative male |
+| `am_adam` | en-US-DavisNeural | deep male |
+| `am_echo` | en-US-TonyNeural | casual male |
+| `am_eric` | en-US-EricNeural | confident male |
+| `am_liam` | en-US-RyanNeural | young, energetic male |
+| `am_onyx` | en-US-ChristopherNeural | deep, authoritative male |
+
+### Voice priority (highest → lowest)
+
+1. `[AgentName]:` prefix in response text → agent voice from `voices.json`
+2. Project key match → `voices.json` `"projects"` section
+3. `"default"` entry in `voices.json`
+
+### Per-agent voices (task-hook.py)
+
+`task-hook.py` reads `subagent_type` from the Task tool input and looks up the agent by name:
+
+```json
+{
+  "default": {"voice": "af_heart", "speed": 1.0},
+  "general-purpose": {"voice": "am_michael", "speed": 1.0},
+  "code-reviewer": {"voice": "am_onyx", "speed": 0.9}
+}
+```
+
+### Per-agent prefix (stop.py)
+
+Any agent that begins its response with `[AgentName]:` gets routed to that voice. Add to the agent's system prompt:
+```
+Always begin your response with [AgentName]:
+```
+Add to `voices.json`:
+```json
+{
+  "MyAgent": {"voice": "am_adam", "speed": 0.9}
+}
+```
+The hook strips `[AgentName]:` before speaking.
+
+### Per-project voices
+
+Add a `"projects"` section. Keys are matched as case-insensitive substrings of the encoded project path under `~/.claude/projects/`:
+
+```bash
+ls ~/.claude/projects/   # shows encoded dir names like c--Users-me-Repos-MyProject
+```
+
+```json
+{
+  "projects": {
+    "MyProject": {"voice": "am_onyx", "speed": 0.95},
+    "another-repo": {"voice": "af_sarah", "speed": 1.0}
+  }
+}
+```
+
+---
+
+## Enable / Disable
+
+TTS is gated on the presence of `~/.claude/hooks/tts/on`:
+
+```bash
+# Disable
+rm ~/.claude/hooks/tts/on
+
+# Re-enable
+touch ~/.claude/hooks/tts/on          # Mac/Linux
+echo. > %USERPROFILE%\.claude\hooks\tts\on  # Windows cmd
+```
+
+---
+
+## Commands
+
+Type in the Claude Code prompt:
+
+| Prompt | Effect |
+|--------|--------|
+| `/voice:stop` or `/stop` | Stop speech immediately, clear queue |
+| `/repeat` | Replay last spoken response |
+
+---
+
+## Daemon Protocol
+
+The daemon runs on `localhost:6254` and accepts JSON lines:
+
+| Command | Effect |
+|---------|--------|
+| `{"cmd": "speak", "text": "...", "voice": "af_heart", "speed": 1.0, "project": "repo"}` | Queue speech |
+| `{"cmd": "stop"}` | Stop immediately, clear queue |
+| `{"cmd": "ping"}` | Health check → `{"ok": true, "pid": N}` |
+| `{"cmd": "quit"}` | Shut down daemon |
+
+**Queue behavior:** at most one item per `project` key. New message from the same project replaces its queued slot. Messages from different projects line up. Omit `project` for single-project use.
+
+---
+
+## Performance Tuning
+
+The daemon runs at below-normal process priority and limits ONNX threads by default. To adjust:
+
+```python
+# Top of daemon.py, before any imports
+os.environ.setdefault('OMP_NUM_THREADS', '4')         # lower = less CPU spike
+os.environ.setdefault('ONNXRUNTIME_NUM_THREADS', '4') # higher = faster synthesis
+```
+
+After editing daemon.py, restart the daemon:
+```bash
+# Mac/Linux
+pkill -f daemon.py
+
+# Windows
+taskkill /F /IM python.exe  # kills all python processes
+```
+The daemon auto-restarts on the next response.
+
+---
+
+## Troubleshooting
+
+### No audio output
+- Check that the `on` file exists: `ls ~/.claude/hooks/tts/on`
+- Check that settings.json hooks are wired correctly
+- Check `~/.claude/hooks/tts/daemon.log` for errors
+
+### edge-tts fails silently
+- Requires internet access — check connectivity
+- If offline, install kokoro-onnx fallback (see above)
+- Check `~/.claude/hooks/tts/debug.log` for synthesis errors
+
+### kokoro-onnx not found at startup
+- This is expected if you skipped the offline fallback install
+- The daemon will log: `kokoro-onnx not installed — edge-tts only`
+- Install it if you need offline support: `pip install kokoro-onnx` + download models
+
+### cffi not found / sounddevice import error
+- Run: `pip install cffi`
+- sounddevice doesn't always pull in cffi automatically
+
+### Daemon keeps restarting / won't stay up
+- Check for port conflict: `lsof -i :6254` (Mac/Linux) or `netstat -ano | findstr 6254` (Windows)
+- Check `~/.claude/hooks/tts/daemon.log`
+
+### Audio cuts off mid-sentence (kokoro fallback)
+- kokoro-onnx has a 510-token (~1500 char) hard limit
+- The daemon chunks text at sentence boundaries automatically — if you're hitting this, check `debug.log` for `IndexError`
+
+### Windows: DETACHED_PROCESS causes silence
+- Do not add `DETACHED_PROCESS` to the subprocess flags — it breaks the Windows audio session
+- `CREATE_NO_WINDOW` only is correct (already set in the hook files)

package/README.md

@@ -0,0 +1,133 @@
+# claude-code-tts
+
+Neural TTS hook system for [Claude Code](https://claude.ai/code). Reads Claude's responses aloud as they finish.
+
+**Engines:** Edge TTS (Microsoft neural voices, free, requires internet) with automatic offline fallback to kokoro-onnx.
+**Platform:** Windows, macOS, Linux
+**Install:** one Python script, no build tools required
+
+---
+
+## Quick Start
+
+```bash
+npx @domdhi/claude-code-tts
+```
+
+That's it. The installer copies the hook files, enables TTS, optionally installs the offline fallback, and prints the `settings.json` snippet to add to Claude Code.
+
+**Requirements:** Node.js 16+ and Python 3.10+ must both be installed. The hooks run in Python — Node is only used for the install command.
+
+**Or install manually:**
+```bash
+git clone https://github.com/domdhi/claude-code-tts
+cd claude-code-tts
+pip install edge-tts miniaudio sounddevice cffi
+python install.py
+```
+
+---
+
+## What It Does
+
+Three Claude Code hooks work together:
+
+| Hook | File | When it fires |
+|------|------|---------------|
+| `Stop` | `stop.py` | After every Claude response — reads it aloud |
+| `PostToolUse:Task` | `task-hook.py` | After a subagent finishes — reads its output |
+| `UserPromptSubmit` | `repeat.py` | On `/repeat` or `/voice:stop` commands |
+
+A persistent daemon (`daemon.py`) keeps the TTS model loaded in the background. Hook files connect to it via TCP on `localhost:6254`, starting it automatically if needed.
+
+---
+
+## Voice Configuration
+
+Edit `~/.claude/hooks/tts/voices.json` to customize voices per agent or per project.
+
+**Available voices:**
+
+| Key | Edge TTS | Style |
+|-----|----------|-------|
+| `af_heart` | AriaNeural | warm female (default) |
+| `af_bella` | MichelleNeural | polished female |
+| `af_sarah` | SaraNeural | professional female |
+| `af_sky` | JennyNeural | friendly female |
+| `af_nova` | MonicaNeural | energetic female |
+| `am_michael` | GuyNeural | natural male |
+| `am_adam` | DavisNeural | deep male |
+| `am_echo` | TonyNeural | casual male |
+| `am_eric` | EricNeural | confident male |
+| `am_liam` | RyanNeural | energetic male |
+| `am_onyx` | ChristopherNeural | authoritative male |
+
+**Per-agent voices** (add to `voices.json`):
+```json
+{
+  "default": {"voice": "af_heart", "speed": 1.0},
+  "general-purpose": {"voice": "am_michael", "speed": 1.0}
+}
+```
+The `task-hook.py` reads `subagent_type` from the Task tool input to look up the agent's voice automatically.
+
+**Per-project voices** (add a `"projects"` section):
+```json
+{
+  "projects": {
+    "my-project": {"voice": "am_onyx", "speed": 0.95}
+  }
+}
+```
+Project keys are matched as case-insensitive substrings of the encoded project path under `~/.claude/projects/`.
+
+**Per-agent prefix** — any agent that begins its response with `[AgentName]:` gets routed to that voice:
+```json
+{
+  "MyAgent": {"voice": "am_adam", "speed": 0.9}
+}
+```
+
+See [INSTALL.md](INSTALL.md) for full configuration reference.
+
+---
+
+## Commands
+
+Type these in the Claude Code prompt:
+
+| Command | Effect |
+|---------|--------|
+| `/voice:stop` | Stop speech immediately |
+| `/repeat` | Replay last response |
+
+---
+
+## Enable / Disable
+
+TTS is controlled by the presence of an `on` file in the install directory:
+
+```bash
+# Disable
+rm ~/.claude/hooks/tts/on
+
+# Re-enable
+touch ~/.claude/hooks/tts/on          # Mac/Linux
+echo. > %USERPROFILE%\.claude\hooks\tts\on  # Windows
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Claude Code
+- Internet connection (for Edge TTS primary engine)
+- `edge-tts`, `miniaudio`, `sounddevice`, `cffi`
+- Optional: `kokoro-onnx` + model files (~82MB) for offline fallback
+
+---
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict'
+
+const { execFileSync } = require('child_process')
+const path = require('path')
+
+// Find Python — try python3 first on Mac/Linux, python first on Windows
+const candidates = process.platform === 'win32'
+  ? ['python', 'python3']
+  : ['python3', 'python']
+
+let python = null
+for (const candidate of candidates) {
+  try {
+    execFileSync(candidate, ['--version'], { stdio: 'ignore' })
+    python = candidate
+    break
+  } catch {
+    // not found, try next
+  }
+}
+
+if (!python) {
+  console.error('Error: Python 3.10+ is required but was not found.')
+  console.error('Install Python from https://python.org and try again.')
+  process.exit(1)
+}
+
+const script = path.join(__dirname, '..', 'install.py')
+const args = process.argv.slice(2)  // pass through --dir and any other flags
+
+try {
+  execFileSync(python, [script, ...args], { stdio: 'inherit' })
+} catch (e) {
+  process.exit(e.status ?? 1)
+}