WatchState

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

updates

2024-03-08

This update include breaking changes to how we process commands, we have streamlined the command interface to accept some consistent flags and options. Notably, we have added -s, --select-backend flag to all commands that accept it. commands that were accepting comma separated list of backends now needs to be separate option call for example --select-backend home_plex --select-backend home_jellyfin instead of --select-backend home_plex,home_jellyfin.

All commands that was accepting backend name as argument now accepts -s, --select-backend flag. This change is to make the command interface more consistent and easier to use.

Another breaking change is the removal of the -c, --config flag from all commands that was accepting it. This flag was used to override the default servers.yaml file. This was not working as expected as there are more than just the servers.yaml to consider like, the state of cache, and the state of the database. As such, we have removed this flag. However, we have added a new environment variable called WS_BACKENDS_FILE which can be used to override the default servers.yaml file. We strongly recommend not to use it as it might lead to unexpected behavior.

We started working on a Web API which hopefully will lead to a web frontend to manage the tool. This is a long term goal, and it's not expected to be ready soon. However, the Web API is expected within 3rd quarter of 2024.

2023-11-11

We added new feature watch progress tracking YAY which works exclusively via webhooks at the moment to keep tracking of your play progress. As this feature is quite EXPERIMENTAL we have separate command and task for it state:progress will send back progress to your backends. However, Sadly this feature is not working at the moment with Jellyfin once they accept my PR #10573 i'll add support for it. However, The feature works well with both Plex and Emby.

The support via webhooks is excellent, and it's the recommended way to track your progress. However, if you cant use webhooks, the state:import command will pull the progress from your backends. however at reduced rate due to the nature of the command. If you want faster progress tracking, you should use webhooks.

To sync the progress update, You have to use state:progress command, it will push the update to all export enabled backends. This feature is disabled by default like the other features. To enable it add new environment variable calledWS_CRON_PROGRESS=1. We push progress update every 45 minutes, to change it like other features add WS_CRON_PROGRESS_AT="*/45 * * * *" This is the default timer.

On another point, we have decided to enable backup by default. To disable it simply add new environment variable WS_CRON_BACKUP=0.

2023-10-31

We added new command called db:parity which will check if your backends are reporting the same data.

Features

• Sync backends play state (from many to many).
• Backup your backends play state into portable format.
• Receive Webhook events from media backends.
• Find un-matched or mis-matched items.
• Search your backend for title or item id.
• Display and filter your play state. Can be exported as yaml or json.
• Check if your media servers reporting same data via the parity command.
• Track your watch progress via webhooks.

---

Install

create your docker-compose.yaml with the following content:

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}:${GID:-1000}"
        container_name: watchstate
        restart: unless-stopped
        # For information about supported environment variables visit FAQ page.
        # works for both global and container specific environment variables. 
        environment:
            - WS_TZ=UTC # Set timezone.
        ports:
            - "8080:8080" # webhook listener port.
        volumes:
            - ./data:/config:rw # mount current directory to container /config directory.

Create directory called data next to the docker-compose.yaml file. After creating your docker compose file, start the container.

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

Important

It's really important to match the 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" if that works it means you have permissions issues. refer to FAQ to troubleshoot the problem.

Note

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.

Note

To use this container with podman set docker-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.

Adding backend

After starting the container you should start adding your backends and to do so run the following command:

Note

to get your plex token, please visit this plex page to know how to extract your plex token. For jellyfin & emby. Go to Dashboard > Advanced > API keys > then create new api keys.

$ docker exec -ti watchstate console config:add

This command is interactive and will ask you for some questions to add your backend.

Managing backend

To edit backend settings run

$ docker exec -ti watchstate console config:manage -s backend_name

Importing play state.

What does Import or what does the command state:import means in context of watchstate?

Import means, pulling data from the backends into the database while attempting to normalize the state.

To import your current play state from backends that have import enabled, run the following command:

$ docker exec -ti watchstate console state:import -v

This command will pull your play state from all your backends. To import from specific backends use the [-s, --select-backend] flag. For example,

$ docker exec -ti watchstate console state:import -v -s home_plex -s home_jellyfin 

Note

Now that you have imported your current play state enable the import task by adding the following environment variables to your docker-compose.yaml file WS_CRON_IMPORT=1. By default, we have it disabled. for more environment variables please refer to Environment variables list.

Supported import methods

Out of the box, we support the following import methods:

• Scheduled Task. Cron jobs that pull data from backends on a schedule.
• On demand. Pull data from backends on demand. By running the state:import & state:export command 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.

---

Exporting play state

What does export or what does the command state:export means in context of watchstate?

Export means, sending data back to backends, while trying to minimize the network traffic.

To export your current play state to backends that have export enabled, run the following command

$ docker exec -ti watchstate console state:export -v

This command will export your current play state to all of your export enabled backends. To export to specific backends use the [-s, --select-backend]flag. For example,

$ docker exec -ti watchstate console state:export -v -s home_plex -s home_jellyfin 

Note

Now that you have exported your current play state, enable the export task by adding the following environment variables to your docker-compose.yaml file WS_CRON_EXPORT=1. By default, we have it disabled. for more environment variables please refer to Environment variables list.

---

FAQ

Take look at this frequently asked questions page. to know more about this tool and how to enable webhook support and answers to many questions.

Social contact

If you have short or quick questions, you are free to join my discord server and ask the question. keep in mind it's solo project, as such it might take me a bit of time to reply.

Donate

If you feel like donating and appreciate my work, you can do so by donating to children charity. For example Make-A-Wish. I Personally don't need the money, but I do appreciate the gesture. Making a child happy is the best thing you can do in this world.