Proposed Features, and BugFixes to-do list - Discussion and Feedback

[StudioNirin]

Features/Proposals:

1. Making it so that files don't actually get moved off the Array, but instead just get renamed and copied to cache. Reduces write operations. (Main discussion thread for this here) (Worked on by @Brandon-Haney )

2. Make it so that the Exclude file has a marker, so that a user can manually add in entries above that marker that are never altered (or read) by plexcache. I believe Mover Tuner only allows for a single Exclude file, so this will allow this file to function in that way for users that need it. (Worked on by @StudioNirin )

3. Figure out a way to have the exclude file also have files that are newly marked as 'needed on cache', but were already on cache (new downloads etc) and not being moved from the array. The issue comes in with the current option of "watched files get moved back to array" as you might want those files to stay on cache (if they're recent downloads) so other users can watch them.
   (Already part of 1 above).

4. Possibly implementing a proper auth token specific to the script. Thoughts on the below approach?

Plex PIN-Based Authentication
Alternative authentication method using Plex's official PIN-based OAuth flow.

Workflow:

Script generates a PIN via POST https://plex.tv/api/v2/pins
User opens URL in browser: https://app.plex.tv/auth#?clientID=xxx&code=xxx
User logs into Plex and clicks "Allow"
Script polls GET https://plex.tv/api/v2/pins/<pinID> until token is returned
Token is saved for future API calls

Pros:
Works on any system
No manual web view token needed
User explicitly authorizes the app
Official Plex authentication method

Cons:
Requires user interaction (open browser, login)
On headless servers, user must copy/paste URL to another device
More complex
Integration: Could offer as option during setup:

How would you like to authenticate?
1. Auto-detect token from Preferences.xml (Unraid only *might not be working as expected*)
2. Authenticate via Plex.tv (opens browser)
3. Enter token manually

5. Addition to the new in v2.0 'data storage limit' feature, where if it detects plexcache is using that much space, it prioritises removing watchlist items in favour of onDeck items or something.

6. Remove Watchlist_Cache file completely.... is there actually any use for it? Whenever I run the script I want it to be accurate and up to date. I have mine set to 6 hours, and the script runs once or twice a day, so it's always 'expired' anyway. Why bother keeping it? Does anyone have a use for this existing?

7. Remove 'Watched_Cache' file completely. Again, I'm not sure it has any real use. Even less so than the watchlist cache file. The watchlist is at least useful, it just probably doesn't need to be stored for future runs. The watched file seems to have no benefit.

Bugfixes:

1. Some of the Episode/Show logic looks for 'Season X' as a folder marker, but with sonarr some episodes are also in 'Specials' so the logic needs to be updated to account for it. Maybe add 'Series X' as another option too. - MERGED.
2. Files moved from cache to array seem to be getting marked as 'root' instead of 'nobody' which is what unraid usually uses for media permissions. There's a build in unraid tool to correct the ones that have already been done, but would be good to fix it going forwards.

[StudioNirin]

New proposal -

Remove Watchlist_Cache file completely.... is there actually any use for it? Whenever I run the script I want it to be accurate and up to date. I have mine set to 6 hours, and the script runs once or twice a day, so it's always 'expired' anyway. Why bother keeping it? Does anyone have a use for this existing?

[Brandon-Haney]

I think there might be a misunderstanding about what watchlist_cache_expiry actually does.

It controls how often the script calls the Plex.tv API to refresh the watchlist - NOT how long files stay on your cache drive.

With your setting of 720h (30 days):

• For 30 days, the script uses a stale JSON file instead of fetching current watchlist data
• If you add something new to your watchlist, it won't be cached until that 30 days expires
• If you remove something from your watchlist, the script won't know for 30 days

What you're describing (keeping files on cache for X days then moving back) is actually controlled by cache_retention_hours - which is a completely separate setting. (Also on the test exclude branch, not part of main at this time)

So the question remains: does anyone actually want the script to use stale watchlist data instead of fetching fresh data? The only benefit is reducing API calls to plex.tv to avoid rate limiting, but for most users running once or twice daily, this seems unnecessary.

[Brandon-Haney]

To follow-up, I agree that this isn't needed for users running every 6, 12, 24hrs. If a user was running every few mins then we would need something like this.

[Brandon-Haney]

@thepilzkopf Thinking more on this,

New setting: watchlist_retention_days (e.g., 30 days)

How it works:

• Plex API provides watchlistedAt timestamp for each item
• Files auto-expire from cache X days after being added to watchlist, even if still on watchlist
• Multi-user aware: if another user adds the same item later, the timer resets to their add date
• Works alongside existing cache_retention_hours which protects against accidental removals (buffer time if needed)

Example: You add a movie on Day 1, it gets cached. 30 days later it moves back to array automatically. If you still want it cached, remove and re-add to reset the timer.

I think this is in-line with your ask.

[StudioNirin]

I think we would recommend users not running this script that frequently. The main benefit of the script is reducing spin up times of the array. If they run it every few minutes then the array will spin up randomly throughout the day.

The best use (I think anyway) is to run the script at a fixed time of day and schedule all the other array tasks like mover etc at a similar time (staggered slightly) so that the array wakes up at say midnight, is busy for an hour, and then spins down for the rest of the day.

If they run the script more often than every 6 hours they may as well not bother using it, as the array will be spinning most of the time already and there will be little or no benefit.

I could be wrong on this of course, its just how it seems

On the subject of the watchlist retention, I would say that all watchlist items should be cached because in theory they will get watched... but I also know there are people who have watchlisted stuff months ago and never got around to it. So yeh probably worth it. However I would perhaps instead not set it as a firm timer (eg X number of days) but tie it to the space used on the cache.

Eg. If space used is more than 50%, check watchlist timestamps, remove anything older than 12 months.
If space used gets over 75%, remove watchlist items older than 6 months.
Could even add the check to include onDeck files. There's already a setting for checking the date onDeck (default 99 days I believe) so have it that :
if space used goes over 75%, remove watchlist items older than 6 months and remove onDeck items older than 3 months.

Or something. Just because if the users aren't using up much space, then theres no need to be removing watchlist items just because theyre older. Theyre still more likely to be randomly watched than most other items.

Not sure that all made sense but hopefully it did haha

[thepilzkopf]

Thanks for the explanation, this was unclear for me.

@thepilzkopf Thinking more on this,

New setting: watchlist_retention_days (e.g., 30 days)

How it works:

• Plex API provides watchlistedAt timestamp for each item
• Files auto-expire from cache X days after being added to watchlist, even if still on watchlist
• Multi-user aware: if another user adds the same item later, the timer resets to their add date
• Works alongside existing cache_retention_hours which protects against accidental removals (buffer time if needed)

Example: You add a movie on Day 1, it gets cached. 30 days later it moves back to array automatically. If you still want it cached, remove and re-add to reset the timer.

I think this is in-line with your ask.

Yep this sounds nice.
But For me just a nice to have - I use only for me, not for external users. So I know now how to handle the watchlist

[Brandon-Haney]

@StudioNirin

Proposal: Remove "Watched" media processing (seeking feedback)

I'm reviewing the logic around how PlexCache-R decides when to move files back to the array, and wanted to get community input on a proposed simplification.

Current behavior:

The script currently fetches three types of media from Plex:

1. OnDeck - actively being watched
2. Watchlist - user intends to watch
3. Watched - user's entire watch history

The "Watched" fetch pulls your full watch history (potentially thousands of items) to identify files that were recently marked as watched and should be moved back to the array.

The problem:

Fetching the entire watched history seems redundant. On a typical server, this could be 2,000-3,000+ items, but only a handful are actually on the cache drive.

My thinking:

When a file falls off OnDeck, it happens for one of these reasons:

• User finished watching -> Plex marks as watched -> removed from OnDeck
• User manually marked as unwatched -> removed from OnDeck
• For TV: episode finished -> next unwatched episode takes its place

In all cases, the file is no longer being actively accessed. The reason it left OnDeck doesn't matter for the caching decision, what matters is that it's no longer on OnDeck or Watchlist.

Proposed change:

Remove the "Watched" processing entirely. The logic simplifies to:

1. File on OnDeck or Watchlist -> keep on cache
2. File on neither -> start retention timer -> move to array after retention expires

The exclude list already tracks what's on cache, and get_files_to_move_back_to_array() already checks "is this file still on OnDeck/Watchlist?", so we don't need the watched list to make this decision.

Benefits:

• Faster script execution (no fetching thousands of watched items)
• Simpler logic
• Less API calls to Plex

Question for the community:

Is there a use case I'm missing where knowing the watched status specifically matters for caching decisions? Or does the simpler "on OnDeck/Watchlist = keep, otherwise = move back" logic cover your needs?

[Brandon-Haney]

I think we can let this one sit for awhile, I'm at a fairly good place with this exclude branch so I just need testing from you to catch any edge cases or broken parts. Pull the most recent version when you have time and try to break something. My tests have been successful now. (Add/remove ondeck, add/remove watchlist, radarr/sonarr file updates)

[StudioNirin]

2025-12-04 06:32:24,833 - INFO - Adding file to array: /mnt/user/media/tv/series/Star Trek Strange New Worlds (2022)/Season 1/Star Trek Strange New Worlds - S01E03 - Ghosts of Illyria (Bluray-1080p x265).mkv
2025-12-04 06:32:24,834 - CRITICAL - Error moving media files to array: FileNotFoundError: [Errno 2] No such file or directory: '/mnt/user/media/movies/movies/Wreck-It Ralph (2012)/Wreck-It Ralph (2012) (WEBDL-1080p x264).mkv'

Still getting the same error. I can obviously manually fix it but I'm still not sure why it keeps picking it up. I noticed you had an update for "only process watched files that are on cached drive" but is that code just going by any file that's on the cached drive, and not files that are in the 'needed by plexcache' lists?

[Brandon-Haney]

@StudioNirin could you run python3 plexcache_app.py --v and share the full log, so I can investigate the Wreck-it Ralph? Maybe its in another one of your posts so I will look for that as well.

Edit: I found it, looks like its a bug with the watched json file, I believe if you run python3 plexcache_app.py --v --skip-cache the error would be gone.

The issue was in how we load from the watched cache when it hasn't expired. Previously, we blindly added all entries from plexcache_watched_cache.json to the move queue without checking if the files still exist on the cache
drive.

What was happening:

1. Wreck-It Ralph was cached and added to plexcache_watched_cache.json
2. File was upgraded (different quality/name) on cache (Radarr)
3. Cache hadn't expired, so script loaded stale path from JSON
4. Script tried to move non-existent file -> FileNotFoundError

The fix:

• When loading from watched cache, we now verify each file exists on the cache drive
• Stale entries are logged as warnings and removed from the JSON
• Valid entries are processed normally

Commit: Brandon-Haney@e8a709b

[StudioNirin]

Ok new version seems to be working. I had a ton of stale entries. However from what you wrote, it seems that the watched cache will now delete all entries that aren't currently on the cache-drive. Which means (I think?) that it'll end up the same as the exclude list (give or take). Another reason it probably doesn't need to exist lol.

I'll run some more tests during this evening and report back.

[Brandon-Haney]

Yea, I agree with getting rid of the watched cache file and that will be easy to do later.

[Brandon-Haney]

@StudioNirin, please review the below. I am going to make a new branch to work on this but I want to ensure it aligns with your thoughts.

Proposed: Smart Cache Eviction System

The Problem

Currently, when the cache fills up, PlexCache-R simply skips new files (first-come-first-served). Files only move back to the array when they're no longer on OnDeck/Watchlist. This means:

• A movie cached while fresh on a watchlist continues taking space even after aging past watchlist_retention_days (retention only blocks new caching, doesn't evict existing items)
• No way to make room for high-priority content without manually intervening
• Files can "churn" - moving back and forth unnecessarily

Proposed Solution: Priority-Based Eviction

Assign each cached file a priority score (0-100). When cache approaches capacity, automatically evict the lowest-scoring items first to make room for higher-priority content.

Priority Scoring Factors

Factor	Impact	Why
OnDeck vs Watchlist	+20 for OnDeck	You're actively watching it
User Count	+5 per user (max +15)	Multiple users = popular
Cache Recency	+5 to +15	Recently cached = recent interest, avoid churn
Watchlist Age	+10 if fresh, -10 if >30 days	Old watchlist items often forgotten
Episode Position	+15 current, +10 next, -5 if far ahead	Next episode matters most

Example Scores

Scenario	Score
OnDeck episode, 3 users watching, cached today	100 (keep)
Watchlist movie, 2 users, added 3 days ago	75 (keep)
Watchlist movie, 1 user, added 45 days ago	45 (evict first)

New Settings

{
  "cache_eviction_mode": "smart",           // "smart", "fifo", or "none"
  "cache_eviction_threshold_percent": 90,   // Start evicting at 90% full
  "eviction_min_priority": 60               // Only evict items below this score
}

Key Design Decisions

1. Opt-in by default - eviction_mode defaults to "none" so existing behavior unchanged
2. Threshold-based - Only evicts when cache exceeds threshold (e.g., 90%)
3. Protected floor - Items above eviction_min_priority (60) are never evicted, even if cache is full
4. Uses existing metadata - Leverages data we already track (timestamps, watchlist users, source)

Prerequisite: OnDeck User Tracking

Currently, we track which users have items on their Watchlist but not OnDeck. To enable the "User Count" factor for OnDeck items, we need to:

• Modify get_ondeck_media() to return user info (data is already available in API, just discarded)
• Create OnDeckTracker class similar to existing WatchlistTracker

This is a refactor of existing code, not a new API integration.

Diagnostics

New --show-priorities flag to see scores without taking action:

Score | Source    | Days Cached | File
------+-----------+-------------+---------------------------
  100 | ondeck    |           1 | Foundation S02E05.mkv
   75 | watchlist |           5 | Poor Things (2023).mkv
   45 | watchlist |          45 | Barbie (2023).mkv  ← Would evict

Questions for Discussion

1. Scoring weights - Do the priority factors and weights make sense? Should OnDeck bonus be higher/lower than +20?
2. Default threshold - Is 90% a good default for when to start evicting? Too aggressive? Too conservative?
3. Minimum priority floor - Should 60 be the default cutoff, or should we allow evicting higher-priority items when really pressed for space?
4. Additional factors - Are there other signals we should consider? (e.g., file size, genre, time of day added)
5. FIFO mode - Worth implementing a simple "oldest first" mode as an alternative to smart scoring?

Looking for any feedback before I start implementation

[StudioNirin]

@Brandon-Haney
Ok I'm going to say two things -

1. This is a fantastic idea and I love it. There's going to need to be some tweaks to the scores and weightings as you suggest, but other than that it's great.
2. I really think it'll be worth putting a pause on it for a couple days until we get all the v2.0 stuff ironed out and released. Then this feature can be the core of the following release.

I only say this because I think we are pretty close to getting v2 out there, and then once it's out I can focus on ironing out the readme and wiki while you are tinkering this this new smart caching system.

I'm not even sure if we would need a couple of days to get 2.0 released, Your latest PR seems to be pretty much there, but I noticed you were still committing bugfixes to it. Once you're done with that just let me know and I'll do a full test run on my setup here and then I'd probably say merge and release v2 (assuming no obvious bugs pop up)

[StudioNirin]

As for some immediate feedback on the score weightings:

Priority Scoring Factors

Factor	Impact	Why
OnDeck vs Watchlist	+20 for OnDeck	Anyone actively watching it
User Count	+5 per user (max +15)	Multiple users = popular
Cache Recency	+5 to +15	Recently cached = recent interest, avoid churn
Watchlist Age	+10 if fresh, 0 if >30 days, -10 if >60 days	Old watchlist items often forgotten
onDeck Age	+10 if recently watched, 0 if >30 days, -10 if >60 days	Maybe items that haven't been watched lately get lower priority. Though this might interact with our existing 99 days setting.
Episode Position	+15 current, +10 next, +0 if far ahead	I think make this so +10 = the next X episodes

for episode position its tricky, cos a series might be onDeck and not watched for a while for various reasons, but when someone comes back to it they're then likely to watch several episodes in a row. However I think doing something like +10 for X episodes, and have X being equal to half your number_episodes setting. So for me I have 12 episodes cached ahead, so the next 6 would get +10 and then after that they'd get 0. I don't think they should get a negative, as they should only be removed if the pressure is high enough.

I think the balance should always err towards emptying watchlist files first, and only when even the latest watchlist files are gone should onDeck items be removed. Maybe have a balancing point in there so that "brand new" watchlist files have priority over onDeck items that haven't been watched in forever (but then we already have a 99 day expiry for onDeck items I think? We would have to figure out those current settings and merge them so we don't have overlaps/redundancies).

[Brandon-Haney]

@StudioNirin This is exactly what I was looking for, yes I agree lets focus on 2.0 merging to main then we can take on the new work. I added a few minor fixes today as I ran into some issues when I was testing on my system. I will give it a longer test tomorrow but I think now is a good time for you to review the PR and test it yourself.