beketov027/soccer_labeling_tool

Soccer Event Labeller

A desktop labeling tool for annotating soccer (football) match videos frame by frame. It is designed to build a dataset of short clips (for example, 30-second segments) with timestamped event labels for training or evaluation.

Overview

The app loads videos from a folder, lets you scrub through frames, and mark when specific in-game events occur. Labels are saved automatically as JSON files alongside your videos. A timeline shows color-coded markers for each labeled event, and the sidebar tracks overall dataset progress.

Main script: soccer_event_labeller.py

Input

Video files

Place match clips in the videos/ folder (created automatically on first run), or choose another folder with Open… in the sidebar.

Property	Details
Location	videos/ by default, or any folder you select
Formats	.mp4, .avi, .mov, .mkv, .webm
Content	Soccer match footage (typically short clips for dataset building)

The last-used video folder is stored in .labeller_config.json so the app reopens the same directory next time.

Event classes

When labeling, you assign one of these event types to the current frame:

Event	Shortcut
pass	1
pass_received	2
recovery	3
tackle	4
interception	5
ball_out_of_play	6
clearance	7
take_on	8
substitution	9
block	0
arial_duel	Q
shot	W
save	E
foul	R
goal	T

Output

Label JSON files

For each video videos/<name>.<ext>, the tool writes labels/<name>.json.

Property	Details
Location	labels/ (next to the project when using the default videos/ folder; otherwise a labels/ folder beside your custom video directory)
Format	JSON array of annotation objects
Auto-save	Labels are saved automatically when you add, edit, or remove annotations

Example (labels/input.json for video videos/input.mp4):

[
    {
        "frame": 0,
        "event": "interception"
    },
    {
        "frame": 336,
        "event": "ball_out_of_play"
    }
]

Each entry contains:

• frame — zero-based frame index where the event occurs
• event — one of the event class names listed above

Annotations are sorted by frame (then event name) when saved. Multiple different events can be labeled on the same frame; duplicate frame + event pairs are not allowed.

Setup

Requires Python 3.11+ and these packages:

• customtkinter
• opencv-python
• Pillow

python -m venv .venv
.venv\Scripts\activate        # Windows
pip install customtkinter opencv-python Pillow

Usage

python soccer_event_labeller.py

1. Add videos to videos/ or click Open… to pick another folder.
2. Select a video from the sidebar list (green = labeled, gray = unlabeled).
3. Scrub or play the video to the moment an event happens.
4. Click an event button or press its keyboard shortcut to label the current frame.
5. Labels are written to labels/<video_name>.json automatically.

Keyboard shortcuts

Action	Key
Play / pause	Space
Previous / next frame	← / →
Step ±1 second	Shift+← / Shift+→
Label event	1–0, Q–T (see table above)
Delete selected label	Delete / Backspace
Undo last label	Ctrl+Z
Save labels	Ctrl+S
Previous / next video	P / N
Go to selected label	G

Project structure

event_labeler/
├── soccer_event_labeller.py   # Main application
├── videos/                    # Input videos (default)
├── labels/                    # Output JSON annotations
├── .labeller_config.json      # Saved video folder path
└── .venv/                     # Python virtual environment (optional)