# media-curator
AI-assisted curation and organization for large media datasets
## motivation
If you've ever dealt with thousands of images, videos, or audio files dumped into folders with cryptic names, you know the pain. Manual organization doesn't scale, and basic rule-based systems miss the semantic relationships between content. This tool uses machine learning models to understand what's actually in your media files, then helps you tag, filter, deduplicate, and organize them in ways that make sense. It's built for photographers, researchers, archivists, and anyone drowning in unstructured media who needs their computer to actually understand what it's storing.
## architecture
```mermaid
graph TB
A[Media Files] --> B[Scanner]
B --> C[Feature Extractor]
C --> D[Embedding Store]
D --> E[Curator Engine]
E --> F[Tag Generator]
E --> G[Similarity Finder]
E --> H[Deduplicator]
F --> I[Metadata DB]
G --> I
H --> I
I --> J[Query Interface]
J --> K[Organized Output]
style C fill:#e1f5ff
style E fill:#fff4e1
style I fill:#f0e1ffpip install media-curator
from media_curator import Curator
# Initialize with your media directory
curator = Curator("./my_photos")
# Extract features from all images
curator.scan()
# Auto-tag based on content
curator.generate_tags(model="clip")
# Find duplicates and near-duplicates
duplicates = curator.find_duplicates(threshold=0.95)
# Query semantically
results = curator.search("sunset over mountains")
# Export organized structure
curator.export("./organized", strategy="by_date_and_tags")The core workflow has three stages. First, the scanner walks your media directories and extracts embeddings using vision or audio models (CLIP for images, Whisper for audio, etc.). These embeddings capture semantic meaning in a way that filename-based tools can't. Second, the curator engine clusters similar items, generates tags from the embeddings, and identifies duplicates using cosine similarity. Finally, you can query the collection using natural language or export to an organized folder structure based on dates, auto-generated tags, or custom rules. Everything runs locally by default, with optional API backends for larger models.
Create a curator.yaml in your project root:
# Models to use for different media types
models:
image: "openai/clip-vit-base-patch32"
video: "microsoft/xclip-base-patch32"
audio: "openai/whisper-base"
# Scanning behavior
scanner:
recursive: true
extensions: [".jpg", ".png", ".mp4", ".mov", ".mp3", ".wav"]
ignore_patterns: [".*", "_*"]
# Deduplication settings
deduplication:
threshold: 0.95
strategy: "keep_highest_resolution"
# Tag generation
tagging:
min_confidence: 0.7
max_tags_per_item: 10
custom_taxonomy: "tags.txt" # optional
# Storage
storage:
embeddings_db: "./embeddings.db"
metadata_db: "./metadata.db"
cache_dir: "./cache"Q: Does this work offline?
A: Yes. Default models download once and run locally. You can also point to API endpoints if you prefer.
Q: What media formats are supported?
A: Images (JPEG, PNG, WebP), video (MP4, MOV, AVI), and audio (MP3, WAV, FLAC). Format support depends on your installed codecs.
Q: How accurate is the deduplication?
A: It catches exact duplicates, resized versions, and crops. Slight color grading or compression changes usually still match above 0.9 similarity.
Q: Can I add custom tags or categories?
A: Yes. Provide a taxonomy file or use the API to inject manual tags that complement the auto-generated ones.
Q: How much disk space does it use?
A: Embeddings are ~512 floats per item (2KB), plus thumbnails if cached. Metadata DB is negligible. A 10k image collection needs roughly 20MB.
Q: Performance on large datasets?
A: Scanning is I/O bound. 10k images takes 5-10 minutes on a modern laptop with GPU. Queries are fast (milliseconds) once indexed.
MIT