birdpreen 0.1.0

Scan macOS Photos library, detect and identify birds, write species captions

preen

Groom your photo library — automatically find and name every bird.

Preen scans your macOS Photos library, detects birds with YOLO, identifies species with SuperPicky's OSEA classifier (10,964 species), and writes "中文名 (English Name)" as captions — visible on iPhone.

Features

• Scans entire Photos library including iCloud photos
• YOLO multi-bird detection — finds all birds in a photo
• OSEA species identification with GPS-based eBird regional filtering
• Writes captions via persistent Photos.app connection (photoscript)
• SQLite checkpoint — pause/resume, incremental or full rescan
• Deduplicates species in multi-bird captions

Requirements

• macOS with Photos.app
• Python 3.11+

Installation

git clone https://github.com/bohemianpan/preen.git
cd preen
python3 -m venv venv
source venv/bin/activate
pip install -e .

On first scan, model files (~260 MB) are automatically downloaded from HuggingFace.

Usage

# Scan new photos (incremental)
preen scan

# Full library rescan
preen scan --full

# Dry run — detect and identify without writing
preen scan --dry-run

# Custom confidence threshold (default: 70%)
preen scan --threshold 65

# Process in batches
preen scan --batch-size 500

# Check progress
preen status

# Reset checkpoint to start over
preen reset

Credits

• OSEA bird classification model (10,964 species) by Sun Jiao
• Bird identification logic (OSEA classifier, AVONET geographic filtering, eBird species data) extracted from SuperPicky
• YOLO11 segmentation model by Ultralytics
• Photos library access via osxphotos
• Photos.app integration via photoscript