README.md

metadata

title: Reachy Mini F1 Commentator
emoji: 🏎️
colorFrom: red
colorTo: blue
sdk: static
pinned: false
short_description: An interactive F1 race commentary system for Reachy Mini
tags:
  - reachy_mini
  - reachy_mini_python_app

🏎️ Reachy F1 Commentator

An interactive F1 race commentary system for Reachy Mini that generates organic, context-rich commentary with audio synthesis and synchronized robot movements.

Features

• 🎙️ Enhanced Organic Commentary - 210 templates with varied perspectives (technical, strategic, dramatic)
• 🏁 Quick Demo Mode - 2-3 minute pre-configured demonstration
• 📊 Full Historical Race Mode - Replay any F1 race from OpenF1 API
• 🔊 Audio Synthesis - ElevenLabs text-to-speech integration
• 🤖 Robot Movements - Synchronized head movements with commentary
• 🌐 Web UI - Browser-based race selection and playback control
• ⚡ Configurable Speed - 1x, 5x, 10x, or 20x playback speed

Installation

Via Reachy Mini App Assistant

The easiest way to install this app on your Reachy Mini:

reachy-mini-app-assistant install reachy-f1-commentator

Manual Installation

pip install git+https://huggingface.co/spaces/YOUR_USERNAME/reachy-f1-commentator

Usage

Starting the App

The app runs automatically when started from the Reachy Mini dashboard. It will:

1. Start a web server at http://localhost:5173 (or configured port)
2. Open the web UI for race selection
3. Wait for you to configure and start commentary

Web UI Controls

Mode Selection:

• Quick Demo - 2-3 minute demonstration with pre-configured events
• Full Historical Race - Select from available F1 races

Race Selection (Full Historical Race mode):

• Year - Select from available years (2018-2024)
• Race - Select specific race from chosen year

Configuration:

• Commentary Mode - Basic or Enhanced (Enhanced recommended)
• Playback Speed - 1x (real-time), 5x, 10x, or 20x
• ElevenLabs API Key - Your ElevenLabs API key for audio synthesis
• Voice ID - ElevenLabs voice ID (default provided)

Controls:

• Start Commentary - Begin playback with selected configuration
• Stop - Halt active commentary

Configuration

ElevenLabs API Key

To enable audio synthesis, you need an ElevenLabs API key:

1. Sign up at ElevenLabs
2. Get your API key from the dashboard
3. Enter it in the Web UI before starting commentary

Environment Variables (Optional)

You can also set credentials via environment variables:

export ELEVENLABS_API_KEY="your_api_key_here"
export ELEVENLABS_VOICE_ID="your_voice_id_here"

Quick Demo Mode

Perfect for showcasing the system without internet connectivity:

• Pre-configured 2-3 minute demonstration
• Includes overtakes, pit stops, fastest lap, and incidents
• Demonstrates commentary variety and robot movements
• No OpenF1 API connection required

Full Historical Race Mode

Experience past F1 races with generated commentary:

• Select from 100+ historical races (2018-2024)
• Configurable playback speed (1x to 20x)
• Real race data from OpenF1 API
• Complete race commentary with all significant events

Enhanced Commentary System

The enhanced commentary system generates organic, natural-sounding commentary:

• 210 Templates - Extensive variety prevents repetition
• 5 Excitement Levels - Calm to dramatic based on event significance
• 5 Perspectives - Technical, strategic, dramatic, positional, historical
• Context Enrichment - Multiple data points per commentary
• Narrative Tracking - Detects battles, comebacks, strategy divergence
• Frequency Controls - Prevents repetitive content patterns

Example Commentary

Basic Mode:

"Hamilton gets past Verstappen! Up to P1!"

Enhanced Mode:

"Fantastic overtake by Hamilton on Verstappen, now in P1!"
"There it is! Hamilton takes the lead from Verstappen!"
"Hamilton makes a brilliant move on Verstappen for P1!"

Requirements

• Reachy Mini (or simulation mode)
• Python 3.9+
• ElevenLabs API Key (for audio synthesis)
• Internet Connection (for Full Historical Race mode)

Development

Running in Standalone Mode

For development and testing without the Reachy Mini framework:

# Method 1: Run main module directly (recommended)
python -m reachy_f1_commentator.main

# Method 2: Use the app.py wrapper
python reachy_f1_commentator/app.py

The app will:

• Auto-detect and connect to Reachy if available
• Fall back to text-only mode if Reachy is not connected
• Start web server on http://localhost:8080

Testing Reachy Connection

To verify Reachy Mini connection and audio capabilities:

python test_reachy_audio_connection.py

This will check:

• ✅ Reachy Mini SDK installation
• ✅ Connection to Reachy
• ✅ Audio capabilities
• ✅ Simple audio playback test

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_enhanced_commentary_generator.py

# Run with coverage
pytest --cov=reachy_f1_commentator

Architecture

reachy_f1_commentator/
├── main.py                    # ReachyMiniF1Commentator app class
├── static/                    # Web UI assets
│   ├── index.html
│   ├── main.js
│   └── style.css
├── src/                       # Commentary generation components
│   ├── enhanced_commentary_generator.py
│   ├── speech_synthesizer.py
│   ├── motion_controller.py
│   └── ...
├── config/                    # Configuration and templates
│   ├── enhanced_templates.json
│   └── config_enhanced_example.json
└── tests/                     # Test suite

Credits

Based on the F1 Commentary Robot project with Enhanced Organic Commentary System.

Key Features:

• Enhanced commentary generation with 210 templates
• Context enrichment from multiple OpenF1 API endpoints
• Event significance scoring with context bonuses
• Narrative thread tracking (battles, comebacks, strategy)
• Dynamic commentary styles (5 excitement levels × 5 perspectives)
• Frequency controls for content variety

License

MIT License - See LICENSE file for details

Support

For issues, questions, or contributions:

• Open an issue on the repository
• Check the documentation
• Join the Reachy Mini community

Acknowledgments

• Pollen Robotics - Reachy Mini platform
• Hugging Face - App hosting and distribution
• OpenF1 - Historical race data API
• ElevenLabs - Text-to-speech synthesis