litemm 0.1.0

Media Manager & Visualizer

📸 MM — Universal Organizer for Media

A self-hosted, AI-powered media library manager for photos, videos, and audio.

Scan, tag, search, deduplicate, and browse your media collection with a beautiful web UI.

---

Features · Quick Start · Installation · Usage · Web UI · API · Contributing

---

✨ Features

🔍 Smart Scanning Recursive media discovery with parallel processing SHA-256 hashing for integrity & deduplication EXIF, video, and audio metadata extraction Support for RAW, HEIC/HEIF, and 30+ formats	🤖 AI-Powered CLIP-based image embeddings (ViT-B-32) Natural language image search ("sunset over ocean") Zero-shot auto-tagging (~36 categories) Visual similarity search
🌍 Offline Geocoding Reverse geocoding from GPS EXIF data GeoNames cities15000 dataset (no API keys needed) Chinese province/city name support Chinese lunar & solar festival detection	🖼️ Beautiful Web UI Responsive gallery with justified layout Pinch-to-zoom thumbnail resizing Infinite scroll with date grouping Detail panel with full metadata & map
📁 Library Management Manual & smart albums (auto-generated) Star ratings, tags, batch operations Template-based file import & organization Multi-library support with runtime switching	⚡ Performance SQLite-backed (zero config, portable) WebP thumbnail caching (4 sizes) with ETag Async API server (FastAPI + Uvicorn) Background CLIP processing

🏗️ Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Web UI (React)                        │
│         React 19 · TailwindCSS · Zustand · Vite              │
└──────────────────┬───────────────────────────────────────────┘
                   │ REST API
┌──────────────────▼───────────────────────────────────────────┐
│                    FastAPI Server                             │
│     Auth · Media · Albums · Smart Albums · Tags · Stats      │
└──────────────────┬───────────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────────┐
│                    Core Engines                               │
│  Scanner · Metadata · Embeddings · Tagger · Geocoding · ...  │
└──────────────────┬───────────────────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────────────────┐
│               SQLite (Peewee ORM / aiosqlite)                │
│         Media · Metadata · Tags · Embeddings · Albums        │
└──────────────────────────────────────────────────────────────┘

🚀 Quick Start

# Install with uv (recommended)
uv pip install -e .

# Create a new library (interactive)
mm init ~/Photos

# Start the web server
mm server
# → Open http://localhost:8000

📦 Installation

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• exiftool — for EXIF metadata extraction
• ffmpeg / ffprobe — for video/audio metadata & thumbnails

# macOS
brew install exiftool ffmpeg

# Ubuntu / Debian
sudo apt install libimage-exiftool-perl ffmpeg

Install mm

# Clone the repository
git clone https://github.com/HSPK/mm.git
cd mm

# Install with uv
uv pip install -e .

# (Optional) Install CLIP support for AI features
uv pip install -e ".[clip]"

Build the Frontend

cd web
npm install
npm run build
cd ..

📖 Usage

CLI Commands

Command	Description
mm init [dir]	Create or open a media library (interactive setup)
mm server [dir]	Start the web UI server
mm import <source>	Import media files into the active library
mm search	Search by text, image, or tags (requires CLIP)
mm dedup	Find and remove duplicate media files by hash
mm info <file>	Show detailed file metadata
mm config [key] [value]	Get or set library config values
mm geo update	Offline reverse geocode GPS-tagged media
mm db list	List all registered databases
mm db set <n>	Switch the active database
mm db add <path>	Register an existing database file
mm db rm <n>	Unregister a database (optionally delete)
mm db stats	Show detailed library statistics
mm db clean	Remove entries for files no longer on disk
mm db sync <dir>	Clean stale entries and re-scan changed files

Library Setup

# Create a new library interactively
mm init ~/Photos

# View all config values
mm config

# Set the import template
mm config import_template "{year}/{year}-{month:02d}-{day:02d}/{original_name}{ext}"

# Sync database with disk (remove stale + re-scan)
mm db sync ~/Photos

# Parallel sync with 8 workers
mm db sync ~/Photos -j 8

Searching

# Semantic search by text (requires CLIP)
mm search --text "sunset at the beach"

# Search by image similarity
mm search --image ~/Photos/reference.jpg --top-k 20

# Filter by tags
mm search --tag landscape --tag nature

Deduplication

# Find and remove duplicate media files (by hash)
mm dedup

Importing & Organizing

# Import from SD card (copies into library using configured template)
mm import ~/DCIM

# Move instead of copy
mm import ~/DCIM --move

Web Server

# Start on default port (8000)
mm server

# Specify library directory
mm server ~/Photos

# Custom host and port
mm server -h 0.0.0.0 -p 9000

# Development mode with auto-reload
mm server --reload

🌐 Web UI

The web interface provides a full-featured media browser:

• Library — Browse all media with infinite scroll, date grouping, and adjustable thumbnail sizes
• Albums — Smart albums auto-generated by tag, camera, year, festival, and location
• Search — Quick filtering and semantic search
• Detail View — Full metadata, EXIF info, location, tags, and star ratings
• Batch Operations — Multi-select for bulk tagging, rating, and deletion
• Settings — Theme switching (light/dark), library management
• Auth — User accounts with token-based authentication

🔌 API

mm exposes a comprehensive REST API at /api/:

Endpoint	Description
/api/auth/*	Authentication (login, setup, logout)
/api/media	Media CRUD, thumbnails, file streaming
/api/batch/*	Bulk operations (tags, ratings, delete)
/api/albums/*	Album management
/api/smart-albums/*	Smart album definitions & resolution
/api/tags	Tag CRUD with usage counts
/api/stats	Library statistics & timeline
/api/library	Multi-library switching
/api/users	User management (admin)

Interactive API docs available at /docs (Swagger UI) when the server is running.

🛠️ Tech Stack

Component	Technology
Backend	Python 3.10+, FastAPI, Peewee ORM, SQLite
AI/ML	OpenCLIP (ViT-B-32), PyTorch
Frontend	React 19, TypeScript, TailwindCSS, Vite
State	Zustand
UI Kit	shadcn/ui, Radix UI, Lucide Icons
Media	Pillow, pillow-heif, rawpy, exiftool, ffmpeg
Geocoding	GeoNames (offline), lunar-python

🤝 Contributing

Contributions are welcome! Here's how to get started:

# Clone and install in dev mode
git clone https://github.com/HSPK/mm.git
cd mm
uv pip install -e ".[clip]"

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Start frontend dev server
cd web && npm install && npm run dev

Please open an issue first to discuss what you would like to change.

📄 License

This project is open source. See the LICENSE file for details.

---

If you find mm useful, please consider giving it a ⭐!