[V3.0 Update Development] Proposals and To-Do List

[StudioNirin]

@Brandon-Haney
I'll keep this top message updated with new features list and a to-do list / bugfixes as we go along. Figure it'll also be helpful for filling out the eventual changelog and release notes cos I forgot half the things that ended up going into V2 lol.

1. Add in functionality for Remote Users Watchlists to be individually turned on/off in the setup script.
2. Create 'Smart Cache Eviction' policies for keeping and removing cached files based on various priority values if/when free space on the cache becomes full.
3. 'Multi Path Mapping' options for more complex setups where people might have multiple caches or network storage libraries for their media. Will be an optional setup, and gets automatically skipped for users that don't require it, so keeps setup simple.

Additional - Look into the possibility of moving PlexCache-R into a docker container.

Let me know if you think of anything else and I'll keep this top post updated.

[Brandon-Haney]

Here's what I've been working on in my feature branches:

---

Smart Cache Eviction System

Branch: feature/smart-cache-and-watched-removal
Status: Functional, needs testing

Implements priority-based cache eviction to intelligently free space when cache is nearing capacity.

New Classes

• OnDeckTracker - Tracks which users have items OnDeck
• CachePriorityManager - Calculates 0-100 priority scores for cached items

Priority Scoring (0-100)

Factor	Points
Source type	+20 for OnDeck (protected)
User count	+5 per user (max +15)
Cache recency	+5 to +15 based on how recently cached
Watchlist age	+10 fresh, 0 if >30d, -10 if >60d
OnDeck age	+10 recent, 0 if >30d, -10 if >60d

Eviction Modes

• smart - Priority-based (low scores evicted first, OnDeck protected)
• fifo - First-in-first-out
• none - Disabled (default, current behavior)

New Settings

{
  "cache_eviction_mode": "smart",
  "cache_eviction_threshold_percent": 90,
  "eviction_min_priority": 60
}

New CLI Flag

• --show-priorities - Display priority report for all cached items

Philosophy

Watchlist-only items get evicted first. OnDeck items are protected with higher base scores.

---

Multi-Path Mapping System

Branch: feature/multi-path (includes smart-cache features)
Status: Functional, needs testing

Replaces single global path settings with per-library path configuration. Useful for users with multiple arrays or who only want certain libraries cached.

New Data Model

{
  "path_mappings": [
    {
      "library_name": "Movies",
      "plex_source": "/data/movies",
      "real_source": "/mnt/user/media/movies",
      "cache_path": "/mnt/cache/media/movies",
      "cacheable": true
    },
    {
      "library_name": "TV Shows",
      "plex_source": "/data/tv",
      "real_source": "/mnt/user/media/tv",
      "cache_path": "/mnt/cache/media/tv",
      "cacheable": true
    },
    {
      "library_name": "Music",
      "plex_source": "/data/music",
      "real_source": "/mnt/user/media/music",
      "cache_path": null,
      "cacheable": false
    }
  ]
}

Features

• Per-library cacheable toggle - Exclude specific libraries from caching
• Auto-migration - Existing single-path configs automatically migrate
• Longest-prefix matching - Handles overlapping paths correctly
• Backwards compatible - Legacy plex_source/real_source still work

New CLI Flag

• --show-mappings - Display current path mapping configuration

---

Setup Wizard Redesign

Branch: feature/multi-path
Status: Complete

Major UX overhaul to make initial setup faster and less confusing.

Progress & Flow

• Step progress indicators (STEP 1/5, 2/5, etc.)
• Ask for cache root ONCE at start, auto-apply to all libraries
• End-of-setup summary with full configuration overview

Improved Prompts

• Default Plex URL suggestion (localhost:32400)
• Shows Plex paths during library selection for context
• Smart path suggestions (learns from your first entry)

---

Other Improvements

• RSS Feed Retry + Cache Fallback - Already merged to v2.0 via PR Fix RSS feed timeout causing incorrect file moves #34
• UUID resolution for RSS feed users - Better user tracking from RSS
• Priority report enhancements - User counts, stale entry filtering, better sorting

---

Both feature branches are available on my fork if you want to try them out. I've tested both on my server and they are working well, will need additional testers eventually.

[Brandon-Haney]

Multi-Path Mapping System

Branch: feature/multi-path (includes smart-cache features) Status: Functional, needs testing

Replaces single global path settings with per-library path configuration. Useful for users with multiple arrays or who only want certain libraries cached.

New Data Model

{
"path_mappings": [
{
"library_name": "Movies",
"plex_source": "/data/movies",
"real_source": "/mnt/user/media/movies",
"cache_path": "/mnt/cache/media/movies",
"cacheable": true
},
{
"library_name": "TV Shows",
"plex_source": "/data/tv",
"real_source": "/mnt/user/media/tv",
"cache_path": "/mnt/cache/media/tv",
"cacheable": true
},
{
"library_name": "Music",
"plex_source": "/data/music",
"real_source": "/mnt/user/media/music",
"cache_path": null,
"cacheable": false
}
]
}

Features

• Per-library cacheable toggle - Exclude specific libraries from caching
• Auto-migration - Existing single-path configs automatically migrate
• Longest-prefix matching - Handles overlapping paths correctly
• Backwards compatible - Legacy plex_source/real_source still work

New CLI Flag

• --show-mappings - Display current path mapping configuration

Setup Wizard Redesign

Branch: feature/multi-path Status: Complete

Major UX overhaul to make initial setup faster and less confusing.

Progress & Flow

• Step progress indicators (STEP 1/5, 2/5, etc.)
• Ask for cache root ONCE at start, auto-apply to all libraries
• End-of-setup summary with full configuration overview

Improved Prompts

• Default Plex URL suggestion (localhost:32400)
• Shows Plex paths during library selection for context
• Smart path suggestions (learns from your first entry)

Other Improvements

• RSS Feed Retry + Cache Fallback - Already merged to v2.0 via PR Fix RSS feed timeout causing incorrect file moves #34
• UUID resolution for RSS feed users - Better user tracking from RSS
• Priority report enhancements - User counts, stale entry filtering, better sorting

Both feature branches are available on my fork if you want to try them out. I've tested both on my server and they are working well, will need additional testers eventually.

After further testing, I've identified a limitation with the multi-path system that users should be aware of:

The .plexcached backup system does NOT work with remote/network-mounted storage (e.g., Synology NAS mounted via SMB at /mnt/remotes/).

Why it doesn't work:

• When PlexCache-R renames a file to .plexcached, Sonarr/Radarr no longer see the original file and may attempt to re-download it
• AFAIK Cross-machine symlinks aren't possible (can't create a symlink on Synology pointing to Unraid local cache)
• The .plexcached backup system was designed for local Unraid array <> cache moves on the same machine

What works:

• Local Unraid libraries where both array and cache paths are on the same Unraid server
• Path mappings like: /mnt/user/TV Shows (array) <> /mnt/cache_downloads/TV Shows (cache)

What doesn't work:

• Remote NAS mounts like /mnt/remotes/NAS_Media/ as the "array" path
• Any setup where Sonarr/Radarr monitor a different path than Unraid's /mnt/user/
• Underlying FUSE system required (/mnt/user vs /mnt/user0)

[StudioNirin]

Here's what I've been working on in my feature branches:

Both feature branches are available on my fork if you want to try them out. I've tested both on my server and they are working well, will need additional testers eventually.

Nice, I'll look at these tomorrow. Keeping new features split up into their own branches makes it a lot easier to look at each one and merge them one by one.

After further testing, I've identified a limitation with the multi-path system that users should be aware of:

The .plexcached backup system does NOT work with remote/network-mounted storage (e.g., Synology NAS mounted via SMB at /mnt/remotes/).

Interesting. Definitely something we need to put in the wiki or on the readme somewhere. Though hopefully not many people use that kind of setup. It seems a bit convoluted/unnecessary but I guess there's a use-case for it that I'm not seeing.

Perhaps the solution on our end would be adding an option in setup/settings, where the user can instead choose to use the old style of caching where the files are moved instead of renamed.

Though I would think moving the files would have the same issue of sonarr/radarr losing the file, if they aren't able to see it on the cache drive on those systems in either case? So perhaps it's just a universal "plexcached is not compatible with remote network storage of media".

I am not sure why you would have a NAS, that instead of storing files on the NAS itself you store it on a different NAS. NAS-ception.

[Brandon-Haney]

Here's what I've been working on in my feature branches:

Both feature branches are available on my fork if you want to try them out. I've tested both on my server and they are working well, will need additional testers eventually.

Nice, I'll look at these tomorrow. Keeping new features split up into their own branches makes it a lot easier to look at each one and merge them one by one.

After further testing, I've identified a limitation with the multi-path system that users should be aware of:
The .plexcached backup system does NOT work with remote/network-mounted storage (e.g., Synology NAS mounted via SMB at /mnt/remotes/).

Interesting. Definitely something we need to put in the wiki or on the readme somewhere. Though hopefully not many people use that kind of setup. It seems a bit convoluted/unnecessary but I guess there's a use-case for it that I'm not seeing.

Perhaps the solution on our end would be adding an option in setup/settings, where the user can instead choose to use the old style of caching where the files are moved instead of renamed.

Though I would think moving the files would have the same issue of sonarr/radarr losing the file, if they aren't able to see it on the cache drive on those systems in either case? So perhaps it's just a universal "plexcached is not compatible with remote network storage of media".

I am not sure why you would have a NAS, that instead of storing files on the NAS itself you store it on a different NAS. NAS-ception.

The reason I have a separate NAS is for all my 4K content, my Unraid server handles the rest. I was hoping to cache those files to Unraid as well, but I missed that Sonarr/Radarr would see them as missing once renamed to .plexcached. I considered making the rename optional, but that wouldn't work either even if we moved instead of renamed, Plex's library paths point to the NAS mount, not the Unraid cache drive. It would never read from cache anyway.

So yes, it's a universal "PlexCache-R is not compatible with remote network storage" limitation. The multi-path feature handles this by letting you mark remote paths as cacheable: false so PlexCache-R gracefully skips them instead of failing or behaving unexpectedly.

Multi-path benefits

The multi-path system is still useful for users with non-standard Unraid structures. For example:

• Multiple cache pools: TV shows cache to /mnt/nvme/ while movies cache to /mnt/ssd/
• Selective caching: Cache TV libraries but skip 4K movie libraries (too large to justify cache space)
• Non-standard folder structures: Libraries at different paths like /mnt/user/media/tv/ and /mnt/user/data/movies/ with different Plex container mappings
• Improved setup wizard: Guides users through per-library path configuration with clear status display

The legacy single-path system couldn't handle any of these, everything had to share the same plex_source > real_source > cache_dir structure.

Backwards compatible: Existing configs are automatically upgraded on first run. Legacy fields are preserved, so users can revert to the old codebase if needed without modifying their settings file.

[StudioNirin]

Ahh, I just have all my 4k content on the same NAS. I just run two instances of sonarr and radarr, one for SD and one for 4k.

The multi path setup seems fine at first glance but I wouldn't want to make the setup process overly complicated. I think there would need to be a question like "do you need advanced path management options yes/no" and if no that entire setup gets skipped and doesn't effect anything. (You may have already done this, I haven't gone through any of it yet)

[Brandon-Haney]

That's a fair point about keeping setup simple for standard users. Here's how I've approached it

Current Implementation:

• The path_mappings system is already backward-compatible, it auto-migrates legacy single-path configs on first run
• Standard users with one library type still only configure one cache path
• The complexity only appears when users have multiple libraries or want selective caching

Setup Wizard Approach:
I could add a detection step early in setup:

1. Scan Plex libraries
2. If user has just Movies + TV Shows pointing to the same root > simple mode (single cache path, done)
3. If user has multiple roots, 4K libraries, or remote mounts > offer "Advanced path configuration"

This way, 90% of users see the same simple flow they're used to, while power users get the flexibility they need.

Would that approach work? The goal is zero added complexity for standard setups while not blocking users with non-standard configurations.

Below is current my setup wizard with some items redacted:

root@Alpha:/mnt/cache_appdata/apps/PlexCache-R# python3 plexcache_setup.py
Welcome to PlexCache-R Setup!
Creating new configuration at: /mnt/cache_appdata/apps/PlexCache-R/plexcache_settings.json


============================================================
STEP 1/5: PLEX CONNECTION
============================================================

Plex server address [http://localhost:32400]: http://localhost:32400
✓ Plex URL: http://localhost:32400

How would you like to authenticate?
  [1] Authenticate via Plex.tv (recommended)
  [2] Enter token manually

Select option [1/2]: 2

To get your token:
  1. Open Plex Web App → Developer Tools (F12)
  2. Network tab → Find request to plex.tv
  3. Copy 'X-Plex-Token' from headers

Enter your Plex token: REDACTED

✓ Connected as: Alpha_
✓ Plex platform: Linux

============================================================
STEP 2/5: LIBRARY SELECTION
============================================================

Where is your cache drive located?
(All cacheable libraries will use subdirectories here)
Cache drive path [/mnt/cache]: /mnt/cache_downloads

✓ Cache root: /mnt/cache_downloads/

Now select which libraries to include and configure their paths.
For each library, you'll specify where files are actually stored.

------------------------------------------------------------
Library: Movies
  Plex path: /data/Movies
Include? [Y/n] y
  Where is this located on your filesystem?
  Real path [/mnt/user/Movies]:

  Can this be cached locally? (No for remote/network storage)
  Cacheable? [Y/n]: y

  Where should cached files be stored?
  Cache path [/mnt/cache_downloads/Movies/]:

  ✓ Movies: /data/Movies/ → /mnt/user/Movies/ → /mnt/cache_downloads/Movies/

------------------------------------------------------------
Library: Movies 4K
  Plex path: /nas/Movies UHD
Include? [Y/n] y
  Where is this located on your filesystem?
  Real path [/nas/Movies UHD]: /mnt/remotes/NAS_Media/Movies UHD

  Can this be cached locally? (No for remote/network storage)
  Cacheable? [Y/n]: n

  ✓ Movies 4K: /nas/Movies UHD/ → /mnt/remotes/NAS_Media/Movies UHD/ (non-cacheable)

------------------------------------------------------------
Library: TV Shows
  Plex path: /data/TV Shows
Include? [Y/n] y
  Where is this located on your filesystem?
  Real path [/mnt/user/TV Shows]:

  Can this be cached locally? (No for remote/network storage)
  Cacheable? [Y/n]: y

  Where should cached files be stored?
  Cache path [/mnt/cache_downloads/TV Shows/]:

  ✓ TV Shows: /data/TV Shows/ → /mnt/user/TV Shows/ → /mnt/cache_downloads/TV Shows/

------------------------------------------------------------
Library: TV Shows 4K
  Plex path: /nas/TV Shows UHD
Include? [Y/n] y
  Where is this located on your filesystem?
  Real path [/nas/TV Shows UHD]: /mnt/remotes/NAS_Media/TV Shows UHD

  Can this be cached locally? (No for remote/network storage)
  Cacheable? [Y/n]: n

  ✓ TV Shows 4K: /nas/TV Shows UHD/ → /mnt/remotes/NAS_Media/TV Shows UHD/ (non-cacheable)

------------------------------------------------------------
Library: Audiobooks
  Plex path: /data/Audiobooks
Include? [Y/n] n
  → Skipped

------------------------------------------------------------
Library: Music
  Plex path: /data/Music
Include? [Y/n] n
  → Skipped

------------------------------------------------------------
✓ Configured 4 library path(s)
  • Movies: cacheable
  • Movies 4K: non-cacheable
  • TV Shows: cacheable
  • TV Shows 4K: non-cacheable

============================================================
STEP 3/5: CACHING BEHAVIOR
============================================================

--- OnDeck Settings ---
Episodes to fetch from OnDeck per show [6]: 3
Max age of OnDeck items in days [99]: 30

--- Watchlist Settings ---
Fetch your own watchlist media? [Y/n] y
Episodes to fetch per watchlist show [3]: 3

============================================================
STEP 4/5: USER CONFIGURATION
============================================================

Fetch OnDeck media from other Plex users? [Y/n] y

Found 24 accessible user(s):
  Local/Home (1): Home
    → Can fetch OnDeck + Watchlist
  Remote/Friends (23): REDACTED
    → OnDeck only (Watchlist via RSS)
  Skipped (3):
    • REDACTED (no token)
    • REDACTED (no token)
    • REDACTED (no token)

Skip OnDeck for specific users? [y/N] n

Local users can have their watchlists fetched individually.
  Skip watchlist for Home? [y/N] n

Fetch watchlists from remote/friend users via RSS? [y/N] y

To get the RSS feed URL:
  1. Go to https://app.plex.tv/desktop/#!/settings/watchlist
  2. Enable 'Friends Watchlist'
  3. Copy the generated RSS URL

Enter RSS URL: REDACTED
✓ RSS feed validated

============================================================
STEP 5/5: ADVANCED SETTINGS
============================================================
Move watched media from cache back to array? [Y/n] y

--- Retention Settings ---
Cache retention: How long to keep files on cache before moving back.
(Protects against accidental unwatching or Plex glitches)
Cache retention in hours [12]: 24

Watchlist retention: Auto-expire watchlist items after X days.
(0 = keep forever while on watchlist)
Watchlist retention in days [0]: 45

--- Cache Limits ---
Limit cache usage (e.g., 250GB, 50%, or empty for no limit)
Cache size limit [no limit]:

Eviction mode when cache is full:
  none  - Skip new files (default)
  smart - Evict lowest priority items
  fifo  - Evict oldest items first
Eviction mode [none]: smart
Eviction threshold % [90]: 65
Min priority to evict (0-100) [60]: 71

--- Unraid Notifications ---
  summary - Notify after every run with files moved (default)
  warning - Only notify on warnings and errors
  error   - Only notify on errors
  blank   - Disable notifications
Notification level [summary]: error

--- Playback Handling ---
When someone is actively watching media:
  No  - Skip that file but continue processing others (default)
  Yes - Exit completely and try again next run
Exit if media is actively playing? [y/N] n

--- Performance ---
Concurrent file moves (array→cache) [5]: 5
Concurrent file moves (cache→array) [2]: 5

============================================================
SETUP COMPLETE!
============================================================

  Libraries: 4 configured (2 cacheable)
  Users: 25 (you + 24 others)
  Cache limit: No limit
  Eviction: smart

  Config saved to: /mnt/cache_appdata/apps/PlexCache-R/plexcache_settings.json

------------------------------------------------------------
Run a test (dry-run) now to verify configuration? [Y/n] n

You can run PlexCache with: python3 plexcache_app.py
Or test first with: python3 plexcache_app.py --dry-run --verbose

[StudioNirin]

Yeh that sounds sensible. Might be the kind of thing I revisit in future though, at some point I'm going to do a full test run of going through the setup process and try and do it in the mind of someone seeing it new, and look for ways to simplify or streamline it (if necessary). but it's a future thing, I think the way you've describe it there will be fine for now and skips the complex parts automatically for people who don't need it (which is a good idea).

I'm going to go back and do some more testing on the v2 branch this evening, as I'm hoping to release it asap and chuck up some posts on reddit and maybe even the unraid forums tonight or tomorrow (if all works well). So I'd appreciate if you also went through and checked for any issues we might have missed.

Also something I am going to add to the initial post of this thread, though it might not happen for v3 but might be a v4 thing... it might be nice to move this entire script into instead being a docker container. I've never done it before and have no idea offhand how to go about it, but I think it could be beneficial. Just a thought.

[Brandon-Haney]

I’d second the Docker idea. I don’t have direct experience with it yet, but I’m actively learning it for a Grafana energy-tracking dashboard I’m building. I should have a better handle on it in a few days.

[Brandon-Haney]

I put my future enhancements list here #56

[Brandon-Haney]

@StudioNirin
Question: Should we cache local media assets (posters, artwork) by default?

Some Plex users store local media assets, posters, artwork, NFOs, metadata, right alongside their video files in the same folder. These are tiny (a few KB each) but when Plex needs them it spins up the array to read them, which defeats the purpose of caching.

On one of my dev branches, I currently cache all sibling files unconditionally. I've added a setting to control this with three options: All (subtitles + artwork + NFOs + everything), Subtitles Only, or None (media file only).

My instinct is that All should be the default. If we're already caching a 20GB video file to avoid spinups, it makes no sense to leave a 50KB poster behind that triggers one anyway. It's the logical next step and the cache space cost is negligible.

The alternative is defaulting to Subtitles Only, which matches current main behavior, safer/more conservative, but means users with local assets still get unnecessary spinups until they find the setting and change it.

Switching between modes is safe, changing the setting just affects what gets cached on future runs. Anything already cached gets restored normally with its parent video regardless.

What do you think, default to All, or keep it conservative with Subtitles Only?

[StudioNirin]

@Brandon-Haney

Hmm I hadn't considered those. I dont keep custom posters or anything for any of my files cos I just let plex do all that automatically. I have a handful of subtitles files but I usually remux those into the file itself.

But yeh, if there are any files that will cause plex to spin up if that file is accessed, then it should be cached. I think.

Though im surprised plex will spin up for posters cos they are usually stored in the plex database. And the posters are shown in the main view list on plex which shows up loads of shows/movies that wont be cached... not sure on that one. Not sure why people would keep nfos either.

But subs etc should be cached for sure. I'd say just default to all. As you say the files are tiny so it doesnt matter much.

[Brandon-Haney]

Though im surprised plex will spin up for posters cos they are usually stored in the plex database. And the posters are shown in the main view list on plex which shows up loads of shows/movies that wont be cached... not sure on that one. Not sure why people would keep nfos either.

I'll test on my sever, I've been meaning to look into storing local assets as my plex db backup is almost 500GB so moving some of those assets out would help me.
I'm, not certain plex would read directly from the local assets or not, still researching.

[XenorPLxx]

Not sure if it goes here or into a separate issue, but wasn't really a thing in v2. I have these stale entries reappearing:

Would be nice to have a checkbox to clean them up automatically <maybe alongside the scheduled task?> and include some info in the same report, viewable in Discord webhook report.
As I understand it's just my Sonarr working hard so nothing i need to worry about and I could just leave them there, but 'reasons' don't let me :).
BTW great work moving this to docker with a nice UI 🎉.

[Brandon-Haney]

Not sure if it goes here or into a separate issue, but wasn't really a thing in v2. I have these stale entries reappearing: Would be nice to have a checkbox to clean them up automatically <maybe alongside the scheduled task?> and include some info in the same report, viewable in Discord webhook report. As I understand it's just my Sonarr working hard so nothing i need to worry about and I could just leave them there, but 'reasons' don't let me :). BTW great work moving this to docker with a nice UI 🎉.

@XenorPLxx

You really shouldn't get those warnings very often, I would be interested in reviewing your logs to determine what is causing them. Would you mind providing that along with a screenshot of the Maintenance page for review?

[StudioNirin]

@Brandon-Haney @XenorPLxx

Actually I also get stale entries and timestamps pretty often, though that was also when my moverr was incorrectly set up due to unraid7 update. So ill keep an eye on this too.