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 vs local-only, large unsynced items
- Similarity Finder — Detect visually similar photos using computed quality feature vectors
- Seasonal Highlights — Curate the best photos per season using quality scores and favorites
- Face Quality Scoring — Rank face photos per person: find best/worst portraits
Safety: All operations are READ-ONLY database queries. No photos are modified or deleted without explicit user action.
When to Use This Skill
Use when users mention:
- - Cleaning up Photos / freeing up photo storage
- Finding duplicate photos
- Removing old screenshots
- Analyzing Photos library storage
- Finding junk or low-quality photos
- Organizing photo exports
- Getting photo timeline summaries ("what did I do last week?")
- Burst photo cleanup
- Finding storage hogs in Photos
- Finding best or hidden gem photos
- People in photos, who appears together
- Where photos were taken, travel, trips, locations
- Searching photos by content (beach, sunset, dog, food)
- Photo-taking habits, patterns, streaks
- "On this day" / photo memories from past years
- Album organization, orphan photos, album cleanup
- Actually deleting junk photos (batch cleanup)
- Live Photos analysis, converting Live Photos to stills
- Shared Library content, who contributed what
- iCloud sync status, unsynced photos, cloud coverage
- Finding similar-looking photos
- Seasonal photo highlights, best of each season
- Face/portrait quality, best/worst portraits per person
Quick Start
All scripts work standalone. The Photos database is automatically located at:
INLINECODE0
Basic workflow:
- 1. Run
library_analysis.py to get overview - Run
junk_finder.py to identify cleanup candidates - Run
duplicate_finder.py to find duplicates - Use results to guide manual cleanup in Photos.app
Commands
1. Library Analysis
Get comprehensive library statistics: counts, storage, date ranges, people, quality scores.
CODEBLOCK0
Options:
- -
--human — Human-readable summary instead of JSON - INLINECODE5 — Write JSON to file
- INLINECODE6 — Custom database path
- INLINECODE7 — Custom Photos library path
Example Output:
CODEBLOCK1
Usage in Conversation:
User: "How many photos do I have?"
AI: Runs library_analysis.py with --human flag, reports summary
User: "Show me my Photos storage breakdown"
AI: Runs library_analysis.py, highlights key stats
2. Junk Finder
Identify cleanup candidates: screenshots, low-quality photos, burst leftovers, duplicates.
CODEBLOCK2
Options:
- -
--screenshot-age DAYS — Consider screenshots older than N days as junk (default: 30) - INLINECODE9 — Quality score threshold for low-quality (default: 0.3, range: 0.0-1.0)
- INLINECODE10 — Skip duplicate detection
- INLINECODE11 — Human-readable summary
- INLINECODE12 — Write JSON to file
Example Output:
CODEBLOCK3
What It Finds:
- - Screenshots — Detected via
ZISDETECTEDSCREENSHOT flag - Old screenshots — Screenshots older than specified age (safe to delete)
- Low quality — Photos with low quality scores (high failure/noise, low composition/lighting)
- Burst leftovers — Unpicked photos from burst sequences
- Possible duplicates — Using Apple's built-in detection
Usage in Conversation:
User: "Find junk in my Photos"
AI: Runs junk_finder.py, reports totals and estimated savings
User: "How many old screenshots do I have?"
AI: Runs junk_finder.py, focuses on screenshot stats
User: "What can I delete to free up 5GB?"
AI: Runs junk_finder.py, shows conservative/aggressive estimates, suggests next steps
3. Duplicate Finder
Find duplicate photos and recommend which to keep based on quality, favorite status, and file size.
CODEBLOCK4
Detection Methods:
- 1. Apple's built-in — Uses INLINECODE14
- Timestamp + dimensions — Photos taken at same second with same dimensions
Recommendation Logic:
- - Favorites get priority
- Screenshots get penalty
- Highest quality score preferred
- Largest file size as tiebreaker
Example Output:
CODEBLOCK5
Usage in Conversation:
User: "Do I have duplicate photos?"
AI: Runs duplicate_finder.py, reports findings
User: "Find duplicates and tell me which to delete"
AI: Runs duplicate_finder.py, explains recommendations
4. Storage Analyzer
Detailed storage breakdown: by year, type, source, growth trends, file types, storage hogs.
CODEBLOCK6
Analyzes:
- - Total storage and breakdown by photo/video
- Storage by year and month
- Screenshots vs regular photos
- File types (JPEG, HEIC, MOV, etc.)
- Growth trends over time
- Top 20 largest files
Example Output:
CODEBLOCK7
Usage in Conversation:
User: "What's taking up space in my Photos?"
AI: Runs storage_analyzer.py, highlights biggest categories
User: "Show me my largest videos"
AI: Runs storageanalyzer.py, focuses on storagehogs section filtered by videos
User: "How much storage am I adding per month?"
AI: Runs storage_analyzer.py, reports recent growth stats
5. Timeline Recap
Generate narrative summaries of photo activity for any date range. Groups photos into events and includes context: people, locations, scenes.
CODEBLOCK8
Options:
- -
--start-date — Start date (required) - INLINECODE16 — End date (optional, defaults to today)
- INLINECODE17 — Hours between photos to consider separate events (default: 4)
- INLINECODE18 — Output narrative text instead of JSON
- INLINECODE19 — Write to file
What It Generates:
- - Day-by-day photo activity
- Event clustering (groups photos taken close together)
- People detected in each event
- Scene classifications (beach, sunset, dog, etc.)
- Location data (if available)
- Favorites count
Example Output:
CODEBLOCK9
Usage in Conversation:
User: "What did I do last week?"
AI: Runs timeline_recap.py with last week's dates, narrates the timeline in story form
User: "Show me my photo activity for February"
AI: Runs timeline_recap.py with Feb 1 - Feb 28, summarizes highlights
User: "Tell me about our vacation photos from August"
AI: Runs timeline_recap.py with August dates, creates a narrative story
AI Tip: When presenting timeline results, narrate them like a story! Don't just dump the JSON. Example:
"You had a busy Saturday on March 1st! In the morning around 9:15, you spent about 2 hours at the pool — 32 photos with Jonah and Silas, mostly swimming and sports shots. You marked 5 as favorites. Then in the evening around 6:30, you captured a family dinner with 13 photos. Looks like a great day!"
6. Smart Export
Plan organized exports by year/month, person, album, or location. Shows what will be exported without actually doing it (unless confirmed).
CODEBLOCK10
Options:
- -
--output-dir PATH — Where to export (required) - INLINECODE21 — How to organize:
year_month, person, album, location (default: year_month) - INLINECODE26 — Export only favorites
- INLINECODE27 — Filter by start date
- INLINECODE28 — Filter by end date
- INLINECODE29 — Export only photos with this person
- INLINECODE30 — Export only from this album
- INLINECODE31 — Show plan without exporting (recommended first step)
Example Output:
CODEBLOCK11
Note: Actual export via AppleScript is not fully implemented. This command generates the export plan and folder structure. For now, use this to identify what to export, then do it manually in Photos.app.
Usage in Conversation:
User: "I want to export all my 2024 photos organized by month"
AI: Runs smart_export.py with year filter and --plan-only, shows the plan
User: "Export all photos with Jonah"
AI: Runs smart_export.py with --person "Jonah" and --plan-only, shows what would be exported
7. Best Photos / Hidden Gems
Surface your highest-quality photos using Apple's computed quality scores. Find hidden gems — great photos you never favorited.
CODEBLOCK12
Options:
- -
--min-quality N — Minimum quality score threshold (default: 0.7, range: 0.0-1.0) - INLINECODE33 — Number of top photos to return (default: 50)
- INLINECODE34 — Only show photos that are NOT favorited
- INLINECODE35 — Filter to specific year
- INLINECODE36 — Human-readable summary
- INLINECODE37 — Write JSON to file
What It Shows:
- - Quality score distribution across your library (excellent/good/average/poor)
- Top N photos ranked by quality with detailed score breakdowns
- Hidden gems: high-quality photos you haven't favorited yet
- Per-photo scores for composition, lighting, symmetry, patterns, etc.
Example Output:
CODEBLOCK13
Usage in Conversation:
User: "Show me my best photos"
AI: Runs best_photos.py with --human flag, highlights top shots
User: "Find hidden gems I haven't favorited"
AI: Runs best_photos.py with --hidden-gems, suggests which to favorite
User: "What are my best photos from 2025?"
AI: Runs best_photos.py with --year 2025, shows quality distribution and top picks
8. People Analyzer
Deep analysis of people detected in your photos: who appears most, who's photographed together, trends over time, best photo of each person.
CODEBLOCK14
Options:
- -
--min-photos N — Minimum photos to include a person (default: 5) - INLINECODE39 — Number of top people to analyze in detail (default: 20)
- INLINECODE40 — Human-readable summary
- INLINECODE41 — Write JSON to file
What It Shows:
- - All named people ranked by photo count
- Per-person yearly trends (are you photographing them more or less?)
- Co-occurrence analysis (who appears together most)
- Best quality photo for each person
- Favorites count per person
- Unnamed face count
Example Output:
CODEBLOCK15
Usage in Conversation:
User: "Who's in my photos the most?"
AI: Runs people_analyzer.py, reports top people with counts
User: "Who do I photograph together?"
AI: Runs people_analyzer.py, focuses on co-occurrence analysis
9. Location / Travel Mapper
Analyze where your photos were taken. Clusters GPS coordinates into locations, identifies trips, and shows most-photographed places.
CODEBLOCK16
Options:
- -
--radius N — Cluster radius in km (default: 1.0) - INLINECODE43 — Filter to specific year
- INLINECODE44 — Minimum photos per location cluster (default: 3)
- INLINECODE45 — Human-readable summary
- INLINECODE46 — Write JSON to file
What It Shows:
- - GPS coverage percentage
- Location clusters with photo counts, date ranges, and people
- Identified trips (clusters with 5+ photos spanning 4+ hours)
- Per-location monthly breakdown
Example Output:
CODEBLOCK17
Usage in Conversation:
User: "Where have I taken the most photos?"
AI: Runs location_mapper.py, reports top locations
User: "Show me my trips from 2025"
AI: Runs location_mapper.py with --year 2025, highlights identified trips
10. Scene / Content Search
Search photos by ML-detected scene classifications (beach, sunset, dog, food, etc.) or generate a complete content inventory.
CODEBLOCK18
Options:
- -
--search TERM — Scene name to search for (omit for content inventory) - INLINECODE48 — Minimum confidence score (default: 0.0)
- INLINECODE49 — Number of search results (default: 50)
- INLINECODE50 — Filter to specific year
- INLINECODE51 — Human-readable summary
- INLINECODE52 — Write JSON to file
Modes:
- 1. Search mode (
--search beach) — Find all photos matching a scene label - Inventory mode (no --search) — Show all scene labels with counts, grouped by category
Example Output (inventory):
CODEBLOCK19
Usage in Conversation:
User: "How many beach photos do I have?"
AI: Runs scene_search.py --search beach, reports count and related scenes
User: "What kinds of photos do I take?"
AI: Runs scene_search.py (inventory mode), summarizes categories
11. Photo Habits & Insights
Behavioral analytics: when you shoot most, busiest days, seasonal patterns, streaks, photo vs video ratio trends.
CODEBLOCK20
Options:
- -
--year YYYY — Filter to specific year - INLINECODE55 — Human-readable summary
- INLINECODE56 — Write JSON to file
What It Shows:
- - Time-of-day breakdown (morning/afternoon/evening/night)
- Peak hour, peak day of week, peak month
- Day-of-week distribution with visual bars
- Longest photo streak (consecutive days with photos)
- Busiest single day
- Year-over-year trends with video ratio
- Monthly trend with photos/videos/screenshots breakdown
Example Output:
CODEBLOCK21
Usage in Conversation:
User: "What are my photo-taking patterns?"
AI: Runs photo_habits.py, narrates key insights
User: "When do I take the most photos?"
AI: Runs photo_habits.py, highlights peak times and days
12. On This Day / Memory Lane
See what you photographed on today's date in previous years. Includes people, scenes, and quality context.
CODEBLOCK22
Options:
- -
--date YYYY-MM-DD — Target date (defaults to today) - INLINECODE58 — Include photos ±N days around target (default: 0)
- INLINECODE59 — Human-readable summary
- INLINECODE60 — Write JSON to file
What It Shows:
- - Photos from each previous year on the same date
- People, scenes, and best photo for each year
- Favorites count per year
- How many years ago each set of photos was taken
Example Output:
CODEBLOCK23
Usage in Conversation:
User: "What did I do on this day in past years?"
AI: Runs onthisday.py, narrates memories year by year
User: "Show me memories from March 3"
AI: Runs onthisday.py --date 2026-03-03, tells the story
AI Tip: Narrate memories warmly! "2 years ago today, you were at the pool with Jonah and Silas — you took 12 photos and favorited 3 of them. The best shot has a quality score of 0.89!"
13. Album Auditor
Find orphan photos (not in any album), empty albums, tiny albums, and overlapping albums.
CODEBLOCK24
Options:
- -
--human — Human-readable summary - INLINECODE62 — Write JSON to file
What It Shows:
- - Orphan photos count (not in any album)
- Empty albums that can be deleted
- Tiny albums (≤3 photos) that might be incomplete
- Album overlap (shared photos between albums, with percentages)
- Album size ranking
Example Output:
CODEBLOCK25
Usage in Conversation:
User: "Are my photos well organized?"
AI: Runs album_auditor.py, reports orphans, empty albums, and overlap
User: "How many photos aren't in any album?"
AI: Runs album_auditor.py, reports orphan count and size
14. Cleanup Executor
Actually move junk photos to trash via AppleScript. Supports old screenshots, burst leftovers, low quality, and duplicates. All items go to Recently Deleted (recoverable for 30 days).
CODEBLOCK26
Options:
- -
--category — What to clean up: old_screenshots, all_screenshots, burst_leftovers, low_quality, INLINECODE68 - INLINECODE69 — Screenshot age in days for oldscreenshots (default: 30)
- INLINECODE70 — Quality threshold for lowquality (default: 0.3)
- INLINECODE71 — Maximum items to process (default: 500)
- INLINECODE72 — Actually perform the cleanup (without this, preview only)
- INLINECODE73 — Items per AppleScript batch (default: 50)
- INLINECODE74 — Human-readable summary
Safety:
- - Without
--execute, shows preview only (dry run) - With
--execute, requires typing 'yes' to confirm - Items are moved to Recently Deleted (not permanently deleted)
- 30-day recovery window in Photos.app
- Uses AppleScript through Photos.app (never touches database directly)
Example Usage:
CODEBLOCK27
Usage in Conversation:
User: "Delete my old screenshots"
AI: Runs cleanupexecutor.py --category oldscreenshots --human first to show preview, then prompts user before running with --execute
User: "Clean up burst photos"
AI: Runs cleanupexecutor.py --category burstleftovers --human, shows count and size, asks for confirmation
⚠️ AI Tip: Always show the preview first! Never run with --execute without showing the user what will be affected and getting confirmation.
15. Live Photo Analyzer
Analyze Live Photos vs still photos: identify Live Photos, compare storage impact, find Live Photos that could be converted to stills to save space.
CODEBLOCK28
Options:
- -
--year YYYY — Filter to specific year - INLINECODE78 — Human-readable summary
- INLINECODE79 — Write JSON to file
What it reports:
- - Total Live Photos vs stills (count and storage)
- Playback style breakdown (live, loop, bounce, long exposure)
- Year-over-year Live Photo trends
- Estimated savings if Live Photos were converted to stills (~50% of video component)
- Unfavorited Live Photos as conversion candidates
- Largest Live Photos (biggest savings first)
16. Shared Library Analysis
Analyze the Shared Library in Apple Photos: personal vs shared content, contributor breakdown, storage impact.
CODEBLOCK29
What it reports:
- - Whether Shared Library is enabled
- Personal vs shared asset counts and storage
- Contributor identifiers and their contributions
- Shared content by year and monthly trends
- Photo/video split for shared content
Note: Requires macOS 13+ / iOS 16+ database format for Shared Library columns.
17. iCloud Sync Status
Check iCloud sync coverage across the library: synced vs local-only, download status, large unsynced items.
CODEBLOCK30
What it reports:
- - Sync coverage percentage (synced vs local-only)
- Storage breakdown by sync state
- Photo vs video sync comparison
- Year-over-year sync trends
- Large local-only items (>10 MB) that aren't synced
- My assets vs others' assets
- Downloadable (cloud-only) item count
18. Photo Similarity Detection
Find visually similar photos beyond exact duplicates using computed quality feature vectors (composition, lighting, color, patterns, etc.).
CODEBLOCK31
Options:
- -
--threshold — Cosine similarity threshold 0-1 (default: 0.95, very similar) - INLINECODE81 — Filter to specific year
- INLINECODE82 — Max photos to compare (default: 500, controls runtime)
- INLINECODE83 — Human-readable summary
What it reports:
- - Groups of visually similar photos
- Potential storage savings per group
- Keep candidate (largest/highest quality in each group)
- Total extra (removable) similar photos
Runtime note: O(n²) comparison; use --limit to control runtime for large libraries.
19. Seasonal Highlights
Curate the best photos from each season using quality scores, favorites, and scene context.
CODEBLOCK32
Options:
- -
--year YYYY — Filter to specific year - INLINECODE86 — Top N photos per season (default: 20)
- INLINECODE87 — Use Southern Hemisphere season definitions
- INLINECODE88 — Human-readable summary
What it reports:
- - Best photos per season (spring, summer, fall, winter)
- Season-by-season quality scores and favorite counts
- Year-over-season distribution matrix
- Busiest season identification
- Best single photo per season
20. Face Quality Scoring
Score face quality per person using Apple Photos' face detection attributes: quality measure, blur, yaw angle, smile, face size, and center position.
CODEBLOCK33
Options:
- -
--person NAME — Filter to specific person name - INLINECODE90 — Top N best/worst per person (default: 10)
- INLINECODE91 — Human-readable summary
What it reports:
- - Per-person face quality rankings
- Best and worst portraits per person
- Composite face score (quality, blur, size, yaw, smile, center)
- Overall library face quality average
- Most photographed person, highest quality person
Database Schema Reference
Detailed schema documentation is in references/database-schema.md. Key tables:
- - ZASSET — Main photos/videos table
- ZADDITIONALASSETATTRIBUTES — File sizes, dimensions
- ZCOMPUTEDASSETATTRIBUTES — Apple's quality scores
- ZPERSON — Detected people
- ZDETECTEDFACE — Face detections
- ZGENERICALBUM — Albums
- ZSCENECLASSIFICATION — ML scene labels
Important: Core Data timestamps are seconds since 2001-01-01, not Unix epoch.
Common Workflows
Workflow 1: Quick Cleanup Assessment
CODEBLOCK34
Workflow 2: Free Up Storage
CODEBLOCK35
Workflow 3: Year-End Photo Recap
CODEBLOCK36
Workflow 4: Export Organized Archive
CODEBLOCK37
Workflow 5: Deep Cleanup
CODEBLOCK38
Workflow 6: Daily Memory Check
CODEBLOCK39
Workflow 7: Location & Travel Review
CODEBLOCK40
Workflow 8: People Deep Dive
CODEBLOCK41
Workflow 9: Live Photo & Storage Optimization
CODEBLOCK42
Workflow 10: Seasonal Year in Review
CODEBLOCK43
Workflow 11: Shared Library Audit
CODEBLOCK44
Tips for AI Assistants
When User Asks About Photos Cleanup
- 1. Start with analysis — Run
library_analysis.py to understand the library - Find junk — Run
junk_finder.py to quantify cleanup opportunities - Be specific — Don't just say "you have junk photos," say "you have 287 screenshots older than 30 days (2.1 GB) that could be deleted"
- Explain savings — Always mention estimated storage savings
- Guide to Photos.app — Scripts identify candidates, but user must delete via Photos.app
When User Asks "What Did I Do?"
- 1. Use timeline_recap — Perfect for narrative summaries
- Narrate, don't dump — Turn JSON into a story
- Highlight favorites — Mention standout moments
- Use emojis — Makes it more engaging
When User Asks About Storage
- 1. Run storage_analyzer — Most comprehensive view
- Identify hogs — Call out the biggest files/categories
- Show trends — "You're adding about 1.5 GB per month"
- Suggest actions — "Deleting old screenshots could free up 2 GB"
When User Asks About Best/Favorite Photos
- 1. Use best_photos — Shows quality distribution and top picks
- Highlight hidden gems — Use --hidden-gems to find unfavorited great shots
- Show scores — Explain what makes a photo high quality (composition, lighting, etc.)
When User Asks About People
- 1. Use people_analyzer — Comprehensive people stats
- Show co-occurrences — "Jonah and Silas appear together in 2,100 photos"
- Show trends — "You photographed Jonah 40% less in 2025"
When User Asks "On This Day" / Memories
- 1. Use onthisday — Perfect for nostalgia
- Narrate warmly — Tell the story of each year
- Suggest window — If nothing found, suggest --window 2 for nearby dates
When User Wants to Actually Delete
- 1. Always preview first — Run cleanup_executor without --execute
- Show counts and sizes — "287 old screenshots, 2.1 GB"
- Explain safety — Items go to Recently Deleted, recoverable for 30 days
- Get confirmation — Never auto-execute cleanup
Output Format Guidance
JSON output: Default for programmatic use, includes full details
Human output: Use --human flag for readable summaries
In conversation: Synthesize the data into natural language, don't just read the output
Requirements
- - Python: 3.9+ (tested with 3.13)
- Platform: macOS only (Apple Photos database)
- Dependencies: None (uses only Python stdlib)
- Database: Read-only access to INLINECODE96
Safety & Permissions
- - ✅ All operations are READ-ONLY — No photos are modified or deleted
- ✅ No external dependencies — Pure Python stdlib
- ✅ No Photos.app API — Direct SQLite reads (safe)
- ⚠️ Smart export uses AppleScript — Requires Photos.app to be running
- ⚠️ Cleanup executor uses AppleScript — Moves items to Recently Deleted (recoverable)
Limitations
- - Read-only analysis — Scripts identify candidates, but cleanup must be confirmed by user
- Export via AppleScript — Requires Photos.app to be running
- Reverse geocoding — Offline lookup covers ~100 major world cities; remote locations show coordinates
- Similarity detection — Uses computed quality vectors (not pixel-level); O(n²) comparison limited by INLINECODE97
- Shared Library columns — Requires macOS 13+ / iOS 16+ database format
- Empty library support — Scripts work on any library, but Matt's Mac mini library is empty (synced elsewhere)
- Schema changes — Apple may change database schema in future macOS versions
Troubleshooting
"Database not found"
→ Specify path with INLINECODE98
"Permission denied"
→ Close Photos.app first, or run script while Photos.app is open (read-only is safe)
"No quality scores"
→ Not all photos have computed quality attributes; scripts handle NULLs gracefully
"Results don't match Photos.app counts"
→ Scripts exclude trashed items; Photos.app may show different views
Future Enhancements
All previously planned features have been implemented! Possible further expansions:
- - Machine learning model export for custom photo classifiers
- Photo deduplication across multiple Photos libraries
- Integration with external photo services (Google Photos, Flickr)
- Time-lapse generation from photo sequences
- Custom smart album rule builder
- Photo metadata repair / bulk editing suggestions
Bottom line: This skill gives you X-ray vision into your Photos library. Use it to understand what you have, find what you don't need, and make cleanup decisions with confidence.
Apple Photos 清理工具
用于分析和清理 Apple Photos 资料库的综合工具包。超越 Photos.app 的功能:智能垃圾检测、详细存储分析、带质量评分的重复项查找、用于故事叙述的时间线回顾以及智能导出规划。
概述
Apple Photos 在整理和同步照片方面表现出色,但在清理方面并不擅长。本技能填补了这一空白:
- - 资料库分析 — 获取全局概况:数量、存储空间、日期范围、人物、质量分布
- 垃圾查找器 — 识别截图、低质量照片、连拍残留、旧截图
- 重复项查找器 — 使用 Apple 检测 + 时间戳/尺寸匹配查找重复项
- 存储分析器 — 按年份、类型、文件格式、增长趋势、存储大户进行详细分解
- 时间线回顾 — 为任意日期范围生成照片活动的叙述性摘要
- 智能导出 — 按年/月、人物、相册或地点规划有序导出;AppleScript 导出
- 最佳照片 / 隐藏珍宝 — 展示您未收藏的高质量照片
- 人物分析器 — 深度分析人物:共现情况、随时间变化的趋势、每人最佳照片
- 地点映射器 — 将 GPS 坐标聚类为地点,识别旅行,离线反向地理编码
- 场景搜索 — 通过机器学习检测的内容(海滩、狗、食物)进行搜索,或生成内容清单
- 拍照习惯 — 行为分析:时段、星期几、连续记录、季节性趋势
- 历史上的今天 — 查看往年今日拍摄的照片
- 相册审计员 — 查找孤立照片、空相册、相册之间的重叠
- 清理执行器 — 通过 AppleScript 批量将垃圾移至废纸篓(需确认)
- 实况照片分析器 — 比较实况照片与静态照片,查找可转换的候选对象,存储影响
- 共享资料库 — 分析共享资料库与个人资料库:贡献者、内容分配、存储空间
- iCloud 状态 — 检查 iCloud 同步覆盖范围:已同步与仅本地、大未同步项目
- 相似度查找器 — 使用计算出的质量特征向量检测视觉上相似的照片
- 季节性精选 — 使用质量评分和收藏夹精选每季最佳照片
- 面部质量评分 — 按人对面部照片进行排名:查找最佳/最差肖像
安全性: 所有操作均为只读数据库查询。未经用户明确操作,不会修改或删除任何照片。
何时使用本技能
当用户提及以下内容时使用:
- - 清理照片 / 释放照片存储空间
- 查找重复照片
- 删除旧截图
- 分析照片资料库存储
- 查找垃圾或低质量照片
- 整理照片导出
- 获取照片时间线摘要(我上周做了什么?)
- 连拍照片清理
- 查找照片中的存储大户
- 查找最佳或隐藏珍宝照片
- 照片中的人物,谁一起出现
- 照片拍摄地点、旅行、行程、位置
- 按内容搜索照片(海滩、日落、狗、食物)
- 拍照习惯、模式、连续记录
- 历史上的今天 / 往年照片回忆
- 相册整理、孤立照片、相册清理
- 实际删除垃圾照片(批量清理)
- 实况照片分析,将实况照片转换为静态照片
- 共享资料库内容,谁贡献了什么
- iCloud 同步状态、未同步照片、云覆盖范围
- 查找外观相似的照片
- 季节性照片精选,每季最佳
- 面部/肖像质量,每人最佳/最差肖像
快速开始
所有脚本均可独立运行。照片数据库自动位于:
~/Pictures/Photos Library.photoslibrary/database/Photos.sqlite
基本工作流程:
- 1. 运行 libraryanalysis.py 获取概况
- 运行 junkfinder.py 识别清理候选对象
- 运行 duplicate_finder.py 查找重复项
- 使用结果指导在 Photos.app 中进行手动清理
命令
1. 资料库分析
获取全面的资料库统计信息:数量、存储空间、日期范围、人物、质量评分。
bash
python3 scripts/library_analysis.py [--human] [--output FILE]
选项:
- - --human — 人类可读摘要而非 JSON
- --output FILE — 将 JSON 写入文件
- --db-path PATH — 自定义数据库路径
- --library PATH — 自定义照片资料库路径
示例输出:
📊 APPLE PHOTOS 资料库分析
==================================================
总资产:12,453
总存储空间:48.3 GB
平均大小:4.1 MB
日期范围:2020-01-15 至 2025-03-03
按类型:
照片:11,234
视频:891
截图:328
收藏:456
连拍:1,234
按年份:
2025:1,203 项,5.2 GB
2024:3,456 项,15.1 GB
2023:2,987 项,12.4 GB
...
主要人物:
Jonah:3,456 张照片
Silas:3,234 张照片
...
对话中的使用:
用户: 我有多少张照片?
AI: 运行带有 --human 标志的 library_analysis.py,报告摘要
用户: 显示我的照片存储分解
AI: 运行 library_analysis.py,突出显示关键统计数据
2. 垃圾查找器
识别清理候选对象:截图、低质量照片、连拍残留、重复项。
bash
python3 scripts/junk_finder.py [--screenshot-age DAYS] [--quality-threshold N] [--human]
选项:
- - --screenshot-age DAYS — 将超过 N 天的截图视为垃圾(默认:30)
- --quality-threshold N — 低质量的质量评分阈值(默认:0.3,范围:0.0-1.0)
- --no-duplicates — 跳过重复检测
- --human — 人类可读摘要
- --output FILE — 将 JSON 写入文件
示例输出:
🗑️ 垃圾查找器结果
==================================================
发现:
📸 截图:328
└─ 旧(>30 天):287
📉 低质量:156
📸 连拍残留:1,089
👥 可能重复:45
预计节省:
保守:2.3 GB
(旧截图 + 连拍残留)
激进:5.7 GB
(所有截图 + 低质量 + 连拍 + ~50% 的重复项)
它能找到什么:
- - 截图 — 通过 ZISDETECTEDSCREENSHOT 标志检测
- 旧截图 — 超过指定天数的截图(可安全删除)
- 低质量 — 质量评分低的照片(高失败/噪声,低构图/光照)
- 连拍残留 — 连拍序列中未选中的照片
- 可能重复 — 使用 Apple 内置检测
对话中的使用:
用户: 在我的照片中查找垃圾
AI: 运行 junk_finder.py,报告总数和预计节省空间
用户: 我有多少张旧截图?
AI: 运行 junk_finder.py,聚焦截图统计
用户: 我可以删除什么来释放 5GB?
AI: 运行 junk_finder.py,显示保守/激进估计,建议下一步操作
3. 重复项查找器
查找重复照片并根据质量、收藏状态和文件大小推荐保留哪些。
bash
python3 scripts/duplicate_finder.py [--human] [--output FILE]
检测方法:
- 1. Apple 内置 — 使用 ZDUPLICATEASSETVISIBILITYSTATE
- 时间戳 + 尺寸 — 同一秒拍摄且尺寸相同的照片
推荐逻辑:
- - 收藏优先
- 截图扣分
- 最高质量评分优先
- 最大文件大小作为平局决胜
示例输出:
👥 重复项查找器结果
==================================================
发现 12 个重复组
总重复项:27
可安全删除:15
总大小:156 MB
潜在节省:89 MB
示例组(显示前 5 个):
组 1(apple_builtin):
✓ 保留 ★ IMG_1234.jpg(4.2 MB,Q:0.823)
删除 IMG_1234-2.jpg(4.1 MB,Q:0.801)
组 2(timestamp_dim