Skip to content

Home

Jump to bottom
Pascal van den Berg edited this page Nov 30, 2025 · 37 revisions

CrossWatch is a lightweight synchronization engine that keeps your Plex, Jellyfin, Emby, Simkl, Trakt and MDBlist in sync. It runs locally with a clean web UI to link accounts, configure sync pairs, run them manually or on schedule, and track stats/history.

🚀 Features

  • Sync watchlists (one-/two-way)
  • Live scrobble (Plex/Jellyfin/Emby → Trakt)
  • Sync ratings (one-/two-way)
  • Sync watch history (one-/two-way)
  • Keep snapshots with CrossWatch tracker
  • Auto-remove from watchlist after finish
  • Analyzer - finds broken or missing matches/IDs
  • Exporter - CSV files for popular service
  • Stats, history, live logs
  • Headless scheduled runs
  • Trackers: CrossWatch  SIMKL  Trakt  MDBList
  • Media servers: Plex  Jellyfin  Emby

🧩 Architecture

  • FastAPI backend (crosswatch.py) at port 8787
  • FastAPI frontend (FastAPI.py)
  • Vanilla JS/CSS UI served from /assets/
  • Pluggable providers:
    • auth (Plex, Jellyfin, Emby, SIMKL, TRAKT, Mdblist)
    • sync (PLEX ⇄ Jellyfin ⇄ Emby ⇄ SIMKL ⇄ TRAKT ⇄ Mdblist)
    • metadata (TMDb enrichment)
  • All state/config stored as JSON in CONFIG_BASE
architecture diagram

⚠️ Limitations

CrossWatch is intentionally lightweight: no database, JSON files only. That keeps it simple but caps scale.

  • Not for very large libraries. JSON state and provider rate limits become the bottleneck.
  • Soft size guidance (varies by hardware; SSD + 2 GB RAM recommended for):
    • Watchlist: stable up to ~2,500 items total across providers.
    • History (plays): stable up to ~10,000 play events total.
    • Ratings: stable up to ~10,000 ratings total.
  • Above these ranges you may see slower planning, large state files, and long first-run times.
  • Heavy backfills (full history/ratings) can take hours. Prefer incremental windows when possible.
  • Ratings can take a long time; we don’t cache ratings (by design).
  • Only for Movies and Shows currently there is no Anime support.

Small/medium home setups = fine. Massive media hoards = use with caution.

🐛 Known Issues

  • Sync bar is not well integrated:
    • Sync progress bar can behave oddly due to real-time updates. Ctrl+F5 helps.
    • Will be improved in the future.
  • Some UI sections don’t auto-refresh reliably. When in doubt, Ctrl+F5 for a clean reload.
  • Stale UI data after long runs: Ctrl+F5 again.
  • Emby webhooks require Emby Premiere. If you don’t have it, use the Watcher instead.
  • Statistics may not always display the exact numbers yet.

Next steps

Clone this wiki locally