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.
3 commits 1 branch 0 tags 550 KiB
Find a file
Jess Hallsworth 2c1033e4a7
Add a read-only LAN probe for validating the design 
Tautulli stays local-network-only, so nothing off the LAN can check this
design against real data. tools/probe.py closes that gap from the inside:
GET requests only, standard library only, credentials redacted from all
output including error messages.

It answers open questions 1-4 in one run — Tautulli's coverage horizon,
the finished/partial/abandoned split across real plays, whether successive
plays are being grouped, library shapes and sizes, multi-version items,
and path roots by size. It also runs the pms_identifier cross-check from
section 4.11.

tools/mockserver.py mocks both APIs so the probe is testable without a live
server. Verified against it: the happy path, Tautulli absent, Tautulli
unreachable, Tautulli erroring, Plex unreachable, and an identifier
mismatch. Credential redaction confirmed in every error path.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GVbG48GAXfCZatcmX123Ra
2026-09-07 04:57:38 +00:00
docs Add a read-only LAN probe for validating the design 2026-09-07 04:57:38 +00:00
tools Add a read-only LAN probe for validating the design 2026-09-07 04:57:38 +00:00
.env.example Promote Tautulli to the primary watch-history source 2026-09-07 04:51:41 +00:00
.gitignore Initial design for MediaShelf 2026-09-07 03:41:38 +00:00
README.md Add a read-only LAN probe for validating the design 2026-09-07 04:57: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 and pulls watch history from Tautulli, builds a local snapshot of every movie and TV season, and joins together facts that are never shown side by side — date added, size on disk, file path, owning library, watch count, last watched, and how much of it anyone actually finished — 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 from Tautulli, so plays by every account are counted and a play that was abandoned after five minutes is distinguished from one that was finished — Plex's own history reports those identically. Falls back to Plex session history if Tautulli is unavailable, and says so rather than degrading silently
  • Sort and filter on every metric; charts for size by library, additions over time, finished vs. abandoned vs. never-opened 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", "two people started it and nobody finished it"
  • 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

Validating the design first

Plex and Tautulli are both LAN-only, so tools/probe.py exists to check this design against real data from inside the network. It is read-only — GET requests only, nothing is modified — and has no dependencies beyond the standard library.

export PLEX_BASE_URL=http://192.168.1.10:32400
export PLEX_TOKEN=...
export TAUTULLI_BASE_URL=http://192.168.1.100:8181
export TAUTULLI_API_KEY=...

python3 tools/probe.py                        # summary to stdout
python3 tools/probe.py --dump inventory.json  # plus a full item inventory

It reports Tautulli's coverage horizon, the finished/abandoned/never-opened split across real plays, library shapes and sizes, path roots, multi-version items, and whether Tautulli is actually watching the Plex server you think it is. Credentials are redacted from all output including error messages, so the result is safe to paste anywhere.

Documentation