56 lines
2 KiB
Markdown
56 lines
2 KiB
Markdown
# mama
|
|
|
|
**M**edia **A**rchive **M**eets **A**utomation — a self-hosted system for
|
|
ingesting, deduplicating, and organizing personal media (photos, videos, music,
|
|
documents) on top of ZFS.
|
|
|
|
## ⚠️ Project Status
|
|
|
|
**Pre-alpha. Not ready for use by anyone but the author.**
|
|
|
|
- Database schema, CLI surface, on-disk layout, and HTTP API are unstable and
|
|
will change without migration paths.
|
|
- Most features described below are planned, not implemented.
|
|
- Documentation lags behind code.
|
|
|
|
Do not point mama at irreplaceable data. Keep independent backups of anything
|
|
mama touches.
|
|
|
|
## Concept
|
|
|
|
mama indexes files placed in configured scan folders, stores file contents in a
|
|
content-addressed blob store, and exposes them through hardlinked filesystem
|
|
views consumable by specialized viewers (Immich for photos and video, Navidrome
|
|
for music, Paperless-ngx for documents).
|
|
|
|
Identical content is stored only once. Per-file context — original path, source
|
|
device, scan timestamp, embedded metadata (EXIF, ID3, sidecar files) — is
|
|
preserved as *observations* linked to the underlying blob, so duplicates
|
|
contribute information instead of clutter.
|
|
|
|
### Workflow
|
|
|
|
1. `mama-scan PATH` — index files into the database (no copies, no moves)
|
|
2. `mama-apply` — materialize approved observations into the archive
|
|
(blob into CAS, hardlink into view)
|
|
3. `mama-web` — browse, merge duplicates, filter, export, delete
|
|
|
|
## Tech Stack
|
|
|
|
- Python 3.13, FastAPI, SQLAlchemy 2.x (async), Alembic
|
|
- PostgreSQL 16 (JSONB for embedded metadata)
|
|
- Vue 3, Vite
|
|
- ZFS (single archive dataset, snapshots, NFS export), Caddy
|
|
- ExifTool, BLAKE3, ffmpeg, Pillow
|
|
- Docker Compose for companion viewers (Immich, Navidrome, Paperless-ngx)
|
|
|
|
## Disclaimer
|
|
|
|
mama is provided as-is for personal use. The author assumes no responsibility
|
|
for data loss, corruption, mis-deduplication, accidental deletion, or any other
|
|
adverse outcome arising from its use. Use at your own risk and only on data you
|
|
can afford to lose.
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|