🏋️‍♂️ RepLica — Real-Time AI Workout Coach

RepLica turns your webcam into a personal fitness trainer. It watches your exercise form in real time and provides instant, spoken feedback — powered by pose detection, an LLM coaching engine, and text-to-speech.

---

🎯 What RepLica Does

Start a workout session, pick an exercise, and let RepLica handle the rest:

• 🧘 Real-Time Body Tracking: Tracks 33 body landmarks using MediaPipe pose detection through your webcam.
• 📐 Precision Form Analysis: Evaluates joint angles, depth, alignment, and balance per rep tailored to specific exercises (Squats, Push-ups, Bicep Curls, Shoulder Press, Lunges).
• 🗣️ Hands-Free Voice Coaching: Groq (Llama 3.3 70B) generates contextual feedback converted to speech in real time, so you never need to interrupt your set to look at a screen.
• 📊 Workout History Logging: Tracks reps, sets, and duration per session, saved locally in SQLite and presented in a clean summary dashboard.

---

🔄 How It Works

Webcam Feed 📷 ──> MediaPipe Pose Detection 🧘 ──> Per-Exercise Metrics 📐
                                                             │
SQLite History 📊 <── Session Progress Synced 🏁 <── Live Audio Feedback 🔊 <── LLM Coaching (Groq) 🤖

🏗️ System Architecture

RepLica/
├── main.py                    # Streamlit UI tying vision, state, and audio together
├── detectors/                 # Per-exercise form analysis (angles, thresholds, flags)
└── services/
    ├── vision/                # WebRTC video capture & MediaPipe pose processing
    ├── tracking/              # Syncs live metrics to app state & detects reps/sets
    ├── coaching/              # LLM prompt engineering, TTS, & debounced voice pipeline
    ├── persistence/           # SQLite-backed workout history database
    ├── auth/                  # Lightweight session/user handling
    └── state/                 # Streamlit session state management

🛠️ Tech Stack

Domain	Technology / Library
Frontend & UI	Streamlit
Real-Time Video	streamlit-webrtc, OpenCV
Pose Detection	MediaPipe
LLM Coaching Engine	Groq API (Llama 3.3 70B)
Text-to-Speech (TTS)	gTTS
Database	SQLite
Package Manager	uv

---

⚡ Notable Engineering Highlights

• Debounced Voice Feedback: The AI coach uses a priority queue with rate-limiting so it never speaks over itself or spams minor form corrections during a rep.
• Per-Exercise Metric Schemas: Centralized exercise configurations isolate math rules and thresholds, avoiding messy conditional logic across the codebase.
• Frame-Rate Optimized Pipeline: Model complexity and frame resolution are tuned specifically to maintain high FPS and low latency (sub-100ms) on standard webcams.

Create virtual environment with uv

uv venv --python 3.12

Activate Virtual Environment

• On Windows (PowerShell):

  .venv\Scripts\activate

• On macOS / Linux:

 .venv/bin/activate

Install dependencies

uv pip install -r requirements.txt

3. Configure API Keys

Create a .env file in the project root:

GROQ_API_KEY=your_groq_api_key_here

4. Run the Application

uv run streamlit run main.py

📌 Status & Roadmap

🟢 Actively Developed

• Real-time pose analysis & rep counting
• LLM + TTS debounced voice feedback pipeline
• Local SQLite workout history logging
• Automated testing suite
• Expanded exercise library
• Cloud deployment

---

👤 Author

Sumit Sana

• GitHub: @sumitstat07
• Email: sumitsana2002@gmail.com
• Landing Page: replica-ai-gym-coach.netlify.app