litemm 0.1.2

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

Why MM?

Most open-source media managers (Immich, PhotoPrism, LibrePhotos) are designed as heavy, multi-container services that require PostgreSQL, Redis, and dedicated ML micro-services. MM takes the opposite approach — a single Python process with SQLite, installable via pip, runnable on a Raspberry Pi, and fully functional without a GPU.

🪶 Lightweight & Zero-Config Single process — no Docker orchestration, no PostgreSQL, no Redis SQLite-backed — zero config, portable, just one .db file pipx install litemm and you're ready to go Runs comfortably on a Raspberry Pi 4 (4 GB)	🤖 Built-in AI — No External Services CLIP embeddings (ViT-B-32) with optional install Natural language search ("sunset over ocean") Zero-shot auto-tagging (~36 categories) Visual similarity search — all offline, on-device
🌍 First-Class CJK & Chinese Support Offline reverse geocoding (GeoNames, no API keys) Chinese province & city name translation (全国省市中文映射) 170+ Chinese festival detection (春节、清明、中秋…) Auto-generated festival albums — unique to MM	📁 Non-Destructive & Coexists with Others Read-only indexing — never modifies your original files Works alongside Lightroom / Apple Photos on the same folder Relative path storage — entire library is portable & movable SHA-256 deduplication prevents duplicate imports
🖥️ Full CLI + Web UI Complete command-line toolkit for automation & scripting Template-based import ({year}/{camera}/{original_name}{ext}) Beautiful responsive gallery with justified layout & infinite scroll Smart albums auto-generated by tag, camera, year, festival, place	⚡ Production-Ready Async API server (FastAPI + Uvicorn) WebP thumbnail caching (4 sizes) with ETag / HTTP 304 Multi-library support with runtime switching Frontend bundled in pip package — no Node.js needed to deploy

MM vs. Others

	MM	Immich	PhotoPrism	LibrePhotos
Install	pip install	6+ Docker containers	Docker + MariaDB	Docker + PostgreSQL
Min RAM	~300 MB	~4 GB	~2 GB	~4 GB
Database	SQLite	PostgreSQL	MariaDB	PostgreSQL
AI search	CLIP (optional)	CLIP (separate service)	TensorFlow	CLIP
Chinese localization	Province/city/festivals	✗	✗	✗
CLI tooling	Full	Minimal	Minimal	✗
Modifies originals	Never	Never	Sidecar writes	Never
Mobile app	—	iOS + Android	PWA	—
Face recognition	—	✓	✓	✓

🏗️ 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 pipx (recommended)
pipx install litemm

# Create a new library (interactive)
mm init

# 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

# Install with pipx (recommended)
pipx install litemm

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 sync

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](LICENSE) file for details.

---

<div align="center">

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

[![Star History Chart](https://api.star-history.com/svg?repos=HSPK/mm&type=Date)](https://star-history.com/#HSPK/mm&Date)

</div>