Hoops Clips
End-to-end pipeline that watches basketball game footage, detects exciting plays, and automatically generates highlight clips ready for sharing.
⚡ What It Delivers
Auto Highlight Detection
Detects dunks, threes, blocks, steals, and fast breaks without manual review.
Clip Generation
Generates short clips with smart padding and exports ready-to-share MP4s.
Coach Workflow
Designed for teams: batch input, ranked output, and quick review cycles.
🧭 How It Works
Ingest
Upload full-game footage or point to a hosted video URL.
Detect
Sample frames and run the action model to score candidate plays.
Rank
Sort plays by confidence and excitement score.
Export
Generate clipped MP4s with timestamps and metadata.
🎯 The Problem
Coaches and players record hours of game footage but rarely have time to review it all. Manually scrubbing through videos to find key plays is tedious and often doesn't happen.
A single game produces 1-2 hours of video. Nobody watches all of it.
Creating highlight reels takes hours of scrubbing and cutting.
Great plays go unshared because no one has time to find them.
👥 Users & Impact
Target Users
- High school and college basketball coaches
- Players building recruiting highlight reels
- Parents capturing their kids' best moments
- Sports content creators and analysts
🎬 Demo
Video Walkthrough
Demo video coming soon
Full pipeline demonstrationScreenshots
🚀 Run or Install
Run with Docker
# Pull the image
docker pull charlie2233/hoops-clips:latest
# Run the server
docker run -p 8787:8787 -v ./videos:/app/input charlie2233/hoops-clips
# Send a video for processing
curl -X POST http://localhost:8787/api/ai/analyze \
-H "Content-Type: application/json" \
-d '{"videoUrl":"https://example.com/game.mp4"}'Requires Docker and ~8GB disk space for model weights.
🛰 Backend & API
Live API
Not connected yet. Add your Google Cloud URL to enable.
API Endpoints
POST /api/ai/analyze
Submit a video URL for analysis. Returns a job ID.
GET /api/ai/result/{jobId}
Fetch the result payload with detected events and confidence scores.
GET /health
Health check endpoint used by Cloud Run.
{ "videoUrl": "https://example.com/game.mp4" }🏗️ Architecture
┌─────────────────────────────────────────────────────────────┐
│ Hoops Clips Pipeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Video │───▶│ Frame │───▶│ Action │ │
│ │ Input │ │ Sampler │ │ Detector │ │
│ └──────────────┘ └──────────────┘ │ (CNN+LSTM) │ │
│ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MP4 │◀───│ Clip │◀───│ Event │ │
│ │ Output │ │ Generator │ │ Ranker │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
├─────────────────────────────────────────────────────────────┤
│ Actions: Dunk │ Three-Pointer │ Block │ Fast Break │ Steal│
└─────────────────────────────────────────────────────────────┘
Tech Stack
✨ Key Features
Action Detection
Recognizes dunks, three-pointers, blocks, steals, and fast breaks automatically.
Auto Clip Generation
Extracts highlight moments with smart padding before and after the action.
Excitement Ranking
Scores plays by intensity so you can pick the best of the best.
Batch Processing
Queue multiple games and process overnight for morning highlights.
REST API
Simple HTTP interface for integration with other tools and workflows.
Docker Ready
One-command deployment with all dependencies bundled.
📊 Metrics & Results
Testing Notes
Tested on 50+ hours of high school and college game footage. Works best with tripod-mounted cameras at sideline level. Performance degrades with shaky handheld footage.
🗺️ Roadmap
Action detection, clip generation, REST API
Containerization, batch processing queue
Browser-based interface for non-technical users
Individual player identification and stats
🙏 Credits
Charlie Han
Atrak Team
PyTorch
OpenCV + FFmpeg
Basketball_action_recoginition_sever (private) by hkair (original author)
Atrak team integrations & improvements
Thanks to the open-source computer vision community and the sports analytics researchers whose work made this possible.