ailia Tracker

A library for tracking the movement of objects based on object detection results.

Getting Started

Choose your platform and track objects across video frames with YOLOX-S detection plus ByteTrack association.

1

Install

Install the ailia Tracker Python package together with the ailia SDK used for detection and the opencv-python helper used by the sample.

pip3 install ailia ailia_tracker opencv-python

Haven't installed Python or git yet? Start with Setting up your Python environment (Windows / Mac / Linux).

View on PyPI
2

Run a Sample

Download example_tracker.py from ailia-models and run it. It detects objects with YOLOX-S, associates them with ByteTrack, and overlays bounding boxes with stable IDs. Models are downloaded automatically. The webcam is used by default; pass -v video.mp4 to use a video file instead.

wget https://raw.githubusercontent.com/ailia-ai/ailia-models/master/object_tracking/bytetrack/example_tracker.py
python3 example_tracker.py

On Windows, use python instead of python3.

example_tracker.py

System Requirements

ailia Tracker runs on desktop and mobile platforms. GPU acceleration is available for the object-detection phase on Windows and Linux.

Operating Systems

  • Windows 10 / 11
  • macOS 11 or later
  • Linux (Ubuntu 20.04+)
  • iOS 13+ / Android 7+

Languages & Compilers

  • Python 3.8+, Dart / Flutter 3.3+
  • C++17 (VS 2019+ / Xcode 14.2+ / clang) + CMake
  • C# / Unity 2021.3.10f1+
  • Kotlin / Java (JNI)

Bundled Models

  • YOLOX-S (object detection)
  • ByteTrack (object tracking)
  • 80 COCO categories

Input / Output

  • Video file or webcam input
  • MP4 output (annotated)
  • Tracking ID, category, confidence
  • Bounding box (x / y / w / h)

Features

Object tracking capabilities provided across the Python, C, C#, Flutter, and JNI APIs.

Detection & Association

  • YOLOX-S detector (80 COCO classes)
  • ByteTrack ID-association algorithm
  • Per-frame inference with GPU acceleration

Tracking Output

  • Stable tracking ID across frames
  • Object category
  • Detection probability
  • Normalized bounding box (0-1 range)

Filtering

  • Restrict to a target category (e.g. category 0 for humans)
  • Filter by confidence in your application code

GPU Acceleration

  • cuDNN + CUDA on Windows / Linux (detection phase)
  • Metal on macOS / iOS
  • CPU fallback when no GPU is present

Use the API in Your Project

Minimal examples for adding ByteTrack association on top of your detector in your own application.

import ailia_tracker

tracker = ailia_tracker.AiliaTracker()  # ByteTrack with default settings

# Per frame: feed detector outputs, compute, read tracked objects
for obj in detections:  # ailia.Detector results
    tracker.add_target(obj["category"], obj["prob"],
                       obj["box"]["x"], obj["box"]["y"],
                       obj["box"]["w"], obj["box"]["h"])
tracker.compute()

for obj in tracker.get_objects():
    print(f"ID {obj.id}  bbox {obj.x:.2f} {obj.y:.2f} {obj.w:.2f} {obj.h:.2f}")

tracker.release()

API Reference by Platform

Python

C++

Unity

Flutter

JNI

FAQ

Common questions about ailia Tracker.

What models does ailia Tracker use under the hood?

YOLOX-S handles per-frame object detection across the 80 COCO categories, and ByteTrack associates detections into stable tracking IDs across frames.

Where do I download the model files?

YOLOX-S weights and prototxt:

yolox_s.opt.onnx
yolox_s.opt.onnx.prototxt

Place both files in the same folder as the sample binary.

How do I track only one category, e.g. people?

Each AILIATrackerObject has a category attribute (integer matching the COCO label). Filter results in your code — e.g. keep only category == 0 to track humans, or build a small lookup map for the labels you care about.

What output information does the tracker produce?

For each tracked object: id (stable across frames), category, detection prob, and a normalized bounding box (x, y, w, h) where 0 maps to the left/top edge and 1 maps to the right/bottom edge.

How do I tune the tracker parameters (score_threshold / track_threshold / track_buffer, etc.)?

Detection score threshold, tracking buffer length, IoU match threshold and the rest are configured via the AILIATrackerSettings struct. For the meaning of each field, recommended values, and a brief overview of ByteTrack's behavior, see the ailia Tracker Parameters section of the API docs.

Does it work with a webcam?

Yes. The Python sample uses the webcam by default (pass -v <index> to select a camera). Pass -w <index> to the C++ sample to use a webcam stream instead of a file. The Unity binding exposes the same camera-input mode through its ailia-tracker-unity package.

How do I enable GPU acceleration?

On macOS / iOS, Metal is used automatically. On Windows / Linux, install CUDA Toolkit and cuDNN. See the CUDA Toolkit / cuDNN Installation Guide for detailed instructions. Acceleration applies to the object-detection phase; ByteTrack association runs on CPU.

How does licensing work?

The C++ binding requires ailia.lic from the evaluation package, placed next to the runtime libraries:

Windows: same folder as ailia.dll.
macOS: ~/Library/SHALO/
Linux: ~/.shalo/

Unity and JNI bindings auto-download the evaluation license on first run. For commercial deployment, request a production license. See the ailia license terms.

Materials

Related Articles

Model deep dives, release notes, and tutorials from the ailia tech blog.

ByteTrack: Tracking with low-confidence boxes
tech.ailia.ai
YOLOX: Object detection beyond YOLOv5
tech.ailia.ai