README.md

---
title: Athletic Ability Analysis
emoji: 🏃‍♂️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.32.2
app_file: app.py
pinned: false
license: mit
---

# 🏃‍♂️ Athletic Ability Analysis

A powerful web application that analyzes athletic jump performance from videos using computer vision and pose estimation. Upload a video file or provide a YouTube URL to get detailed metrics about your jump height, flight time, and overall athletic performance.

## ✨ Features

- **🎥 YouTube Integration**: Analyze videos directly from YouTube URLs
- **📁 File Upload**: Support for MP4, AVI, MOV, and other video formats  
- **📊 Comprehensive Biomechanical Analysis**: Jump height, flight time, peak power, force development, and more
- **🤖 AI Sports Coach**: Get personalized sport recommendations and technique improvements
- **🎯 Real-time Processing**: Fast analysis using Google's MediaPipe pose estimation
- **📱 Modern Interface**: Beautiful, responsive Gradio interface with multiple analysis modes
- **🔬 Scientific Accuracy**: Professional-grade biomechanical analysis
- **⚡ Advanced Metrics**: Peak power output, rate of force development, impulse, and ground contact time

## 🚀 Live Demo

Try the live demo on Hugging Face Spaces: [Athletic Ability Analysis](https://huggingface.co/spaces/YOUR_USERNAME/athletic-ability-analysis)

## 📊 How It Works

1. **Pose Detection**: Uses Google's MediaPipe to detect human pose landmarks in each video frame
2. **Hip Tracking**: Tracks the midpoint between left and right hip joints throughout the video
3. **Jump Analysis**: Calculates jump metrics based on hip trajectory:
   - **Jump Height**: Vertical distance from crouch to apex (in cm)
   - **Flight Time**: Duration of airborne phase (in seconds)
   - **Normalized Rise**: Jump height relative to body position (0-1 scale)
   - **Performance Insights**: Contextual feedback based on performance level

## 🛠️ Technology Stack

- **Backend**: Python with OpenCV, NumPy, and MediaPipe
- **Frontend**: Gradio for beautiful, interactive web interface
- **Video Processing**: yt-dlp for YouTube downloads, OpenCV for video analysis
- **Deployment**: Hugging Face Spaces

## 🚀 Deploy to Hugging Face Spaces

### Quick Deployment

1. **Fork this repository** on GitHub
2. **Create a new Space** on [Hugging Face Spaces](https://huggingface.co/spaces)
3. **Connect your GitHub repo** to the Space
4. **Set the Space type** to "Gradio"
5. **⚠️ IMPORTANT: Set up API Key Environment Variable**:
   - Go to your Space's "Settings" tab
   - Add a new "Secret" with name: `GEMINI_API_KEY`
   - Add your Gemini API key as the value
   - This keeps your API key secure and private
6. **Wait for automatic deployment**

### Manual Deployment

1. **Clone the repository**:
   ```bash
   git clone https://github.com/YOUR_USERNAME/athletic-ability-analysis
   cd athletic-ability-analysis
   ```

2. **Create a new Space** on Hugging Face Spaces

3. **Upload files** to your Space:
   - `app.py` (main application)
   - `athletic_performance.py` (analysis module)
   - `requirements.txt` (dependencies)
   - `README.md` (this file)

4. **🔐 Set up Secure API Key**:
   - In your Space settings, add environment variable: `GEMINI_API_KEY`
   - Get your free API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
   - **NEVER commit API keys to your repository!**

5. **Space will automatically deploy** using Gradio

### 🔐 API Key Security

For the AI Sports Coach feature, you need a Google Gemini API key:

- **🆓 Free**: Get your key at [Google AI Studio](https://aistudio.google.com/app/apikey)
- **🔒 Secure**: Set as environment variable `GEMINI_API_KEY` in HF Spaces
- **🚫 Never**: Commit API keys to code repositories
- **✅ Best Practice**: Use HF Spaces secrets for deployment

## 📁 Project Structure

```
athletic-ability-analysis/
├── app.py                    # Main Gradio application & UI
├── athletic_performance.py   # Core analysis & AI integration
├── requirements.txt          # Python dependencies
├── README.md                # This file (with HF Spaces header)
├── deploy_hf.py             # Deployment helper script
├── test_deployment.py       # Dependency testing
└── .gitignore              # Git ignore file
```

## 🎯 Usage

### Web Interface

1. **Visit your Hugging Face Space URL**
2. **Enter your height and weight** for accurate biomechanical calculations
3. **Choose your analysis type**:
   
   **📊 Standard Analysis:**
   - YouTube or File Upload tabs
   - Get comprehensive biomechanical metrics
   
   **🤖 AI Sports Coach:**
   - Select your gender
   - Provide video (YouTube URL or upload)
   - Get personalized sport recommendations
   - Receive jump technique improvement suggestions

4. **Click analyze** and wait for processing
5. **View comprehensive results** with detailed insights

### Supported Video Formats

- **YouTube**: Any public YouTube video URL
- **Upload**: MP4, AVI, MOV, MKV, WebM

## 📝 Video Requirements

For optimal results, ensure your videos meet these criteria:

- **🎯 Full Body Visible**: Person should be completely visible throughout the jump
- **💡 Good Lighting**: Clear visibility with minimal shadows
- **🎬 Clean Background**: Minimal clutter for better pose detection
- **⏱️ Optimal Duration**: 3-30 seconds works best
- **📐 Vertical Jumps**: Straight vertical jumps produce most accurate results
- **🔓 Public Access**: For YouTube videos, ensure they're not private

## 📊 Performance Metrics

The app analyzes and provides:

- **Jump Height (cm)**: Absolute vertical distance based on your body height
- **Flight Time (s)**: Duration of airborne phase
- **Normalized Rise**: Jump efficiency relative to body size
- **Performance Level**: Contextual feedback (Excellent/Good/Moderate/Starting)
- **Training Insights**: Personalized recommendations

## 🔬 Technical Details

- **Pose Estimation**: MediaPipe Pose with 33 body landmarks
- **Processing**: Real-time frame-by-frame analysis
- **Smoothing**: Moving average filtering for noise reduction
- **Calculations**: Biomechanically accurate jump metrics
- **Performance**: Optimized for cloud deployment

## ⚠️ Limitations

- **Processing Time**: Large videos may take 2-5 minutes to process
- **File Size**: Recommended maximum 100MB for uploads
- **Pose Visibility**: Person must be clearly visible throughout the jump
- **Jump Type**: Optimized for vertical jumps (not broad jumps)

## 🔧 Local Development

To run locally:

1. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

2. **Run the application**:
   ```bash
   python app.py
   ```

3. **Open in browser**: Gradio will provide a local URL

## 🤝 Contributing

Contributions are welcome! Please feel free to:

- Submit bug reports and feature requests
- Improve documentation
- Add new analysis features
- Optimize performance

## 📄 License

This project is open source and available under the [MIT License](LICENSE).

## 🆘 Support & Troubleshooting

If you encounter issues:

1. **Video Quality**: Ensure good lighting and clear visibility
2. **YouTube URLs**: Make sure the video is public and accessible
3. **File Formats**: Use supported video formats (MP4, AVI, MOV, etc.)
4. **Processing Time**: Be patient with large or high-resolution videos
5. **Pose Detection**: Person should be fully visible during the jump

## 🙏 Acknowledgments

- **Google MediaPipe** for state-of-the-art pose estimation
- **OpenCV** for computer vision processing
- **yt-dlp** for YouTube video downloading
- **Gradio** for the beautiful web interface
- **Hugging Face** for hosting and deployment platform

## 📈 Example Results

```
🎉 Jump Analysis Results

📊 Performance Metrics
- Jump Height: 52.34 cm
- Flight Time: 0.623 seconds  
- Normalized Rise: 0.387 (38.7%)

🔥 Excellent jump height! This is above average performance.
⏱️ Great flight time! Shows good explosive power.
```