ELEVENLABS_SETUP.md

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

   pip install elevenlabs==0.2.26
   

3. Add API Key to .env

   # Add this line to your .env file
   ELEVENLABS_API_KEY=your_api_key_here
   

4. Restart Application

   # 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:

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