WatchState

This tool primary goal is to sync your backends users play state without relying on third party services, out of the box, this tool supports Jellyfin, Plex and Emby media servers.

Updates

2026-05-25

Path matching is now available in v1.8.5+. It lets items match using a GUID source derived from the media path, which helps when your backends share the same media files but have unreliable or inconsistent external IDs. See the path matching guide for setup and backfill instructions.

2026-04-30

WatchState now uses the new versioned v02 database schema. On first boot after updating, startup may take a bit longer than usual while legacy databases are imported, migrations are applied, and indexes are rebuilt.

During that upgrade, the old database files are kept as .migrated safety copies. Once the first boot finishes and you have confirmed everything looks good, you can delete those .migrated files if you want to reclaim the space.

Please refer to NEWS for the latest updates and changes.

Features

• Multi-users support via identities.
• Sync backends play state (many-to-many or one-way).
• Backup your backends play state into portable format.
• Receive webhook events from media backends.
• Find un-matched or mis-matched items.
• Search your backend metadata.
• Check if your media servers reporting same data via the parity checks.
• Sync your watch progress/play state via webhooks or scheduled tasks.
• Check if your media backends have stale references to old files.

If you like my work, you might also like my other project YTPTube, which is simple and to the point yt-dlp frontend to help download content from all supported sites by yt-dlp.

Install

If you prefer video format AlienTech42 YouTube Channel had a video about installing WatchState using unraid at this link. Much appreciated.

PS: I don't know the channel owner, but I appreciate the effort. There is small mistake in the video regarding the webhook URL, please copy the URL directly from the backends page. And this tool does support multi-users.

First, start by creating a directory to store the data, to follow along with this setup, create directory called data at your working directory. Then proceed to use your preferred method to install the tool.

Via compose file.

create your compose.yaml next to the data directory, and add the following content to it.

services:
    watchstate:
        image: ghcr.io/arabcoders/watchstate:latest
        # To change the user/group id associated with the tool change the following line.
        user: "${UID:-1000}:${UID:-1000}"
        container_name: watchstate
        restart: unless-stopped
        ports:
            - "8080:8080" # The port which the watchstate will listen on.
        volumes:
            - ./data:/config:rw # mount ./data in current directory to container /config directory.

Next, to run the container, use the following command

mkdir -p ./data && docker compose up -d

Via docker command.

mkdir -p ./data && docker run -itd --name watchstate \
          --user "${UID:-1000}:${GID:-${UID:-1000}}"  \
          --restart unless-stopped -p 8080:8080 \
          -v ./data:/config:rw \
          ghcr.io/arabcoders/watchstate:latest

[!IMPORTANT] It's really important to match the user:, --user to the owner of the data directory, the container is rootless, as such it will crash if it's unable to write to the data directory.

It's really not recommended to run containers as root, but if you fail to run the container you can try setting the user: "0:0" or --user '0:0' if that works it means you have permissions issues. refer to FAQ to troubleshoot the problem.

Unraid users

For Unraid users You can install the Community Applications plugin, and search for watchstate it comes preconfigured. Otherwise, to manually install it, you need to add value to the Extra Parameters section in advanced tab/view. add the following value --user 99:100.

This has to happen before you start the container, otherwise it will have the old user id, and you then have to run the following command from terminal chown -R 99:100 /mnt/user/appdata/watchstate.

Podman instead of docker

To use this container with podman set compose.yaml user to 0:0. it will appear to be working as root inside the container, but it will be mapped to the user in which the command was run under.

Management

After starting the container, you can access the WebUI by visiting http://localhost:8080 in your browser.

[!NOTE] Note, For the first time, you will be prompted to create a new system user, this is a one time operation.

If you want WatchState to match items using local media paths, see the path matching guide.

To add your backends, please click on the help button in the top right corner, and choose which method you want one-way or two-way sync. and follow the instructions.

Once you have added your backends and imported your data you should see something like

Supported import methods

Currently, the tool supports three methods to import data from backends.

• Scheduled Tasks.
  • A scheduled job that pull data from backends on a schedule.
• On demand.
  • Pull data from backends on demand. By running the import task manually.
• Webhooks.
  • Receive events from backends and update the database accordingly.

[!NOTE] Even if all your backends support webhooks, you should keep import task enabled. This help keep healthy relationship and pick up any missed events. For more information please check the webhook guide to understand webhooks limitations.

FAQ

Take look at this frequently asked questions page, or the guides for more in-depth guides on how to configure things.

Social channels

If you have quick questions or would like to chat with other users, you can join the Discord server. Please note that this is a solo project, so replies may take some time. I’m based in the UTC+3 timezone.

Donate

If you’d like to show appreciation for my work, please note that I don’t accept donations. Instead, I encourage you to donate to a children’s charity of your choice. For example, The International Make-A-Wish foundation.

Disclaimer

AI-based tools may have been used to assist with parts of this project. Regardless of how a change is produced, every change is reviewed and approved by the human maintainer before it is included.