Good-Badminton: an AI hawk-eye pipeline for badminton match video

What Good-Badminton actually computes from a match video

The project takes a badminton match recording and produces measurements that are hard to get by watching. Player pose is detected per frame, the shuttlecock is detected with a YOLO model, and both are projected through a court coordinate mapping so that distances and speeds are expressed on the court rather than in pixels. The output is a set of artifacts: an annotated video, a detections.jsonl file with per-frame records, and position heatmaps and scatter plots.

The intended user is a developer or researcher who wants raw movement data from footage they already own. The README states that video, models and analysis results all stay local, which matters if the footage is not yours to upload. The README also groups it with Good-Tennis and Good-Pickleball, sibling projects that share the same pipeline shape (player detection, ball tracking, court mapping, statistics, visualization) but differ in court model and rules.

One thing the repository is not: a racket-shopping resource. Search traffic around this name is dominated by equipment and coaching queries, and none of that is what this code does. It is a video analysis tool with a Python entry point.

Court mapping is the hinge the whole pipeline turns on

Every statistic depends on the four-point court annotation. The README explains why: the four corners establish the mapping from image coordinates to standard court coordinates, and that mapping is what filters out spectators, umpires and people standing outside the court. Half-court assignment, movement distance, speed, rally counting, heatmaps and scatter plots all read from it.

Automatic court detection was added on 2026-06-23 and refined on 2026-06-27, per the changelog, matching white or yellow court lines against a standard badminton court line model. It is not treated as infallible. The first-run flow writes outputs/<video filename>/auto_court_preview.png, and the operator either accepts the automatic result or switches to manual four-corner marking. In the WebUI, the README describes the same escape hatch: click four corner points on the image and apply them.

The annotation is cached at outputs/<video filename>/court_annotations.txt and reused on later runs in the same output directory. That cache is also the sharp edge. The README says plainly that if you change the video viewpoint, the crop, or the template image, you must delete court_annotations.txt and mark the four points again. Nothing detects that your camera moved. A stale annotation file will silently produce plausible-looking distances computed against the wrong mapping.

Rally detection is a separate mechanism and worth separating in your head from court mapping. It works by court template matching: consecutive frames recognized as the match view open a rally, and consecutive frames leaving that view close it. The rally number appears in the video overlay and in the detection data. This is a view classifier, not a shot classifier, so a long close-up of a player between points is what ends a rally, not a shuttlecock landing.

Installing Good-Badminton and running the first analysis

The README requires Python 3.8 or newer, FFmpeg on the system PATH, and the badminton YOLO weights downloaded from the project's GitHub Releases page. Default dependencies in requirements.txt are CPU builds: torch==2.5.1+cpu, torchvision==0.20.1+cpu and onnxruntime==1.18.1, pulled with an extra index pointing at the PyTorch CPU wheel repository.

On Linux or macOS the documented setup is a virtual environment plus the requirements file:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

On Windows the same steps use the Scripts activation path instead:

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt

For NVIDIA GPUs the README gives a specific replacement rather than a generic instruction. It uninstalls the CPU torch, torchvision and onnxruntime packages, installs CUDA 12.1 wheels, then installs onnxruntime-gpu==1.20.1:

pip uninstall -y torch torchvision onnxruntime onnxruntime-gpu
pip install torch==2.5.1+cu121 torchvision==0.20.1+cu121 --index-url https://download.pytorch.org/whl/cu121
pip install onnxruntime-gpu==1.20.1

Verification is two one-liners. The first should print cuda: True; the second should list CUDAExecutionProvider among the available providers:

python -c "import torch; print('torch:', torch.__version__); print('cuda:', torch.cuda.is_available()); print('gpu:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'not available')"
python -c "import onnxruntime as ort; print(ort.__version__); print(ort.get_available_providers())"

The README warns that after installing the GPU build, pip check may report that rtmlib requires onnxruntime, which is not installed. The instruction is to leave it alone as long as CUDAExecutionProvider is visible, because installing the CPU onnxruntime package can overwrite the GPU one. To go back to CPU, it gives pip install --force-reinstall -r requirements.txt.

The first real run is a single command. Without a template path the program opens a file chooser for a court template image, typically a frame where the view is stable and the lines are clear:

python main.py --video-path videos/demo.mp4

After the court step, expect outputs/<video filename>/detect_<video filename>.mp4, detections.jsonl, and a position_visualizations/ directory. The README's reference log line for a 720p clip with yolo11n-pose.pt and weights/yolo11s-ball.pt reads pose 0.02s, shuttlecock 0.02s, shuttle draw 0.00s, players draw 0.01s, court draw 0.00s. Adding --performance-stats prints a summary roughly every five seconds so you can see whether pose inference, shuttlecock detection or drawing is the bottleneck. Pose family is selectable: rtmpose with lightweight, balanced or performance modes, the single-stage rtmo, or yolo-pose with a named Ultralytics checkpoint.

The Gradio WebUI, and when the CLI is the better choice

The WebUI arrived on 2026-06-24, credited in the changelog to a pull request from KangweiLIAO. It is an optional layer: requirements-webui.txt installs Gradio on top of the base environment, and python -m webui.app starts it, with the terminal printing an address that defaults to http://127.0.0.1:7860.

The browser flow is upload the match video and a court template, click the court detection button, correct the corners by clicking four points if the automatic result is wrong, adjust parameters such as pose model, language and visualization options, then run the analysis and wait for the progress bar. Outputs are the annotated video, the heatmaps and scatter plots, and the detection data.

The CLI remains the more controllable interface. Parameter names such as --pose-family, --pose-mode, --yolo-pose-model, --ball-model, --language and --performance-stats are documented as command-line flags, and the README notes that the WebUI does not affect the CLI path. If you are scripting repeated runs over a folder of clips, the CLI is the surface you can wrap; the WebUI is a single-session tool. The README also lists a batch video analysis workflow as an unchecked item on the development plan, so batching is not something the project provides today.

Where Good-Badminton will disappoint you

The development plan is the most honest document in the repository. Hit-point recognition, a more accurate shuttlecock detection model, and fuller stroke-type statistics are all unchecked. The changelog calls hit-point analysis and technical stroke statistics experimental and says they are still iterating, suited to research and secondary development. Treat any stroke-level number as provisional.

Performance is the second constraint. The README recommends a GPU with 6GB or more of VRAM, 16GB or more of system memory, and SSD storage for writing output video, detections.jsonl and visualization images. It states that CPU can run the full pipeline but that pose and shuttlecock detection become noticeably slower, making CPU suitable mainly for short clips or functional checks. The reference timings the README quotes are for GPU inference on 720p video and depend on the graphics card, resolution, pose model, whether a window is shown, and whether audio is kept.

The third constraint is viewpoint. Because the court mapping is derived from one annotation per output directory, this is a fixed-camera tool. Handheld footage, cuts between cameras, or a zoomed broadcast feed will fight the design. The shuttlecock detection runs on the full frame, and the README describes trajectory display filtering as basic padding around the court's horizontal extent, so a shuttlecock detected far outside the court is filtered by a heuristic rather than by a model that understands the scene.

Finally, the repository README does not document rollback or a downgrade path for the GPU environment beyond reinstalling the CPU requirements. If a CUDA wheel mismatch breaks your environment, the documented recovery is the CPU reinstall line, not a version matrix.

How it differs from Good-Tennis and Good-Pickleball

The closest alternatives are the author's own sibling projects, and the difference is not the architecture but the domain model. All three follow the same sequence: player detection, ball or shuttlecock tracking, court coordinate mapping, trajectory statistics, and visualization output. What changes is the court model, the ball detection target, and the sport's rules.

That means the choice between them is a choice about your footage, not about pipeline quality. A badminton court has different line geometry from a tennis court, and the rally structure differs, so the template matching and the coordinate mapping are not interchangeable. If you have tennis footage, Good-Badminton's court model is the wrong one, and the README points you at Good-Tennis instead. The practical consequence for anyone evaluating the code: a fix or a model improvement in one of the three may not transfer, because the court assumptions differ even where the module names look similar.

Outside that family, the realistic alternative is building the pipeline yourself on top of the same public components the project already uses: Ultralytics for detection, rtmlib for RTMPose and RTMO, OpenCV for drawing and coordinate work. The project's value is the assembled court mapping, annotation caching, rally logic, statistics and output format, not any single model. If you only need person detection on sports footage, going straight to Ultralytics is less code to maintain.

Editorial conclusion

Adopt it if you have a fixed-camera badminton video, a GPU with roughly 6GB or more of memory, and the willingness to re-annotate the four court corners whenever the camera angle changes. Skip it if you need reliable hit-point or stroke-type statistics today: the README lists those as unfinished work, and the shuttlecock detection model is described as still needing improvement. Before committing, download the YOLO weights from the GitHub Releases page, run the CLI once on a short 720p clip, and check that outputs/<video name>/court_annotations.txt is produced and reused on the second run.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. yo-WASSUP/Good-Badminton on GitHub