🎬 WatchState

Synchroniseur de watch state entre Plex, Jellyfin, Emby, Kodi et autres : garde une seule source de vérité sur ce que tu as regardé et où tu en es.

📋 Informations Générales

Attribut	Valeur
Nom	WatchState
Slug	app-watchstate
Description	Synchronise l'historique de visionnage, la progression, les notes et watchlists entre plusieurs serveurs média
Site officiel	https://watchstate.app/
Repository	https://github.com/theJinFei/watchstate
Stars	1 442 ⭐
Licence	MIT
Langage principal	PHP
Catégorie	Media Streaming
Tags	[catalogue, media-streaming, watchstate, sync, plex, jellyfin, emby]

📝 Description

WatchState résout un problème courant en multi-serveur : on a un Plex pour la famille, un Jellyfin perso, un Emby chez un ami, et on aimerait que "vu à 70 % sur Plex" soit répercuté partout. WatchState agit comme une couche d'orchestration : il interroge régulièrement les backends, détecte les écarts d'état (vues, progression, watchlist, notes), et pousse les modifications de manière idempotente vers tous les autres backends.

Les backends supportés incluent Plex, Jellyfin, Emby, Kodi (via JSON-RPC), Subsonic (et donc Ampache/Navidrome), et Simkl/Trakt (services externes de tracking). L'outil est agnostique au sens où on peut garder Plex comme "primary" et tout réconcilier vers les autres, ou bien définir des règles par utilisateur.

Cas d'usage typique : un couple utilise Plex sur la TV, mais l'un des deux regarde sur Jellyfin via mobile en déplacement — WatchState rapproche les deux visions. Limites : pas d'UI web, configuration 100 % en ligne de commande et fichier YAML, ce qui rebute les moins à l'aise avec le shell.

🚀 Installation

Via Docker (recommandé)

# docker-compose.yml
version: "3.8"

services:
  watchstate:
    image: ghcr.io/thejinfei/watchstate:latest
    container_name: watchstate
    restart: unless-stopped
    environment:
      WS_CONFIG_DIR: /config
      TZ: Europe/Paris
    volumes:
      - ./config:/config
    # Pas de port exposé : CLI uniquement
    entrypoint: ["/app/watchstate", "sync"]

Installation manuelle

PHP 8.2+, composer, ffmpeg. Cloner, composer install, puis php watchstate sync (cron). L'outil est conçu pour tourner en CLI cron, pas comme un service web persistant.

⚙️ Configuration

Fichier config.yaml : déclarer les backends (URL, token, identifiant). Chaque backend a un type (plex, jellyfin, emby, kodi, subsonic, simkl, trakt).
Mappage utilisateurs : associer un user Plex à un user Jellyfin à un user Simkl dans users.yaml.
Stratégie de sync : primary (qui est la source), pull (récupère l'état), push (impose son état). Configurable par backend.
Cron : */15 * * * * docker exec watchstate php watchstate sync typique.
Logging : fichier state.log, niveau configurable, rotation via logrotate.
Webhooks : optionnel, permet de déclencher la sync à la fin d'un visionnage.

🔗 Alternatives

PlexTraktSync — Plus ancien, ciblé Plex ↔ Trakt uniquement, Python.
JellyPlexWatched — Script de sync historique entre Plex et Jellyfin, plus limité.
Simkl / Trakt — Services externes centralisés, pas auto-hébergés, mais WatchState peut s'y brancher.
Unwatched — Plus simple, script bash, ne couvre que le cas "marquer comme vu".

🔒 Sécurité

Stocker les tokens API dans config.yaml chiffré ou dans des variables d'environnement Docker.
Ne pas exposer de port : WatchState est un outil CLI interne, ne doit pas être accessible réseau.
Si on doit consulter les logs à distance, les exposer en lecture seule via app-traefik avec auth SSO.
Les tokens Plex/Jellyfin ont accès à l'API complète : les considérer comme des secrets critiques.

📚 Ressources

Site officiel : https://watchstate.app/
Repository : https://github.com/theJinFei/watchstate
Documentation : https://watchstate.app/docs
Wiki : https://github.com/theJinFei/watchstate/wiki

🔗 Pages Liées

cat-media-streaming (catégorie parente)
app-jellyfin — Backend typique
app-plex — Backend typique
app-tracearr — Complément (analytics)
recettes-docker-compose — Templates
securisation-home-lab — Bonnes pratiques

4.7 KiB Raw Blame History