yrtria/MediaShelf
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Plex library analytics and reclaim-candidate reporting. v1 is report-only.
1 commit 1 branch 0 tags 550 KiB
Find a file
Jess Hallsworth fdcddc8149
Initial design for MediaShelf 
Software design for a Plex library analytics and reclaim-reporting tool.
v1 is report-only: no deletion, no filesystem access, Plex API as the sole
data source. Movies at item level, TV rolled up to season level.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVbG48GAXfCZatcmX123Ra
2026-09-07 03:41:38 +00:00
docs Initial design for MediaShelf 2026-09-07 03:41:38 +00:00
.env.example Initial design for MediaShelf 2026-09-07 03:41:38 +00:00
.gitignore Initial design for MediaShelf 2026-09-07 03:41:38 +00:00
README.md Initial design for MediaShelf 2026-09-07 03:41:38 +00:00

README.md

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