threader-python

Python SDK for Threader — read football video annotation data and bridge notebook analysis back to the Threader desktop app.

Installation

pip install threader-python

Or with visualization extras:

pip install "threader-python[viz]"

Quick Start

Inside a Threader Notebook

When running inside Threader's built-in notebook, the connection is automatic:

import threader_python as tp

# Query data — returns pandas DataFrames
events = tp.events(type="pass")
players = tp.players()
teams = tp.teams()

# Filter passes between two players
pair = events[(events.player_id == "p1") & (events.receiver_id == "p2")]

# Send selection to Threader — Clips panel filters automatically
tp.select(pair)

# Or create a playlist directly
tp.playlist(pair, title="Messi → Alba passes")

Standalone (Jupyter Lab, VS Code, etc.)

Point to a .threader project file manually:

import threader_python as tp

tp.connect("/path/to/match.threader")

events = tp.events(type="shot")
print(events[["player_id", "x", "y", "is_successful"]])

Data access works fully in standalone mode. Bridge actions (select, play, playlist) print a summary instead of triggering UI interactions.

API Reference

Connection

Data Access

All data functions return a pandas.DataFrame (except match() which returns a dict).

Bridge Actions (Threader Integration)

These functions communicate with the Threader desktop app when running inside a Threader notebook:

All bridge functions accept either a DataFrame (with an id column) or a list of ID strings.

How It Works

• Data access: Reads directly from the .threader SQLite file (read-only, WAL-safe for concurrent access)
• Bridge actions: Emit a custom MIME type (application/x-threader+json) via IPython's display(), which the Threader app's notebook renderer picks up and dispatches to the UI

Development

# Clone and install
git clone https://github.com/rondo-labs/threader-python.git
cd threader-python
uv sync

# Run tests
uv run pytest

# Lint
uv run ruff check src/ tests/

License

MIT