README.md

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