Watchers Scale Manual

Understanding How Watchers Scale Manual Actually Works

Most people who come across this tool are dealing with large media libraries and realize their automation setup is hitting limits they didn't expect. The basic idea is straightforward — you're managing how watched/unwatched status scales across devices, libraries, or sync layers. But the manual configuration part is where things get messy, and most guides skip over the actual pain points. I spent about three weeks debugging a scenario where my Plex server was marking shows as watched on my main library but not syncing to the secondary server that ran our household. The issue wasn't the watcher — it was the scale configuration. When you have multiple library servers behind a reverse proxy, each instance maintains its own watched state by default. You have to tell Watchers to treat them as a single scale, or you end up with duplicate content flags scattered across instances. The installation itself is simple if you're on Linux. Clone the repository, install the Python dependencies from requirements.txt, then create your config file. I'd recommend starting with a minimal config before adding scale rules. There's a sample config in the repo — don't ignore it. The defaults are sane, and modifying them without understanding what they do is how you accidentally unmark everything as unwatched across your entire library.

The Scale Configuration Breakdown

Here's what actually matters in the config file, in order of impact: Library source mapping: You need to define which libraries belong to which scale group. A single Watchers instance can monitor multiple library sources, but if you don't map them explicitly, scaling won't happen correctly between them. The field is called "scale_group" and it defaults to null, which means no scaling at all — the watcher runs in isolation per library. Sync interval: This controls how often watched state gets pushed between scaled instances. The default is 300 seconds, which is fine for most setups but can cause noticeable lag if you're watching on mobile and expecting it to reflect immediately on the main server. I changed mine to 60 seconds. Your API rate limits may object.

Conflict resolution: This is the part nobody reads. When two instances mark the same episode differently at the same time, Watchers needs a rule. The default is "latest wins," which sounds reasonable until you realize it means whichever server happened to write last overrides everything else, regardless of accuracy. If you've got a trusted primary server, set conflict_resolution to "primary" and specify which instance is primary. This saved me from a situation where a test server was constantly overriding watched status on my production library.

A Problem You'll Probably Hit

Mid-season show progress tracking breaks under certain conditions. If you add new episodes to your library after Watchers has already processed previous episodes in that show, the scale doesn't automatically know about the gap. Episodes between the last watched and the newest added can end up in a limbo state — neither marked watched nor unwatched properly. I ran into this with The Bear season 3, which dropped all episodes at once while my watcher was in the middle of processing season 2. The workaround is to clear the affected show's cache entry and let Watchers re-scan it. In practice, that means removing the show from the watched database manually — it's stored in a SQLite file at ~/.watchers/watched.db — then letting the next sync cycle rebuild it. Don't delete the whole database unless you want to reprocess your entire library. It takes roughly 4 hours for a 2000-episode library on a standard NAS setup, depending on disk speed and API limits.

Common Pitfalls Beginners Miss

The first thing people overlook is that Watchers Scale Manual only syncs watched status, not playback position. If you're expecting resume-point synchronization between scaled instances, that's not happening. You need a separate tool for that — I use JustWatch for position sync alongside Watchers for status sync. Two different problems, two different solutions. The second thing is timezone handling. If your servers are in different timezones, the timestamp comparisons Watchers uses to determine "most recently watched" will produce incorrect results. I've seen configs where an episode in Tokyo gets marked as unwatched on a New York server because the timestamp comparison fails across zones. Set all your servers to UTC and the problem disappears entirely. A third nuance: API rate limits. Watchers makes a lot of small API calls when scaling across multiple libraries. If you're using themdb or tvdb APIs at the free tier, you'll hit rate limits during initial sync. The tool will retry, but the initial sync can take significantly longer than documented. I'd budget twice the expected time for a first run through a large library, especially if you're pulling metadata as well as watched status.

When This Approach Fails Completely

Watchers Scale Manual isn't built for real-time sync scenarios. If you need watched status to update within seconds across all instances, this tool will frustrate you. The architecture is polling-based, not event-driven. There's no websocket integration or push notification system. Even at the fastest sync interval, you're looking at 60-second gaps minimum, and realistically more like 2-3 minutes in normal operation. For those cases, consider a different approach entirely. Jellyfin with its native sync plugin handles real-time watched state propagation better because it's built into the server architecture rather than layered on top. If you're already on Plex, the official Plex sync features combined with Watchers for bulk management is probably your best path. Watchers fills a specific niche — it's good at batch updates and complex library management across heterogeneous setups. It's not a real-time solution, and nobody seems to make that clear in the documentation.

What to Do Before You Deploy

Test with a single episode first. I can't stress this enough. Add one episode to one library, configure the scale, and watch what happens. Check the SQLite database directly to see what's being recorded. The logging output is decent but not exhaustive — you'll miss edge cases unless you're also checking the database state manually. Back up your watched.db file before making any config changes. I lost about six hours of progress data the first time I adjusted the scale_group setting because I didn't back up. It's a small file, maybe 50MB for a full library, but it contains every watched/unwatched decision Watchers has made. Losing it means either re-watching content to repopulate it or spending hours reprocessing metadata and status separately. The configuration file supports comments, so leave notes in it. Future you will thank present you when you come back six months later trying to remember why you set a particular scale_group value or conflict resolution rule. I still have configs from 2023 with handwritten notes explaining decisions I'd completely forgotten about.