ailia Tracker

Getting Started

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

Clone Samples

Clone the C++ sample repository and initialize submodules. The ailia-tracker-cpp binding is included as a submodule.

git clone https://github.com/ailia-ai/ailia-models-cpp.git
cd ailia-models-cpp
git submodule init
git submodule update

On macOS only, clear the quarantine attribute on the bundled dylibs:

./xattr.sh

Sample Repository bytetrack sample

Build & Run

Fetch the one-month evaluation license, install CMake and OpenCV, build, and run the ByteTrack sample. bytetrack.sh downloads the YOLOX-S detector ONNX on first run, then processes the video.

# Fetch a one-month evaluation license
cd ailia
python3 download_license.py
cd ..

# macOS
brew install cmake opencv
# Linux: apt install cmake libopencv-dev
# Windows: install CMake and Visual Studio,
#   then set OpenCV_DIR to your OpenCV build path

cmake .
cmake --build .
cd object_tracking/bytetrack
./bytetrack.sh    # use bytetrack.bat on Windows

Full C++ Setup Guide

Install via UPM

Open Window > Package Manager in Unity (2021.3.10f1+), click + > Add package from git URL, and enter the binding URL below.

https://github.com/ailia-ai/ailia-tracker-unity.git

Unity API Reference

Run a Sample

Clone ailia-models-unity, open it in the Unity Editor (2021.3.10f1+), and play ObjectTracking/ObjectTrackingSample.unity with a video clip or webcam input. Bounding boxes with stable IDs are overlaid in the Game view.

git clone https://github.com/ailia-ai/ailia-models-unity.git

Sample Scene

Clone Binding

Clone the JNI binding repository and add it to your Android Studio project.

git clone https://github.com/ailia-ai/ailia-tracker-jni.git

Binding

Run a Sample

Clone ailia-models-kotlin with submodules and open it in Android Studio. Run the tracker sample on a connected device — it pairs YOLOX-S detection with ByteTrack association on each video frame.

git clone https://github.com/ailia-ai/ailia-models-kotlin.git
cd ailia-models-kotlin
git submodule update --init --recursive

AiliaTrackerSample.kt

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

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)

Use the API in Your Project

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

#include "ailia_tracker.h"
#include "ailia_detector.h"

struct AILIATracker *tracker = nullptr;
AILIATrackerSettings settings = {0.1f, 0.7f, 0.5f, 30, 0.8f};
ailiaTrackerCreate(&tracker, AILIA_TRACKER_ALGORITHM_BYTE_TRACK, &settings,
                   AILIA_TRACKER_SETTINGS_VERSION, AILIA_TRACKER_FLAG_NONE);

// Per frame: feed detector outputs, compute, read tracked objects
for (auto &d : detectorObjects) {  // d is AILIADetectorObject
    ailiaTrackerAddTarget(tracker, &d, AILIA_DETECTOR_OBJECT_VERSION);
}
ailiaTrackerCompute(tracker);

unsigned int n;
ailiaTrackerGetObjectCount(tracker, &n);
for (unsigned int i = 0; i < n; i++) {
    AILIATrackerObject obj;
    ailiaTrackerGetObject(tracker, &obj, i, AILIA_TRACKER_OBJECT_VERSION);
    printf("ID %u  bbox %.2f %.2f %.2f %.2f\n", obj.id, obj.x, obj.y, obj.w, obj.h);
}

ailiaTrackerDestroy(tracker);

using ailiaTracker;
using ailiaDetector;

var tracker = new AiliaTrackerModel();
var settings = new AiliaTracker.AILIATrackerSettings();
settings.score_threshold = 0.1f;
settings.nms_threshold = 0.7f;
settings.track_threshold = 0.5f;
settings.track_buffer = 30;
settings.match_threshold = 0.8f;
tracker.Create(AiliaTracker.AILIA_TRACKER_ALGORITHM_BYTE_TRACK, settings);

// Per frame: feed the detector output list, get back tracked objects
List<AiliaTracker.AILIATrackerObject> tracked = tracker.Compute(detectorObjects);
foreach (var obj in tracked) {
    Debug.Log($"ID {obj.id}  bbox {obj.x} {obj.y} {obj.w} {obj.h}");
}

tracker.Close();

val settings = AiliaTrackerSettings(
    score_threshold = 0.1f, nms_threshold = 0.7f,
    track_threshold = 0.5f, track_buffer = 30,
    match_threshold = 0.8f,
)
val tracker = AiliaTracker(
    algorithm = AiliaTracker.AILIA_TRACKER_ALGORITHM_BYTE_TRACK,
    settings = settings,
)

// Per frame: feed each detector output, compute, then read tracked objects
for (d in detections) {
    tracker.addTarget(
        category = d.category, prob = d.confidence,
        x = d.x, y = d.y, w = d.width, h = d.height,
    )
}
tracker.compute()

for (i in 0 until tracker.getObjectCount()) {
    val o = tracker.getObject(i) ?: continue
    Log.d("ailia", "ID ${o.id}  bbox ${o.x} ${o.y} ${o.w} ${o.h}")
}

tracker.close()

API Reference by Platform

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. 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.

Getting Started

Clone Samples

Build & Run

Install via UPM

Run a Sample

Clone Binding

Run a Sample

System Requirements

Operating Systems

Languages & Compilers

Bundled Models

Input / Output

Features

Detection & Association

Tracking Output

Filtering

GPU Acceleration

Use the API in Your Project

API Reference by Platform

C++

Unity

JNI

FAQ

Materials

Related Articles