| # ElevenLabs TTS Setup Instructions | |
| ## Phase 2: Audio Hints Feature | |
| The chatbot can now generate partial audio hints using ElevenLabs text-to-speech! | |
| ### Features: | |
| - **Progressive Audio Hints**: First syllable → First half → Rhythm pattern → Almost full | |
| - **Strategic Timing**: Automatic at attempts 3, 5, 7, 10+ or when user asks | |
| - **Cost Effective**: ~$0.003 per hint, cached for reuse | |
| ### Setup Steps: | |
| 1. **Get ElevenLabs API Key** | |
| - Sign up at https://elevenlabs.io/ | |
| - Get your API key from the dashboard | |
| - Free tier: 10,000 characters/month (~3,000 audio hints) | |
| 2. **Install Dependencies** | |
| ```bash | |
| pip install elevenlabs==0.2.26 | |
| ``` | |
| 3. **Add API Key to .env** | |
| ```bash | |
| # Add this line to your .env file | |
| ELEVENLABS_API_KEY=your_api_key_here | |
| ``` | |
| 4. **Restart Application** | |
| ```bash | |
| # Kill and restart both backend and frontend | |
| ./restart.sh | |
| ``` | |
| ### Testing: | |
| 1. Start a game and make 3+ attempts | |
| 2. Open the chatbot (? button) | |
| 3. Ask: "Give me a hint" or "How does it sound?" | |
| 4. Chatbot will provide text hint + audio file | |
| ### Audio Hint Strategy: | |
| - **Attempt 3**: First syllable (e.g., "Win" from "Wingardium Leviosa") | |
| - **Attempt 5**: First half (e.g., "Wingardium") | |
| - **Attempt 7**: Rhythm pattern (e.g., "Win ... gar ... di ... um ... Le ... vi ... o ... sa") | |
| - **Attempt 10+**: Almost full (e.g., "Wingardium Leviosa" missing last syllable) | |
| ### Costs: | |
| - ElevenLabs pricing: $0.30 per 1,000 characters | |
| - Average hint: 10 characters = $0.003 per hint | |
| - 100 users/day with 2 hints each = $0.60/day = $18/month | |
| - Caching reduces API calls by 70-90% | |
| ### Status Check: | |
| Check if ElevenLabs is configured: | |
| ```python | |
| from client.utils.elevenlabs_tts import get_status | |
| print(get_status()) | |
| ``` | |
| ### Troubleshooting: | |
| **Audio hints not working?** | |
| 1. Check .env file has `ELEVENLABS_API_KEY` | |
| 2. Restart backend and frontend | |
| 3. Check logs for "ElevenLabs configured: True" | |
| 4. Verify API key is valid at elevenlabs.io | |
| **Cost too high?** | |
| - Audio hints are cached automatically | |
| - Adjust `should_offer_audio_hint()` logic in `elevenlabs_tts.py` | |
| - Reduce random chance after attempt 5 (currently 30%) | |
| ### Files Modified: | |
| - `client/utils/elevenlabs_tts.py` - New TTS integration module | |
| - `client/frontend/components/floating_chatbot.py` - Audio hint generation | |
| - `requirements.txt` - Added elevenlabs dependency | |