README.md

metadata

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

# 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

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:

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

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:

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 for Reachy Mini
• OpenAI for the Realtime API
• Hugging Face for hosting