|
|
--- |
|
|
title: Twenty Questions Game |
|
|
emoji: 👋 |
|
|
colorFrom: red |
|
|
colorTo: blue |
|
|
sdk: static |
|
|
pinned: false |
|
|
short_description: Write your description here |
|
|
tags: |
|
|
- reachy_mini |
|
|
- reachy_mini_python_app |
|
|
--- |
|
|
|
|
|
# 🤖❓ 20 Questions - Reachy Mini App |
|
|
|
|
|
Play the classic guessing game with Reachy Mini! The robot thinks of something, and you have 20 yes/no questions to figure out what it is. |
|
|
|
|
|
**Powered by OpenAI Realtime API for natural voice conversation.** |
|
|
|
|
|
## ✨ Features |
|
|
|
|
|
- 🎤 **Voice Conversation** - Talk naturally, no buttons needed |
|
|
- 🎭 **Expressive Robot** - Watch Reachy react with emotions |
|
|
- 🧠 **Smart AI** - Natural conversation powered by OpenAI |
|
|
- 🔊 **Real-time Audio** - Low-latency speech-to-speech |
|
|
|
|
|
## 📋 Requirements |
|
|
|
|
|
- Reachy Mini robot (Lite or Wireless) |
|
|
- OpenAI API key with Realtime API access |
|
|
- Python 3.10+ |
|
|
|
|
|
## 🚀 Installation |
|
|
|
|
|
### Method 1: From Hugging Face (Recommended) |
|
|
|
|
|
1. Open the Reachy Mini dashboard: `http://localhost:8000` |
|
|
2. Find "20 Questions" in the app store |
|
|
3. Click **Install** |
|
|
|
|
|
### Method 2: Manual Installation |
|
|
|
|
|
```bash |
|
|
# Clone or download the app |
|
|
git clone https://huggingface.co/spaces/YOUR_USERNAME/reachy_mini_twenty_questions |
|
|
|
|
|
# Install in your Reachy Mini environment |
|
|
cd reachy_mini_twenty_questions |
|
|
pip install -e . |
|
|
``` |
|
|
|
|
|
## ⚙️ Configuration |
|
|
|
|
|
### Required: Set your OpenAI API Key |
|
|
|
|
|
```bash |
|
|
export OPENAI_API_KEY=your-openai-api-key |
|
|
``` |
|
|
|
|
|
Add this to your `~/.bashrc` or `~/.zshrc` to make it permanent. |
|
|
|
|
|
### Optional: Audio Sample Rates |
|
|
|
|
|
If transcription isn't working well, you may need to adjust the sample rates in `main.py`: |
|
|
|
|
|
```python |
|
|
# Common values based on your hardware |
|
|
REACHY_INPUT_SAMPLE_RATE = 16000 # Try: 16000, 44100, 48000 |
|
|
REACHY_OUTPUT_SAMPLE_RATE = 48000 # Try: 24000, 44100, 48000 |
|
|
``` |
|
|
|
|
|
To diagnose audio issues, check the logs when the app starts. |
|
|
|
|
|
## 🎮 How to Play |
|
|
|
|
|
1. **Start the app** from the Reachy Mini dashboard |
|
|
2. **Listen** to Reachy explain the rules |
|
|
3. **Ask yes/no questions** like: |
|
|
- "Is it alive?" |
|
|
- "Is it bigger than a car?" |
|
|
- "Can you eat it?" |
|
|
4. **Make your guess** when you think you know: "Is it a pizza?" |
|
|
5. **Say "play again"** to start a new game |
|
|
|
|
|
## 💡 Tips |
|
|
|
|
|
- Start with broad questions to narrow down categories |
|
|
- Listen to Reachy's tone - it gets nervous when you're close! |
|
|
- You can interrupt Reachy if you have an idea |
|
|
- The robot thinks of: animals, food, objects, and nature things |
|
|
|
|
|
## 🧪 Testing |
|
|
|
|
|
Before running the full app, you can test the OpenAI connection and audio utilities: |
|
|
|
|
|
```bash |
|
|
python test_openai_connection.py |
|
|
``` |
|
|
|
|
|
This script tests: |
|
|
- OpenAI API connection and authentication |
|
|
- Event receiving from OpenAI |
|
|
- Audio conversion utilities |
|
|
- Reachy Mini integration (if available) |
|
|
|
|
|
## 🔧 Troubleshooting |
|
|
|
|
|
### "OPENAI_API_KEY not set" |
|
|
|
|
|
Make sure you've exported your API key or added it to a `.env` file: |
|
|
```bash |
|
|
export OPENAI_API_KEY=sk-your-key-here |
|
|
``` |
|
|
|
|
|
Or create a `.env` file in the project root: |
|
|
``` |
|
|
OPENAI_API_KEY=sk-your-key-here |
|
|
``` |
|
|
|
|
|
### Transcription is garbled or wrong |
|
|
|
|
|
This usually means the audio sample rate doesn't match. Try: |
|
|
|
|
|
1. Check your Reachy Mini's audio hardware specs |
|
|
2. Update `REACHY_INPUT_SAMPLE_RATE` in `main.py` |
|
|
3. Common values: `16000`, `44100`, `48000` |
|
|
|
|
|
### Robot doesn't respond |
|
|
|
|
|
1. Check that the OpenAI API key is valid |
|
|
2. Ensure you have Realtime API access (may require specific tier) |
|
|
3. Check your internet connection |
|
|
|
|
|
### Audio is choppy |
|
|
|
|
|
1. Try adjusting `REACHY_OUTPUT_SAMPLE_RATE` |
|
|
2. Ensure your Reachy Mini isn't running other intensive apps |
|
|
|
|
|
## 🏗️ Architecture |
|
|
|
|
|
``` |
|
|
User Voice → Reachy Mic → Audio Conversion → OpenAI Realtime API |
|
|
↓ |
|
|
Robot Gestures ← Game State ← AI Response ← Voice Response |
|
|
``` |
|
|
|
|
|
- **Audio Utils**: Converts between Reachy (varies) and OpenAI (24kHz PCM16) |
|
|
- **Game State**: Tracks questions, manages phases, generates prompts |
|
|
- **OpenAI Handler**: WebSocket connection to Realtime API |
|
|
- **Robot Expressions**: Maps game emotions to antenna/head movements |
|
|
|
|
|
## 📁 Project Structure |
|
|
|
|
|
``` |
|
|
reachy_mini_twenty_questions/ |
|
|
├── pyproject.toml # Package definition |
|
|
├── index.html # HuggingFace Space landing page |
|
|
├── style.css # Landing page styles |
|
|
├── README.md # This file |
|
|
└── reachy_mini_twenty_questions/ |
|
|
├── __init__.py # Package exports |
|
|
├── main.py # ReachyMiniApp class |
|
|
├── audio_utils.py # Audio format conversion |
|
|
├── game_state.py # Game logic & prompts |
|
|
└── static/ |
|
|
└── index.html # Settings web UI |
|
|
``` |
|
|
|
|
|
## 🤝 Contributing |
|
|
|
|
|
Found a bug or have an idea? Open an issue or PR! |
|
|
|
|
|
## 📄 License |
|
|
|
|
|
Apache 2.0 |
|
|
|
|
|
## 🙏 Acknowledgments |
|
|
|
|
|
- [Pollen Robotics](https://pollen-robotics.com/) for Reachy Mini |
|
|
- [OpenAI](https://openai.com/) for the Realtime API |
|
|
- [Hugging Face](https://huggingface.co/) for hosting |
|
|
|
