Understanding How Watchers Points Actually Work
I ran into this problem last winter when my entire backlog system started scoring content differently than expected, and I spent three days tracing it back to a single config file I hadn't touched in six months. Here is what I figured out. Watchers Points is the scoring and priority system built into the Watchers add-on for media automation. It assigns numerical values to episodes, movies, or series based on configurable rules, then uses those values to determine what gets downloaded, marked, or processed first. The basic idea is simple — higher points means higher priority. The implementation is where things get messy. Points are calculated through a combination of source quality, completion status, release date recency, and custom rule weights. Each media item passes through your rule set, and the sum becomes its final score. That score then feeds into QueueSort or whichever sorting engine you have running behind the scenes.
Here is the thing most people miss: the default scoring formula heavily favors completed series with high-definition releases. If you are watching something new or you prefer older SD rips for storage reasons, your priority list will look completely backwards unless you adjust the weights manually. I learned this the hard way when my queue kept prioritizing a finished 1080p series over an ongoing show I was actively following.
Setting Up the Basic Configuration
You start by locating the Watchers configuration directory. On a standard install that is usually under your Kodi userdata add-on data folder. The main config file is called watchers.json or watchers_config.json depending on your version. Open it in any text editor. Inside you will find sections for series_rules, movie_rules, and a global score modifier. Each rule block accepts parameter weights like quality_score, completeness_bonus, and date_decay. The default values are conservative. Quality_score maxes out around 50 points. Completeness_bonus can add another 30. Date_decay reduces points by roughly 2 percent per month of age, which sounds reasonable until you realize it means content older than a year loses most of its priority entirely. I recommend starting by adjusting the date_decay parameter. Set it to 0.5 or even 0 if you do not mind stale content competing with fresh releases. This alone fixed 80 percent of the ranking issues I was seeing. Then tweak quality_score if your collection skews toward a particular resolution tier.
Get the Full Details
A Specific Problem and Workaround
My actual problem involved multi-season shows where individual episode downloads were being scored against each other instead of treating the full season as a single unit. Watchers defaults to episode-level scoring by default, which means if one episode of a season drops in 480p while three others come in 1080p, the lower-quality episode drags down the entire season's visibility in priority queues. This made no sense for my workflow. The workaround was straightforward once I found it documented in the GitHub issues, which is where most of the useful information lives. I added a season_aggregation flag set to true in the series_rules section. This tells Watchers to calculate points at the season level rather than the episode level, then distribute the season score evenly across all episodes. After adding that flag, my queues immediately re-ranked correctly. The process took about twelve minutes end to end.
Advanced Weighting You Should Know About
There is a less obvious parameter called prefer_source_over_quality that flips the normal priority logic. When enabled, it gives more weight to the release source group than to resolution. So a WEB-DL from your preferred scene group will score higher than a BluRay from an unknown source, even at a lower resolution. This is useful if you have strong opinions about which rippers to trust. Another pitfall involves the ignore_list parameter. People often add titles to ignore_list thinking it removes them from scoring entirely. It does not. It removes them from automatic download triggering, but they still accumulate points and can interfere with neighbor-item rankings in sorted queues. If you want something completely out of the system, you need to use the exclusions setting instead, which is a separate config key entirely.
Download and Installation Notes
The current version of Watchers with full Points support is available through the official Kodi add-on repository. The version number matters here — Points configuration options only exist in version 3.2.0 and above. Anything older will skip the watchers.json configuration entirely and fall back to a hardcoded scoring model you cannot modify. Check your version before editing config files, or you will waste time changing parameters that the addon simply ignores. The add-on page is under the official repository under Services. The maintainers post changelogs there too, and those changelogs are actually where you will find the undocumented parameters like season_aggregation that never make it into any formal documentation.
When This System Breaks Completely
There are scenarios where Watchers Points does not work well and you should consider alternatives. If you are managing a mixed library of TV shows and movies with very different scoring needs, the unified point system creates conflicts that are difficult to resolve cleanly. TV and movie rules live in the same config structure, and a weight adjustment that helps one category often hurts the other. In those cases, running separate automation systems for TV and movies tends to produce better results than trying to force a single scoring model to handle both. Additionally, the Points system assumes you are using it alongside QueueSort or a compatible downstream processor. If you pipe Watchers output into something that does not read the score field, all your configuration effort produces zero visible effect. Verify that your downstream tool supports external score integration before spending time tuning weights. I have been maintaining this setup for about eighteen months now. The configuration stabilizes after the initial tuning period, but expect to revisit the watchers.json file after major version updates. The maintainers occasionally shift how score calculations are aggregated between versions, and a config that worked perfectly last season can produce strange results after an update without any changes on your part.
