This repository contains a web-based tool for annotating football (soccer) videos. The tool allows users to upload videos, add annotations for specific events (e.g., goals, fouls, penalties), and save these annotations for later use.
This application is intended to be used with SoccerNet annotations to ease the process of event annotations. For more information, visit SoccerNet.
demo.webm
- Video Upload: Upload football videos in common formats (e.g., MP4, AVI).
- Annotation Management:
- Add annotations for specific events (e.g., goals, fouls, penalties)
- Edit or delete existing annotations
- Filter annotations by event type
- Save and Load Annotations: Save annotations to a JSON file and load them when reopening the video
- Frontend:
- Backend:
- Flask (Python) for handling file uploads and serving annotations
- Video Processing:
- OpenCV for extracting video metadata (e.g., duration)
- Python 3.x
-
Clone the Repository:
git clone https://github.com/ibrahimabdelaal/Soccer-event-annotation-tool.git cd football-video-annotation-tool -
Install Dependencies:
pip install -r requirements.txt
-
Prepare Your Files:
- Place your video files in the
uploadsfolder - Store annotation files in the
annotationsfolder
The tool supports two annotation formats:
-
Basic Format (Legacy)
- Create a JSON file with the same name as your video
- Example: For
match1.mp4, creatematch1.jsonin the annotations folder - Reference: See
old_structure.jsonfor format details
-
Standard Soccer Net Format
- Uses the OpenSportsLab standard format
- Place your annotations in
standard.jsonin the annotations folder - The tool automatically:
- Detects if
standard.jsonexists - Finds annotations matching your video filename
- Detects if
- Compatible with OSL-ActionSpotting
- Reference: See
standard.jsonfor format details
⚠️ Important Note:- If
standard.jsonexists in the annotations folder, the tool will always use it, even if you have corresponding files in the basic format - To use the basic format, ensure
standard.jsonis removed from the annotations folder
project/ ├── uploads/ │ ├── match1.mp4 │ └── match2.mp4 └── annotations/ ├── match1.json (Basic format) ├── match2.json (Basic format) └── standard.json (Soccer Net format) - Place your video files in the
To start the application, run the app.py file:
python app.py- Click the "Choose File" button to upload a video
- Once uploaded, the video will be displayed in the player
- Make sure that the corresponding annotation file is located in annotations folder with the same name as your video
- See the structure of the JSON annotation file the app works with (example can be found in
annotations_output.json)
- Use the "Add Event" button to open the annotation modal
- Fill in the event details (e.g., time, label, team, visibility) and save the annotation
- Click the "Save Annotations" button to save the annotations to a JSON file
- When reopening a video, annotations will be loaded automatically if a corresponding JSON file exists