Skip to content

Home

Jump to bottom
Pascal van den Berg edited this page Oct 14, 2025 · 37 revisions

CrossWatch is a lightweight synchronization engine that keeps your Plex, Jellyfin, Simkl, and Trakt 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.

🚀 Features

  • Sync watchlists (one-/two-way)
  • Live scrobbling (Plex → Trakt)
  • Sync ratings (one-/two-way)
  • Sync watch history (one-/two-way)
  • Sync playlists (one-/two-way — disabled)
  • Simple web UI — JSON state
  • TMDb metadata & posters
  • Stats, history, live logs
  • Headless scheduled runs
  • Trackers: SIMKL  Trakt
  • Media servers: Plex  Jellyfin

🧩 Architecture

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

⚠️ 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 dont use any caching for ratings (by design)

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

🐛 Known Issues

  • Heads-up (CrossWatch): Some sections don’t auto-refresh reliably. When in doubt, Ctrl+F5 is your friend for a clean reload (Windows).
  • Sync progress bar can behave oddly due to real-time updates. Use CTRL + F5 to hard refresh (Windows).
  • Stale UI data: sometimes sections don’t update instantly. CTRL + F5 (Windows) helps.
  • Plex libraries: Not seeing them in Settings? Verify the server URL—use your LAN IP with http://<IP>:32400 to avoid SSL issues. Still blank? Hard-refresh with Ctrl+F5 (Windows).
  • SIMKL & Jellyfin are still maturing; edge cases are expected.
  • Statistics will not always displays the correct number. Needs some improvements.

Next steps

Clone this wiki locally