Skip to content

Home

Jump to bottom
Pascal van den Berg edited this page Nov 27, 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. CrossWatch aims to become a one-for-all synchronization system for locally hosted environments. Its modular architecture allows new providers to be added easily. This approach keeps the system maintainable, testable, and easy to extend as new platforms emerge. CW also includes its own tracker, so you can keep your data safe with snapshots.

🚀 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