OpenSportsLib is a modular Python library for sports video understanding.
It provides a unified framework to train, evaluate, and run inference for key temporal understanding tasks in sports video, including:
- Action classification
- Action localization / spotting
- Action retrieval
- Action description / captioning
OpenSportsLib is designed for researchers, ML engineers, and sports analytics teams who want reproducible and extensible workflows for sports video AI.
- Unified workflow for training and inference
- Modular design for adding new tasks, datasets, and models
- Config driven experiments for reproducibility
- Support for multiple modalities and sports workflows
- Research friendly while still usable in applied settings
- Documentation: https://opensportslab.github.io/opensportslib/
- PyPI: https://pypi.org/project/opensportslib/
- Issues: https://github.com/OpenSportsLab/opensportslib/issues
Requires Python 3.12+.
Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).
PyTorch Geometric is supported up to PyTorch 2.10.*.
pip install opensportslibpip install --pre opensportslib# Install PyTorch (CPU/GPU auto-detected)
opensportslib setup
# Optional: install PyTorch Geometric support
opensportslib setup --pyg
# Optional: install for DALI support
opensportslib setup --daliNote:
Run opensportslib setup to automatically configure dependencies.
If issues occur, manually install compatible versions of torch, torchvision, and related libraries according to your CUDA version or system compatibility.
OpenSportsLib uses external annotation files, datasets, and pretrained checkpoints.
Public assets are hosted under the OpenSportsLab Hugging Face organization:
https://huggingface.co/OpenSportsLab
Use it as the main entry point to find:
- datasets
- annotation files
- extracted features
- pretrained models and checkpoints
--
import opensportslib
print("OpenSportsLib imported successfully")from opensportslib.apis import ClassificationModel
my_model = ClassificationModel(
config="/path/to/classification.yaml",
weights="/path/to/weights.pt", # optional
)
my_model.train(
train_set="/path/to/train_annotations.json",
valid_set="/path/to/valid_annotations.json",
)from opensportslib.apis import ClassificationModel
my_model = ClassificationModel(
config="/path/to/classification.yaml",
weights="/path/to/weights.pt", # optional
)
predictions = my_model.infer(
test_set="/path/to/test_annotations.json",
)
saved_predictions = my_model.save_predictions(
output_path="/path/to/predictions.json",
predictions=predictions,
)
metrics = my_model.evaluate(
test_set="/path/to/test_annotations.json",
)
metrics_from_file = my_model.evaluate(
test_set="/path/to/test_annotations.json",
predictions=saved_predictions,
)
print(metrics)from opensportslib.apis import LocalizationModel
my_model = LocalizationModel(
config="/path/to/localization.yaml",
weights="/path/to/weights.pt", # optional
)
predictions = my_model.infer(
test_set="/path/to/test_annotations.json",
)
saved_predictions = my_model.save_predictions(
output_path="/path/to/predictions.json",
predictions=predictions,
)
metrics = my_model.evaluate(
test_set="/path/to/test_annotations.json",
)
metrics_from_file = my_model.evaluate(
test_set="/path/to/test_annotations.json",
predictions=saved_predictions,
)OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
from opensportslib.tools import (
download_dataset_split_from_hf,
upload_dataset_inputs_from_json_to_hf,
upload_dataset_as_parquet_to_hf,
)python tools/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
python tools/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision mainDownloads are placed under <output-dir>/<revision>/<split>.
Classify clips or event centered samples into predefined categories.
Predict when key events happen in long untrimmed sports videos.
Search and retrieve relevant clips or moments from a collection of sports videos.
Generate text descriptions for sports events and temporal segments.
- Prepare your dataset in the expected format
- Select or create a YAML config
- Initialize the task specific model
- Train on your annotations
- Run inference on new data
- Extend the pipeline with your own datasets or models
Use the README for the fast start, then go deeper through:
- Full documentation: https://opensportslab.github.io/opensportslib/
- High-level API guide: opensportslib/apis/README.md
- Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
- Example configs: examples/configs/
- Quickstart scripts: examples/quickstart/
- Contribution guide: CONTRIBUTING.md
- Developer guide: DEVELOPERS.md
For contributors who want to work from source:
git clone https://github.com/OpenSportsLab/opensportslib.git
cd opensportslib
pip install -e .If you prefer conda:
conda create -n osl python=3.12 pip
conda activate osl
pip install -e .# Install PyTorch (CPU/GPU auto-detected)
opensportslib setup
# Optional: install PyTorch Geometric support
opensportslib setup --pyg
# Optional: install for DALI support
opensportslib setup --dali- Make sure you are branching from
dev - Create your feature or fix branch from
dev - Open a pull request back into
dev
We welcome contributions to OpenSportsLib.
Please check:
These documents describe:
- how to add models and datasets
- coding standards
- training pipeline structure
- how to run and test the framework
OpenSportsLib is available under dual licensing.
AGPL 3.0 for research, academic, and community use.
For proprietary or commercial deployment, please refer to LICENSE-COMMERCIAL.
If you use OpenSportsLib in your research, please cite the project.
@misc{opensportslib,
title={OpenSportsLib},
author={OpenSportsLab},
year={2026},
howpublished={\url{https://github.com/OpenSportsLab/opensportslib}}
}OpenSportsLib is developed within the broader OpenSportsLab effort for sports video understanding.