Skip to content

Home

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

CrossWatch is a lightweight synchronization engine that keeps your Plex, Jellyfin, Emby, 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 scrobble (Plex/Jellyfin/Emby → Trakt)
  • Sync ratings (one-/two-way)
  • Sync watch history (one-/two-way)
  • Sync playlists (one-/two-way — disabled)
  • Auto-remove from Plex watchlist after finish
  • Analyzer - finds broken or missing matches/IDs
  • Exporter - CSV files for popular service
  • Stats, history, live logs
  • Headless scheduled runs
  • Trackers: SIMKL  Trakt
  • 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)
    • sync (PLEX ⇄ Jellyfin ⇄ Emby ⇄ 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 don’t cache ratings (by design).

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

🐛 Known Issues

  • Some UI sections don’t auto-refresh reliably. When in doubt, Ctrl+F5 (Windows) for a clean reload.
  • Sync progress bar can behave oddly due to real-time updates. Ctrl+F5 helps.
  • Stale UI data after long runs: Ctrl+F5 again.
  • 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.
  • Emby webhooks require Emby Premiere. If you don’t have it, use the Watcher instead.
  • SIMKL & Jellyfin/Emby integrations are still maturing; edge cases are expected.
  • Statistics may not always display the exact numbers yet.

Next steps

Clone this wiki locally