aabyzov/easychamp-player-detection-yolov8

EasyChamp Player Detection YOLOv8

Fine-tuned YOLOv8 model for detecting soccer/football players, ball, and referees in match videos.

Model Description

This model is part of the EasyChamp sports analytics platform. It has been fine-tuned on custom soccer match footage to detect:

• Players (Team A & Team B)
• Ball
• Referees
• Goalkeepers

The model is optimized for real-time video processing and works in conjunction with SigLIP embeddings for team classification.

Model Details

• Architecture: YOLOv8 (Ultralytics)
• Input: Video frames (various resolutions)
• Output: Bounding boxes with confidence scores
• Classes: 4 (player, ball, referee, goalkeeper)
• Confidence Threshold: 0.3 (default)
• Training Dataset: Custom soccer match videos
• Framework: PyTorch

Performance

• Precision: 92%
• Recall: 88%
• mAP@50: 90%
• Processing Speed: ~30-60s for 10s video (M4 Mac MPS)

Usage

With Ultralytics

from ultralytics import YOLO

# Load model from Hugging Face
model = YOLO('https://huggingface.co/aabyzov/easychamp-player-detection-yolov8/resolve/main/player_detection_best.pt')

# Run inference
results = model('path/to/video.mp4', conf=0.3)

# Process results
for result in results:
    boxes = result.boxes  # Bounding boxes
    for box in boxes:
        x1, y1, x2, y2 = box.xyxy[0]  # Box coordinates
        conf = box.conf[0]  # Confidence
        cls = box.cls[0]  # Class

With EasyChamp ML API

# Process video with full pipeline (detection + tracking + team classification)
curl -X POST https://easychamp.com/ec-ml-api/api/video/process \
  -F "[email protected]"

# Or use YouTube URL
curl -X POST https://easychamp.com/ec-ml-api/api/video/process \
  -H "Content-Type: application/json" \
  -d '{"youtube_url": "https://youtu.be/VIDEO_ID"}'

Integration

This model is used in the EasyChamp video processing pipeline:

1. Detection: YOLO detects all objects (players, ball, refs)
2. Classification: SigLIP classifies players into teams
3. Tracking: Stable IDs assigned to players across frames
4. Projection: 2D pitch mapping via homography
5. Annotation: Team-colored bounding boxes and radar overlay

Model Card

Property	Value
Model Type	Object Detection
Architecture	YOLOv8
Input	RGB Video Frames
Output	Bounding Boxes + Confidence
Classes	4 (player, ball, referee, goalkeeper)
Framework	PyTorch (Ultralytics)
Size	137 MB
License	MIT

Limitations

• Optimized for outdoor soccer matches with clear lighting
• May struggle with:
  • Heavy occlusion
  • Low-light conditions
  • Very crowded scenes
  • Non-standard camera angles

Citation

If you use this model, please cite:

@software{easychamp_player_detection_2025,
  author = {EasyChamp},
  title = {EasyChamp Player Detection YOLOv8},
  year = {2025},
  url = {https://huggingface.co/aabyzov/easychamp-player-detection-yolov8},
  publisher = {Hugging Face}
}

Links

• Platform: EasyChamp
• API Documentation: ec-ml-api
• Model Repository: GitHub

License

MIT License - See LICENSE file for details.