Early Development — Use With Caution winnow is functional but still maturing. Features that modify your Frigate training data — quality replacement, stale mapping cleanup — can remove images from your dataset and are not yet battle-tested at scale. Review the logs after each run and keep backups of your Frigate face training directory until you are confident in the results.

Docs: Setup · Troubleshooting · FAQ

winnow pulls photos from your Immich library, selects the most diverse and highest-quality subset using AI embeddings, and delivers them as training data for Frigate's face recognition and object classification models.

The best Frigate training data is images you curate manually — photos taken specifically for recognition, in controlled conditions, uploaded directly through Frigate's UI. For people you can do that for, do it. winnow is for everyone else: people in your library you want Frigate to recognise but don't have dedicated training photos for. It mines your existing Immich library for the most diverse spread of real-world appearances and fills the gap.

winnow only touches files it uploaded. Faces added to Frigate manually through its UI are never deleted, replaced, or modified — not by quality replacement, not by RESET_PERSON, not by stale cleanup. Your manually curated images are always the primary dataset; winnow only adds to it.

How It Works

Immich library
      │
      ▼
1. Fetch all assets tagged with this person
      │
      ▼
2. Filter by recency (YEARS_FILTER) and skip already-uploaded
   and rejected assets (persistent tracker in CACHE_DIR)
      │
      ▼
3. Quality filter — download preview thumbnails and reject:
   • Blurry images (Laplacian variance)
   • Grayscale / infrared (channel similarity)
   • Over- or underexposed
   • Low detection confidence
   • Face crops below minimum pixel size
      │
      ▼
4. Compute embeddings from the same preview thumbnails
   • InsightFace (ArcFace / Buffalo_L) → 512-dim vector
      │
      ▼
5. Near-duplicate removal — greedy cosine-distance pass drops burst shots
   and near-identical photos before clustering runs; the highest-quality
   image from each near-duplicate group is kept
      │
      ▼
6. Diversity selection
   • K-Medoids clustering → one representative per natural group
   • Farthest Point Sampling → fill remaining slots with maximally spread picks
   • Hard example weighting — low-confidence detections get a distance boost
     so unusual angles and harder looks are preferred over easy frontals
   • Adaptive mode: stops when the next candidate is too similar to those already
     selected (distance threshold = 20 % of median pairwise distance for
     faces, 10 % for objects)
      │
      ▼
7. Download full-resolution originals from Immich
      │
      ▼
8. Crop and process — EXIF-corrected, landmark-aligned 112×112 crop (ArcFace format)
      │
      ▼
9. Deliver — upload crops to Frigate's face registration API
   ↳ below MAX_AUTO_IMAGES — upload, unless the novelty gate
     (FRIGATE_SCORE_CEILING) determines the candidate is already
     covered by the current training set
   ↳ at cap + QUALITY_REPLACEMENT=true — with Frigate scoring active,
     swap the most redundant tracked image (highest pre-upload recognize
     score) if the candidate is more novel (lower score); falling back to
     blur-score comparison when no Frigate scores are available; manually
     added files are never touched
   ↳ at cap + QUALITY_REPLACEMENT=false — skip this person

Uploaded and rejected asset IDs are persisted across runs. The same image is never processed twice; rejected assets are permanently skipped unless RETRY_REJECTED=true.

Running in Docker

Image Tags

Tag	Arch	Acceleration
`:latest`	amd64 + arm64	NVIDIA CUDA 12.8 (amd64) · requires NVIDIA Container Toolkit
`:rocm`	amd64	AMD ROCm · pass `/dev/kfd` + `/dev/dri`
`:intel`	amd64	Intel Arc / iGPU via OpenVINO · pass `/dev/dri`, set `OPENVINO_DEVICE=GPU`
`:cpu`	amd64 + arm64	CPU only · ~2 GB smaller · no GPU required

Quick Start

NVIDIA:

services:
  winnow:
    image: ghcr.io/sudolulo/winnow:latest
    environment:
      - IMMICH_URL=http://192.168.1.10:2283
      - API_KEY=your-immich-api-key
      - FRIGATE_URL=http://192.168.1.10:5000
      - CRON_SCHEDULE=0 3 * * 0
    volumes:
      - /path/to/models:/models    # INSIGHTFACE_HOME — persists Buffalo_L model (~300 MB)
      - /path/to/cache:/app/.if_cache
      - /path/to/output:/app/frigate_train
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

AMD (:rocm): use image: ghcr.io/sudolulo/winnow:rocm and replace the deploy: block with:

    devices:
      - /dev/kfd
      - /dev/dri
    group_add:
      - video
      - render

Intel (:intel): use image: ghcr.io/sudolulo/winnow:intel and replace the deploy: block with:

    devices:
      - /dev/dri
    group_add:
      - render
    environment:
      - OPENVINO_DEVICE=GPU   # omit to run OpenVINO inference on CPU (default)

CPU (:cpu): use image: ghcr.io/sudolulo/winnow:cpu, remove the deploy: block, and add mem_limit: 2g to prevent OOM on large libraries.

See compose.yml for the full annotated example with all options.

Scheduling

CRON_SCHEDULE controls container lifetime:

`CRON_SCHEDULE` value	Behaviour
(unset)	Run once on startup, then exit
(empty string)	Stay alive, run nothing — trigger manually with `docker exec -it winnow winnow`
Cron expression	Run on startup, then repeat on schedule

In scheduled mode the process (and loaded models) stays resident between runs. The first run after a fresh install downloads InsightFace Buffalo_L (~300 MB); subsequent runs use the cached model from the mounted volume.

Environment Variables

Connection

Variable	Default	Description
`IMMICH_URL`	(required)	Full URL to your Immich instance
`API_KEY`	(required)	Immich API key
`FRIGATE_URL`	(unset)	Frigate URL — required for face upload; omit to skip

Mode & Strategy

Variable	Default	Description
`STRATEGY`	`adaptive`	`adaptive` — embedding-based diversity selection, stops when candidates become redundant; `standard` — fixed 30 images; `broad` — fixed 100 images
`LIMIT`	(unset)	Exact image count — overrides `STRATEGY`
`AUTO_MODE`	(auto)	Skip interactive prompts and process all people unattended — auto-detected when no TTY is present (Docker, cron); set `true` to force in a terminal
`VERBOSE`	`false`	Enable DEBUG-level console output (log file is always DEBUG)

People Filtering

Variable	Default	Description
`ONLY_PEOPLE`	(unset)	Comma-separated whitelist — process only these people
`SKIP_PEOPLE`	(unset)	Comma-separated list — skip these people
`MIN_FACE_COUNT`	`3`	Skip people with fewer than N tagged assets in Immich
`MERGE_DUPLICATE_PEOPLE`	`false`	When Immich has duplicate entries for the same person (same face split across multiple names), merge their asset pools before processing. Without this, each duplicate group emits a warning and is skipped
`YEARS_FILTER`	`10`	Ignore images older than N years

Image Quality

Variable	Default	Description
`MAX_AUTO_IMAGES`	`20`	Maximum training images per person in Frigate
`QUALITY_REPLACEMENT`	`true`	When at cap, swap a weaker tracked image for a better candidate. With Frigate scoring active, targets the most redundant image (highest pre-upload recognize score); otherwise uses blur score. Never touches manually added Frigate files. Set `false` to skip people at cap

Advanced Tuning (calibrated — do not adjust)

These defaults are tuned for Frigate's ArcFace requirements. winnow will warn on launch if any are set. Image quality issues caused by non-default values will not be investigated.

Variable	Default	Description
`ENABLE_FRIGATE_SCORES`	`true`	Call Frigate's recognize endpoint pre-upload to store diversity scores used for quality replacement. Adds ~200 ms per upload. Disabling also disables the below-cap novelty gate
`FRIGATE_SCORE_CEILING`	(unset)	Below-cap novelty gate. Unset: dynamic — skips candidates whose Frigate score exceeds the most-redundant tracked file's score, auto-calibrates each run. `0`: disable entirely. Positive value (e.g. `0.85`): fixed hard ceiling
`MIN_FACE_WIDTH`	`90`	Minimum face crop width in pixels
`FACE_MARGIN`	`0.15`	Padding around bounding box crop (fraction of face size)
`ENABLE_FACE_ALIGNMENT`	`true`	Align to ArcFace 112×112 format using facial landmarks
`USE_FULL_RESOLUTION`	`true`	Download full-resolution originals rather than preview thumbnails
`MIN_CONFIDENCE`	`0.7`	Minimum Immich face detection confidence
`BLUR_THRESHOLD`	`120.0`	Laplacian variance threshold — lower accepts more blur

GPU & Models

Variable	Default	Description
`FORCE_CPU`	`false`	Disable GPU — fall back to CPU for all inference
`OPENVINO_DEVICE`	`CPU`	Intel variant only: set `GPU` to use Arc or iGPU; default runs on CPU
`ENABLE_CACHE`	`true`	Cache computed embeddings to disk (speeds up re-runs on the same library)
`CACHE_DIR`	`.if_cache`	Path for embedding cache and upload tracker files
`INSIGHTFACE_HOME`	(system)	InsightFace model cache path (Buffalo_L)

Output

Variable	Default	Description
`OUTPUT_DIR`	`./frigate_train`	Directory for object-mode crops and the `winnow.log` file. In Docker, set this via the volume mount instead.

Tracker Overrides (one-shot — remove after use)

Variable	Default	Description
`DRY_RUN`	`false`	Preview selection without downloading or uploading
`RETRY_REJECTED`	`false`	Re-attempt all previously rejected assets (low-confidence skips, Frigate rejections, and other permanent exclusions)
`RESET_PERSON`	(unset)	Set to a person's name to clear their upload history and delete their winnow-managed Frigate training files so the next run starts fresh. Set to `*` to reset all tracked people at once. Manually added Frigate files are never touched
`TRACE_CROP_SIZE`	(unset)	Debug: print all tracked crops whose width or height matches this pixel value, then exit

Scheduling

Variable	Default	Description
`CRON_SCHEDULE`	(unset)	Unset = run once and exit; empty = stay alive; cron expression = scheduled

Local Install

git clone https://github.com/sudolulo/winnow.git
cd winnow
uv sync
uv run winnow

Requires Python 3.13+ and uv. An NVIDIA, AMD, or Intel GPU is recommended — CPU mode works but embedding computation is slower.

When run with a terminal attached, winnow starts an interactive session: select which people to process and choose a strategy (adaptive, standard, broad, or a custom count) per person. Without a TTY — Docker, cron, or AUTO_MODE=true — it processes all people unattended using the configured defaults.

Requirements

Immich v1.106+
Frigate v0.16+ (face mode only — object mode has no Frigate dependency)
GPU recommended: NVIDIA (CUDA), AMD (ROCm), or Intel (Arc / iGPU via OpenVINO)
Python 3.13+

Getting Help

GitHub Discussions — questions, setup help, and general discussion
Wiki — setup guide, troubleshooting, and FAQ
Issues — bugs and feature requests only

Attribution

Based on if_curator by Sebastian, licensed MIT.

README.md Unescape Escape

winnow

How It Works

Running in Docker

Image Tags

Quick Start

Scheduling

Environment Variables

Connection

Mode & Strategy

People Filtering

Image Quality

Advanced Tuning (calibrated — do not adjust)

GPU & Models

Output

Tracker Overrides (one-shot — remove after use)

Scheduling

Local Install

Requirements

Getting Help

Attribution

README.md