# MediaShelf

A self-hosted web app for figuring out which of the thousands of files in a Plex library
are actually worth keeping.

MediaShelf scans a Plex Media Server over its HTTP API, builds a local snapshot of every
movie and TV season, and joins together the facts Plex already knows but never shows side
by side — date added, size on disk, file path, owning library, watch count, and last
watched — into a sortable, filterable, chartable grid with a tunable **reclaim score**
that ranks deletion candidates.

## Status

**v1 is report-only.** MediaShelf does not delete, move, or modify anything. It produces
a ranked list, saved rule sets, and CSV export. Deletion is designed for in the roadmap
but deliberately not built, so the scanner and the scoring model can be trusted before
anything destructive is wired up.

Nothing is implemented yet — this repository currently holds the design.

## What it does

- Full-library ingest from Plex, no agent on the Plex host, no filesystem mounts
- Movies at item level, TV rolled up to **season** level
- Watch data pulled from the server-wide playback history, so plays by *every* Plex
  account are counted — not just the token owner's
- Sort and filter on every metric; charts for size by library, additions over time,
  watched vs. unwatched by size, and size vs. last-watched
- A weighted reclaim score with live sliders, and grace rules so it never recommends
  something you added last week
- Named, re-runnable saved views — *"unwatched, older than 2 years, over 10 GB"*
- CSV export of any view

## Planned stack

Python + Flask, SQLite (WAL), vanilla JS front-end, single container deployed as a
Portainer stack behind Nginx Proxy Manager.

## Roadmap

- **v2** — two-stage quarantine-then-purge deletion, with authentication, a path
  allowlist, and an audit log
- **v3** — Emby and Jellyfin support behind the existing `MediaProvider` abstraction

## Documentation

- [`docs/design.md`](docs/design.md) — the full software design