---
title: WatchState
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, media-streaming, watchstate, sync, plex, jellyfin, emby]
confidence: high
contested: false
sources:
  - https://selfh.st/apps/?tag=Media+Streaming
  - https://github.com/theJinFei/watchstate
  - https://watchstate.app/
---

# 🎬 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é)

```yaml
# 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
