Apple Photos Cleaner

# Apple Photos Cleaner

Comprehensive toolkit for analyzing and cleaning up Apple Photos libraries. Goes beyond what Photos.app offers: intelligent junk detection, detailed storage analysis, duplicate finding with quality scoring, timeline recaps for storytelling, and smart export planning.

## Overview

Apple Photos is great at organizing and syncing photos, but it's not so great at cleanup. This skill fills that gap:

- **Library Analysis** — Get the big picture: counts, storage, date ranges, people, quality distribution
- **Junk Finder** — Identify screenshots, low-quality photos, burst leftovers, old screenshots
- **Duplicate Finder** — Find duplicates using Apple's detection + timestamp/dimension matching
- **Storage Analyzer** — Detailed breakdown by year, type, file format, growth trends, storage hogs
- **Timeline Recap** — Generate narrative summaries of photo activity for any date range
- **Smart Export** — Plan organized exports by year/month, person, album, or location; AppleScript export
- **Best Photos / Hidden Gems** — Surface high-quality photos you haven't favorited
- **People Analyzer** — Deep analysis of people: co-occurrence, trends over time, best photos per person
- **Location Mapper** — Cluster GPS coordinates into locations, identify trips, offline reverse geocoding
- **Scene Search** — Search by ML-detected content (beach, dog, food) or generate content inventory
- **Photo Habits** — Behavioral analytics: time-of-day, day-of-week, streaks, seasonal trends
- **On This Day** — See what you photographed on today's date in prior years
- **Album Auditor** — Find orphan photos, empty albums, overlap between albums
- **Cleanup Executor** — Batch move junk to trash via AppleScript with confirmation
- **Live Photo Analyzer** — Compare Live Photos vs stills, find conversion candidates, storage impact
- **Shared Library** — Analyze Shared Library vs personal: contributors, content splits, storage
- **iCloud Status** — Check iCloud sync coverage: synced...

# Apple Photos Cleaner

Analyze, audit, and clean up your Apple Photos library by querying its SQLite database directly.

Goes beyond what Photos.app offers: intelligent junk detection, detailed storage analysis, duplicate finding with quality scoring, timeline recaps, people analytics, location mapping, and more.

> **Safety:** All operations are read-only database queries. No photos are modified or deleted without explicit user action through the cleanup executor.

## Requirements

- **macOS** (accesses the Photos SQLite database)
- **Python 3.9+** (uses stdlib only — no external runtime dependencies)

## Setup

```bash
# Clone the repo
git clone https://github.com/and3rn3t/apple-photos-cleaner.git
cd apple-photos-cleaner

# Install dev/test dependencies
make install
```

## Commands

Every script lives in `scripts/` and outputs **JSON** by default (for piping / AI consumption). Add `--human` for readable terminal output.

| Script | Purpose |
|---|---|
| `library_analysis.py` | Big-picture stats: counts, storage, date ranges, quality distribution |
| `junk_finder.py` | Identify screenshots, low-quality photos, burst leftovers |
| `duplicate_finder.py` | Find duplicates via Apple's detection + timestamp/dimension matching |
| `storage_analyzer.py` | Breakdown by year, type, format; growth trends; storage hogs |
| `timeline_recap.py` | Narrative summaries of photo activity for any date range |
| `smart_export.py` | Plan organized exports by year/month, person, album, or location |
| `best_photos.py` | Surface high-quality photos you haven't favorited |
| `people_analyzer.py` | People co-occurrence, trends over time, best photos per person |
| `location_mapper.py` | Cluster GPS coordinates into locations, identify trips |
| `scene_search.py` | Search by ML-detected content (beach, dog, food) or browse inventory |
| `photo_habits.py` | Time-of-day, day-of-week, streaks, seasonal trends |
| `on_this_day.py` | Photos from today's date in prior years |
| `album_auditor....