← Directory

WatchState

Self-hosted service that syncs per-user play state across Plex, Jellyfin, and Emby media servers.

  • Backup
  • Media Servers
  • Tools & Utilities
Self-hosted service that syncs per-user play state across Plex, Jellyfin, and Emby media servers. It keeps watch progress consistent between the three backends without relying on third-party services, so homelab users running multiple media servers don't need an external bridge.

Platform availability

Available on 2 of 9 platforms

  • Unraid
  • TrueNAS (not listed)
  • Umbrel (not listed)
  • ZimaOS (not listed)
  • Proxmox
  • Helm (not listed)
  • Mac (not listed)
  • Windows (not listed)
  • Linux (not listed)

Health score?A 0-100 score computed nightly from four factors: maintained (40%: recent commits and steady activity), popular (25%: GitHub stars, log scale), easy to install (20%: platforms, install notes, setup guides, Docker image) and light to run (15%: minimum RAM, ARM support). When the source code has been checked, a fifth factor, security check (20%: automated scan for committed secrets, unsafe desktop-app settings, known-vulnerable dependencies and project hygiene; any serious finding caps it at 20), is added. Factors without data are left out and the rest are rescaled.

76/100 Good

Maintained
100last commit 12 days ago
Popular
641,577 GitHub stars
Easy to install
452 install platforms, install notes, Docker image
Light to run
No data

Based on 3 of 4 factors.

Availability: platform listings confirmed today, links checked 7 days ago

GitHub stars
1,577
Open issues
0
Last commit
2026-10-03
Latest release
v1.10.8
License
MIT
Activity
declining

Checked 6 days ago - source: GitHub (arabcoders/watchstate)

Resources & Compatibility

ARM (e.g. Raspberry Pi) is supported.

Checked 17 days ago - source: Docker Hub image tags and published docs

First-install notes

  • Create the first admin account Before using the app, create the initial WatchState admin account with a username and password. You need this account to log in and manage the app, and you can only create it before one already exists. source
  • Check service paths and user If you start WatchState as a background Linux service, confirm it points to the correct PHP program (the tool that runs WatchState) and the actual WatchState folder, and runs as the watchstate user. Wrong paths or permissions make the service fail to start. source
  • Preview user matches first Use the identity provisioning preview to see which Plex or Jellyfin users match your WatchState identities (the named people you want to track) and which are unmatched. Fix unmatched users before applying, or their activity won’t be attributed correctly. source

Fetched 17 days ago - each note links to its source

Alternatives

No alternatives collected yet.

Common questions

How should I mount WatchState data in Docker?

Create a local data directory and mount it to /config in the container, for example ./data:/config. The default compose example maps host port 8080 to container port 8080, and you can set the container user with UID.

What happens to existing records when path matching is enabled?

Path matching is enabled by default and generates guid_path values for new and refreshed movie and episode records unless WS_GUID_PATH_ENABLED is disabled. Existing records require a full import before they can match by path.

How do I create the initial account and connect media server users?

Create the first WatchState admin account with a username and password before one already exists. Use the identity provisioning preview to see which Plex or Jellyfin users match your identities, and fix unmatched users before applying so their activity is attributed correctly.

What should I check if WatchState fails as a systemd service?

Confirm the service points to the correct PHP program and the actual WatchState folder, and runs as the watchstate user. Wrong paths or permissions can make the service fail to start.

How do I audit media record problems in WatchState?

Use Media Health as the central place to audit media record problems, replacing the old parity, duplicate-reference, and file-integrity views. It reports backend metadata coverage, GUID conflicts, duplicate GUIDs, duplicate file references, structural metadata disagreement, path disagreement, weak matches, and optional local file checks.

Where do I get the webhook URL if I use the Docker installation video?

Copy the webhook URL directly from the backends page because the video has a small mistake about the webhook URL.

Answers sourced from github.com, github.com, github.com

Community

Collected 16 days ago - public community threads