FormCheck is a real-time computer vision application that analyzes exercise form using a hybrid Client-Server architecture. It uses a lightweight React frontend for capture and rendering, and a high-performance Python FastAPI backend for MediaPipe inference.
- Real-Time Analysis: < 100ms latency inference loop.
- Geometric Logic: Calculates joint angles to verify Range of Motion (ROM).
- Rep Counting: State-machine based repetition tracking (Eccentric/Concentric phases).
- Tactical UI: "Glassmorphic" dark mode interface with live HUD overlay.
- Privacy: Video frames are processed in-memory and never stored.
- Framework: React (Vite) + TypeScript
- Styling: Tailwind CSS
- State Management: Zustand
- Sockets:
react-use-websocket - Capture:
react-webcam
- Framework: FastAPI (Python 3.10+)
- Inference: MediaPipe Pose
- Math: NumPy
- Server: Uvicorn (WebSockets)
- Node.js 18+
- Python 3.10+
cd server
python -m venv venv
# Windows
.\venv\Scripts\activate
# Linux/Mac
# source venv/bin/activate
pip install -r requirements.txt
python run.pyServer runs on ws://localhost:8000
cd client
npm install
npm run devClient runs on http://localhost:5173
- Ingestion: Client captures webcam frame (480p @ 12fps).
- Transport: Frame sent as JPEG/Base64 via WebSocket to Backend.
- Inference: Python/MediaPipe extracts 33 skeletal landmarks.
- Logic:
RepCounterclass calculates angles (e.g., Elbow) to determine state. - Feedback: Server returns
Landmarks + Rep Count + Feedback. - Render: Client draws wireframe overlay on canvas atop video.
Project designed as a technical showcase. Pull requests welcome.
We follow Conventional Commits:
<type>(<scope>): <subject>
<body>
Types:
feat: New featurefix: Bug fixdocs: Documentation onlystyle: Code style (formatting, no logic change)refactor: Code restructuring (no behavior change)perf: Performance improvementtest: Adding/updating tests
Examples:
feat(exercises): add bicep curl detection
fix(database): resolve streak calculation timezone bug
docs(api): update WebSocket protocol specification
perf(pose): optimize landmark serialization (20% faster)