agentvibes 2.14.13 → 2.14.14

package/docs/macos-piper-issue.md

@@ -0,0 +1,172 @@
+# macOS Piper TTS Installation Issue
+
+## Problem
+
+User `BMadCode` on macOS reported installation failure when trying to use Piper TTS:
+
+### Error 1: Installer blocks macOS
+```bash
+➜ .claude/hooks/piper-installer.sh
+🎤 Piper TTS Installer
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ Piper TTS is only supported on WSL and Linux
+   Your platform: Darwin
+
+   For macOS/Windows, use ElevenLabs instead:
+   /agent-vibes:provider switch elevenlabs
+```
+
+### Error 2: Direct pipx installation fails
+```bash
+➜ pipx install piper-tts
+
+Fatal error from pip prevented installation. Full pip output in file:
+    /Users/brianmadison/.local/pipx/logs/cmd_2025-11-15_09.14.02_pip_errors.log
+
+pip seemed to fail to build package:
+    piper-tts
+
+Some possibly relevant errors from pip install:
+    ERROR: Cannot install piper-tts==1.1.0, piper-tts==1.2.0 and piper-tts==1.3.0 because these package versions have conflicting dependencies.
+    ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts
+```
+
+## Root Cause Analysis
+
+### Documentation Inconsistency
+**File: `docs/providers.md`** (lines 32 and 90) claims:
+- "Cross-platform support (Windows, macOS, Linux)"
+- Platform Support: "Windows, macOS, Linux, WSL"
+
+**File: `.claude/hooks/piper-installer.sh`** (lines 50-56) explicitly blocks macOS:
+```bash
+# Check if running on WSL or Linux
+if ! grep -qi microsoft /proc/version 2>/dev/null && [[ "$(uname -s)" != "Linux" ]]; then
+  echo "❌ Piper TTS is only supported on WSL and Linux"
+  echo "   Your platform: $(uname -s)"
+  exit 1
+fi
+```
+
+### Why Piper Installation Fails on macOS
+
+1. **piper-tts PyPI package has dependency conflicts** - The `piper-tts` package on PyPI (versions 1.1.0-1.3.0) has unresolved dependency conflicts that prevent installation on macOS
+
+2. **Installer intentionally blocks macOS** - The script checks for Linux/WSL and rejects Darwin (macOS)
+
+3. **README says bash 5.x required** - README.md (lines 140-146) states macOS users need to install bash 5.x via Homebrew, but this is for AgentVibes hooks, not Piper itself
+
+## Solutions
+
+### Recommended Solution: Use ElevenLabs on macOS
+The installer's guidance is correct - macOS users should use **ElevenLabs** instead of Piper TTS:
+
+```bash
+# Switch to ElevenLabs provider
+/agent-vibes:provider switch elevenlabs
+
+# Set your API key
+export ELEVENLABS_API_KEY="your_key_here"
+```
+
+**Why?**
+- ✅ Works perfectly on macOS
+- ✅ No dependency conflicts
+- ✅ 150+ professional voices
+- ✅ Free tier: 10,000 chars/month
+- ✅ Get API key at https://elevenlabs.io
+
+### Alternative: Piper Binary (If Available)
+If Piper precompiled binaries for macOS exist, users could:
+1. Download macOS Piper binary
+2. Install manually to PATH
+3. Skip the Python/pipx installation
+
+**Note:** This requires Piper project to provide macOS binaries.
+
+## Proposed Fixes
+
+### Fix 1: Update Documentation (Priority: HIGH)
+Update `docs/providers.md` to reflect accurate platform support:
+
+**Current (incorrect):**
+```markdown
+| **Platform Support** | All platforms | Windows, macOS, Linux, WSL |
+```
+
+**Should be:**
+```markdown
+| **Platform Support** | All platforms | Windows, Linux, WSL |
+```
+
+**And add note:**
+```markdown
+**Note:** Piper TTS is not currently supported on macOS due to Python dependency conflicts.
+macOS users should use ElevenLabs instead.
+```
+
+### Fix 2: Update Troubleshooting Guide (Priority: MEDIUM)
+Add to `docs/troubleshooting.md`:
+
+```markdown
+## Piper TTS Installation Fails on macOS
+
+**Symptom:** `pipx install piper-tts` fails with dependency conflicts
+
+**Solution:** macOS is not currently supported for Piper TTS. Use ElevenLabs instead:
+
+1. Switch provider: `/agent-vibes:provider switch elevenlabs`
+2. Get API key: https://elevenlabs.io (free tier available)
+3. Set key: `export ELEVENLABS_API_KEY="your_key"`
+4. Test: `/agent-vibes:sample Aria`
+```
+
+### Fix 3: Improve Installer Error Message (Priority: LOW)
+Update `.claude/hooks/piper-installer.sh` error message to be more helpful:
+
+**Current:**
+```bash
+echo "❌ Piper TTS is only supported on WSL and Linux"
+echo "   Your platform: $(uname -s)"
+echo ""
+echo "   For macOS/Windows, use ElevenLabs instead:"
+echo "   /agent-vibes:provider switch elevenlabs"
+```
+
+**Improved:**
+```bash
+echo "❌ Piper TTS is not supported on macOS"
+echo "   Your platform: $(uname -s)"
+echo ""
+echo "   🎤 Recommended: Use ElevenLabs (150+ voices, free tier available)"
+echo "   1. Get API key: https://elevenlabs.io"
+echo "   2. Set key: export ELEVENLABS_API_KEY=\"your_key\""
+echo "   3. Switch provider: /agent-vibes:provider switch elevenlabs"
+echo ""
+echo "   Free tier: 10,000 chars/month"
+```
+
+## Testing Checklist
+
+- [ ] Update `docs/providers.md` platform support table
+- [ ] Add macOS note to Piper TTS section in `docs/providers.md`
+- [ ] Add macOS troubleshooting entry to `docs/troubleshooting.md`
+- [ ] Improve error message in `.claude/hooks/piper-installer.sh`
+- [ ] Verify ElevenLabs works correctly on macOS
+- [ ] Update README.md if needed
+- [ ] Test installer on macOS to confirm helpful error messages
+
+## References
+
+- User report: BMadCode via Discord/Slack (2025-11-15)
+- Piper TTS GitHub: https://github.com/rhasspy/piper
+- ElevenLabs: https://elevenlabs.io
+- Related: README.md bash 5.x requirement (lines 140-146)
+
+## Labels
+- `bug` - Documentation bug
+- `macos` - Platform-specific issue
+- `piper-tts` - Provider-specific
+- `documentation` - Needs doc updates
+- `good first issue` - Clear, well-defined fix