khoroos 0.1.0

Khoroos turns poultry videos into bird tracks, behavior timelines, and descriptive statistics. Use it to measure how observed birds spend their time, compare activity across a recording, and export data for further analysis.

Developed at the UT Smart Agriculture Lab.

Features

• Detection and tracking: locate chickens and follow their trajectories across frames.
• Behavior recognition: classify single-bird clips into 15 behaviors, or select a subset such as feeding and drinking.
• Descriptive statistics: time budgets, behavior bouts, detection counts, spatial summaries, and per-track measurements.
• Interactive review: inspect tracks and behavior timelines alongside the video in a browser.
• Exports: save JSON, CSV tables, and an optional annotated video.
• Replaceable components: bring your own detector, classifier, tracker, or statistics functions. Convert bounding-box annotations between YOLO and COCO formats.

Get started

Requires Python 3.12+ and FFmpeg. A GPU is recommended for inference.

git clone https://github.com/amirivojdan/khoroos.git
cd khoroos
python3 -m venv .venv
source .venv/bin/activate
python -m pip install ".[web]"
khoroos models download
khoroos ui

The default models are public; no Hugging Face login is required. Downloads are cached for later runs, including offline use.

Open http://127.0.0.1:8000, select a video, choose a detail level, and start the analysis. Use the timeline to seek through the recording, select a track to follow one bird, and download the results when the run finishes.

Docker

With Docker and the NVIDIA Container Toolkit installed:

docker compose up --build

Open http://localhost:8000. Startup downloads the models automatically and reuses them on later starts. Model files and results persist in a volume; the web job list resets on restart. See the Docker guide for requirements and storage details.

Command line

Start with a short section of video:

khoroos analyze farm.mp4 -o results/ --max-seconds 60

Analyze a full recording and save an annotated video:

khoroos analyze farm.mp4 -o results/ --overlay

Report selected behaviors:

khoroos analyze farm.mp4 -o results/ --set action_classes=feeding,drinking

Choose --preset fast, balanced (default), or thorough to adjust sampling detail. If GPU memory runs out, reduce --action-batch-size first. See the CLI guide for all options.

Python

Analyze a video directly:

from khoroos import analyze_video

result = analyze_video("farm.mp4", preset="balanced")
print(result.metrics["time_budget"])

Reuse the models across recordings and save each export bundle:

from pathlib import Path
from khoroos import AnalysisRunner

runner = AnalysisRunner()
for video in Path("videos").glob("*.mp4"):
    runner.run(video, output_dir=Path("results") / video.stem)

See the Python guide for parameters and progress callbacks.

Results

Each exported analysis includes:

Statistics describe model-assigned labels. Uncertain predictions are reported separately, and track IDs represent trajectories rather than verified animal identities. See Outputs for field definitions and duration calculations.

Extend Khoroos

Subclass Detector, VideoClassifier, or Tracker to use your own algorithms. VideoAnalyzer accepts custom models, and PipelineComponents configures the reader, tracker, cropper, and metrics. Class labels and behavior groups are configurable.

Follow the extension guide for working examples, or the configuration guide for devices, model sources, and cache paths.

Development

uv sync --locked --extra web --extra dev --extra docs
uv run pytest
uv run ruff check src tests
uv run mkdocs serve

Tests use stub models and generated videos; no model download is needed.

Resources and licenses

• Documentation
• ChickenAct dataset and training notebook
• Public models: chicken detector and action classifier, licensed under CC BY-NC-SA 4.0.
• Code: PolyForm Noncommercial License 1.0.0.