-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
No — with one exception. winnow only reads from Immich (assets, people, face bounding boxes). It never writes back to Immich or deletes anything, unless you set MERGE_DUPLICATE_PEOPLE=true, which permanently merges duplicate person records inside Immich. That setting is false by default.
The adaptive strategy (default) decides this for you — it keeps selecting until adding more images would be redundant. In practice this is usually 10–40 per person. You can cap it with MAX_AUTO_IMAGES (default 20).
The default is intentionally conservative. The goal is for winnow to supplement a training set that should be primarily built from manually-curated images — photos you took specifically for recognition, in controlled conditions, uploaded directly through Frigate's UI. winnow is for the people you can't do that for: faces in your library you want Frigate to recognise but don't have dedicated training photos for.
When winnow reaches the cap on subsequent runs, QUALITY_REPLACEMENT=true (default) lets it improve the training set rather than stalling:
- With Frigate scores (default, after the first run): targets the most redundant existing file — the one Frigate already recognizes most confidently — and replaces it only if the new candidate is more novel (scores lower). This keeps the set maximally diverse.
-
Without Frigate scores (first run, or
ENABLE_FRIGATE_SCORES=false): falls back to blur scores — replaces the blurriest existing file if the candidate is sharper.
Only files winnow uploaded are ever replaced. Anything added manually through Frigate's UI is never touched.
Quality and diversity matter far more than volume. 30 well-spread images outperform 200 from the same week.
You can use DRY_RUN=true to preview selection without uploading. But winnow's purpose is uploading to Frigate — without FRIGATE_URL set, it will select images and skip the upload step.
winnow computes a 512-dim ArcFace embedding for each candidate image (what the face actually looks like — angle, lighting, expression). It then clusters those embeddings with K-Medoids and picks representatives that are maximally spread across the embedding space using Farthest Point Sampling. It stops when the next-most-different image is already close enough to something already selected. See the README pipeline for the full breakdown.
Yes. By default it processes every named person in your Immich library. Use ONLY_PEOPLE to whitelist specific names or SKIP_PEOPLE to exclude them.
By default winnow warns about duplicates (same name on multiple person records), keeps only the one with the most assets, and skips the rest. This is safe but means winnow only sees part of that person's photo pool.
Set MERGE_DUPLICATE_PEOPLE=true to permanently merge duplicate groups inside Immich before processing — the person with the most assets absorbs the others. This modifies Immich and cannot be undone. Only enable it after you've verified the duplicates are actually the same person.
Any NVIDIA GPU with CUDA 12.x support works with :latest. AMD ROCm GPUs work with :rocm. Intel Arc and integrated GPUs work with :intel. InsightFace Buffalo_L fits comfortably in 2 GB VRAM.
CPU mode works but is significantly slower — about 8–10× vs GPU for InsightFace (see Benchmarks). For large libraries or frequent scheduled runs, a GPU makes a noticeable difference.
CPU memory: Set a container memory limit of at least 2 GB (mem_limit: 2g). The model uses roughly 600 MB–1 GB and thumbnails are processed in bounded batches of 32, so usage stays flat regardless of library size.
ARM builds (linux/arm64) are CPU-only — GPU variants are amd64 only.
Yes — the compose.yml uses standard Docker volume mounts. Replace the example paths with whatever absolute paths suit your setup.
docker compose pull
docker compose up -dThe latest, cpu, rocm, and intel tags on GHCR always point to the latest release. Versioned tags (e.g. ghcr.io/sudolulo/winnow:v0.5.0) are also published for each release and are useful for pinning to a known-good version.