🍿 ListSync - Bridge Your Watchlist & Media Server 🎬

---

🚀 What is ListSync?

ListSync automatically syncs your watchlists from IMDb, Trakt, Letterboxd, MDBList, and more with Overseerr/Jellyseerr. No more manual adding - just add movies and shows to your favorite watchlist, and they'll appear in your media server automatically.

Key Features:

• 🔄 Automatic synchronization
• 🎬 Support for multiple watchlist platforms
• 🖥️ Compatible with Overseerr and Jellyseerr
• ⚡ Easy setup with Docker

---

🖥️ Modern Web Dashboard

ListSync now includes a comprehensive web dashboard built with Next.js 15 and React 19, providing a modern interface to manage all your sync operations.

Key Features

• 📊 Real-Time Sync Monitoring - Live progress bars and status updates
• 📋 Intuitive List Management - Add, edit, and organize your lists with ease
• 📈 Comprehensive Analytics - Success rates, performance metrics, and historical data
• ⚙️ Web-Based Configuration - Manage all settings through the dashboard
• 🎨 Modern Responsive UI - Works perfectly on desktop, tablet, and mobile
• 🌙 Dark/Light Themes - Automatic system preference detection

Access your dashboard at: http://localhost:3222 (frontend) and http://localhost:4222/api (API)

---

📚 Quick Links

• 🚀 Installation Guide
• 📋 List Setup Guide
• 🛠️ Troubleshooting
• 📖 Documentation

---

✨ Run ListSync & SeerrBridge with ElfHosted 🚀

ElfHosted is your friendly neighborhood open-source PaaS, handling the geeky heavy-lifting (hosting, security, updates, you name it!) so you can focus on watching your media.

Important

ElfHosted 💜 ListSync & SeerrBridge!

ListSync and its awesome companion SeerrBridge are fully supported and integrated into the ElfHosted ecosystem, you can already get them pre-configured in the bundles below, with a $1, 7-day trial!

Tip

ElfHosted Streaming Bundles: Your Turn-Key Streaming Powerhouse! 💹

Want all of this without the DIY setup? 🎉 These ElfHosted bundles come pre-wired with RealDebrid, SeerrBridge and ListSync, and your choice of media server. Get the ultimate hassle-free, automated infinite streaming experience:

• Starter Personal Media Streamer [2xHD / 1x4K, contented]
• Hobbit Personal Media Streamer [4xHD / 2x4K, semi-dedicated]
• Ranger Personal Media Streamer [8xHD / 4x4K, semi-dedicated]

---

🚀 Getting Started

ListSync offers flexible deployment options to suit different use cases, from quick testing to full production deployments with web dashboard.

🐳 Deployment Options

📦 Full Stack Deployment (Recommended)

Complete ListSync with Web Dashboard + API + Core Sync

The full deployment includes everything: the core sync engine, REST API backend, and modern web dashboard for comprehensive management.

What's Included:

• 🖥️ Web Dashboard (Port 3222) - Modern React interface
• 🔌 REST API (Port 4222) - Full API for automation
• ⚙️ Core Sync Engine - Automated list synchronization
• 📊 Real-time Monitoring - Live sync progress and analytics
• 🎛️ Configuration Management - Web-based settings

Deploy with Docker Compose:

# Copy the example environment file and configure
cp .env.example .env
# Edit .env with your settings, then start using the public image
docker-compose up -d
# or build from source
docker-compose -f docker-compose.local.yml up -d

Access Points:

• 🌐 Web Dashboard: http://localhost:3222
• 🔗 API Docs: http://localhost:4222/docs
• 📊 Health Check: http://localhost:4222/api/system/health

⚙️ Core-Only Deployment

Lightweight Core Sync Engine Only

Perfect for headless servers or when you only need the core synchronization functionality without the web interface.

What's Included:

• ⚙️ Core Sync Engine - Automated list synchronization only
• 📝 Console Logging - Text-based status updates
• 🔄 Scheduled Syncing - Automated intervals
• 💾 Local Database - SQLite for sync history

Deploy with Docker Compose:

# Copy the core environment file and configure
cp .env.core .env
# Edit .env with your settings, then start
docker-compose -f docker-compose.core.yml up -d

Perfect for:

• 🖥️ Headless servers
• 📦 Minimal resource usage
• 🔧 Integration with existing systems
• 🚀 Lightweight automation

🌐 Public Domain Deployment

Internet-Accessible Deployment with Domain

Deploy ListSync with public internet access using your own domain, perfect for remote management and team access.

Deploy with Docker Compose:

# Copy the domain environment file and configure
cp .env.proddomain .env
# Edit .env with your domain settings, then start
docker-compose -f docker-compose.proddomain.yml up -d

🛠️ Configuration Setup

All deployment options use the same environment configuration. Create a .env file or use our plug-and-play template:

Quick Start with Pre-configured Lists: Use our plug-and-play configuration:

# Copy the plug-and-play environment file
cp .env.plugnplay .env
# Edit only the essential settings in .env:
# - OVERSEERR_URL (your Overseerr/Jellyseerr URL)
# - OVERSEERR_API_KEY (your API key)
# - DISCORD_WEBHOOK_URL (optional)
# - TZ (your timezone)

The .env file comes pre-configured with curated lists including:

Provider	List Type	Description
IMDb	Chart & Lists	Top 250 Movies, Disney Movies
Trakt	Trending & Popular	Trending Movies, Popular Movies, Trending Shows, Popular Shows
MDBList	Curated Collections	Top Weekly Movies, Pixar Movies, Pirated Movies Charts
Steven Lu	Popular Collection	Popular Movies Collection

🌍 Timezone Configuration

ListSync automatically timestamps all sync activities and displays them in the web interface. To ensure timestamps match your local time, configure your timezone using the examples below.

🕐 Setting Your Timezone

Quick Setup by Timezone

Choose your timezone using either UTC offset or regional timezone format:

🌍 UTC Offset Format (Universal)

# docker-compose.yml
environment:
  # UTC offsets (recommended for simplicity)
  - TZ=UTC+0                  # Greenwich Mean Time
  - TZ=UTC-5                  # US Eastern Time
  - TZ=UTC-6                  # US Central Time
  - TZ=UTC-7                  # US Mountain Time
  - TZ=UTC-8                  # US Pacific Time
  - TZ=UTC+1                  # Central European Time
  - TZ=UTC+2                  # Eastern European Time
  - TZ=UTC+8                  # China/Singapore Time
  - TZ=UTC+9                  # Japan/Korea Time
  - TZ=UTC+10                 # Eastern Australia Time

🌐 GMT Format (Alternative)

# docker-compose.yml
environment:
  # GMT offsets (equivalent to UTC)
  - TZ=GMT+0                  # Greenwich Mean Time
  - TZ=GMT-5                  # US Eastern Time
  - TZ=GMT-8                  # US Pacific Time
  - TZ=GMT+1                  # Central European Time
  - TZ=GMT+8                  # Asia-Pacific Time

Finding Your Timezone

• 🌐 Online: Visit timeanddate.com/time/zones for the complete worldwide list of offsets
• 🖥️ Linux/macOS: Run timedatectl or cat /etc/timezone
• 🪟 Windows: Check "Time zone" in Settings → Time & Language

🛠️ Manual Installation (Advanced Users)

🔧 Local Development & Manual Setup

For developers or advanced users who want to run ListSync without Docker or need a development environment.

Prerequisites

• Python 3.9+
• Node.js 18+ (for web dashboard)
• Chrome/Chromium browser
• Git

Quick Manual Setup

Installation Method	Command
	git clone https://github.com/Woahai321/list-sync.git && cd list-sync && poetry install && poetry run python -m list_sync
	git clone https://github.com/Woahai321/list-sync.git && cd list-sync && pip install -r requirements.txt && python -m list_sync

Additional Resources:

• 📖 Detailed Installation Guide
• 👥 Contributing Guide
• 🏗️ Architecture Overview

---

Currently in Development for v0.7.0

For the most stable experience, use the source code from the latest release here.

---

📊 Compatibility

🌉 SeerrBridge Integration

SeerrBridge is our companion application that provides an alternative to traditional *arr stack (Radarr/Sonarr) setup. It works alongside ListSync to create a complete media management solution:

• Automated Processing: When ListSync adds requests to Jellyseerr/Overseerr, SeerrBridge automatically processes them
• Browser Automation: Uses Selenium to automate media fetching through Debrid Media Manager
• Simplified Setup: Eliminates the need for complex *arr stack configuration

How ListSync & SeerrBridge Work Together

1. ListSync adds media requests to Jellyseerr/Overseerr
2. SeerrBridge detects the requests via webhook
3. SeerrBridge automatically processes the requests through DMM
4. Media becomes available in your RD library

For detailed information about SeerrBridge, visit the SeerrBridge Repository.

Media Server Compatibility

Application	Status	Notes
	✅ Supported	Full functionality with Overseerr
	✅ Supported	Full functionality with Jellyseerr
	✅ Supported	Compatible through Jellyseerr
	✅ Supported	Compatible through Jellyseerr

Supported List Services

Service	Status	Notes
	✅ Supported	Full support for lists, watchlists, and charts
	✅ Supported	Full support for lists and user watchlists
	✅ Supported	Special lists include trending, popular, anticipated (configurable item limit)
	✅ Supported	Fixed pagination for watchlists with "Older" button support
	✅ Supported	Support for username/listname format or full URLs
	✅ Supported	Popular movies from JSON API

---

📋 Obtaining List IDs

ListSync supports multiple list services. You can add them using either the raw URL or the list ID.

📋 IMDb List ID or URL

Using the Raw URL:

1. Navigate to your IMDb list in your browser.
2. Copy the URL from the address bar. Examples:
   • Custom lists: https://www.imdb.com/list/ls012345678/
   • IMDb charts: https://www.imdb.com/chart/top/ (Top 250), https://www.imdb.com/chart/boxoffice/ (Box Office)
   • Watchlists: https://www.imdb.com/user/ur12345678/watchlist
3. Paste the URL directly into ListSync.

Using the List ID:

1. Look at the URL:
   • Custom lists: ls012345678
   • IMDb charts: Use the chart name (e.g., top, boxoffice)
   • Watchlists: ur12345678
2. Use the list ID in ListSync.

Supported IMDb Charts:

• top (Top 250 Movies)
• boxoffice (Box Office)
• moviemeter (MovieMeter)
• tvmeter (TVMeter)

📋 Trakt List ID or URL

Using the Raw URL:

1. Navigate to your Trakt list in your browser.
2. Copy the URL from the address bar. Example:
   • https://trakt.tv/users/username/lists/example-list
3. Paste the URL directly into ListSync.

Using the List ID:

1. Click the "Share" button on your Trakt list.
2. Copy the link, which will look like:
   • https://trakt.tv/lists/12345678
3. The list ID is the number at the end (e.g., 12345678).

📋 Trakt Special Lists

Using the Raw URL:

1. Copy the URL from the address bar. Examples:
   • https://trakt.tv/movies/trending
   • https://trakt.tv/shows/popular
   • https://trakt.tv/movies/boxoffice

Using Shortcut Format:

ListSync supports a shortcut format of list-type:media-type. Examples:

• trending:movies - Top trending movies
• popular:shows - Popular TV shows
• anticipated:movies - Most anticipated movies

Available Types:

• List types: trending, popular, anticipated, watched, collected, boxoffice, streaming, recommendations, favorited
• Media types: movies, shows

Note: The boxoffice list type is only available for movies.

These special lists sync a configurable number of items (default: 20, can be set via TRAKT_SPECIAL_ITEMS_LIMIT environment variable).

📋 Letterboxd URL

Using the Raw URL:

1. Navigate to your Letterboxd list in your browser.
2. Copy the URL from the address bar. Example:
   • https://letterboxd.com/user/list/example-list/
   • https://letterboxd.com/user/watchlist/ (for watchlists)
3. Paste the URL directly into ListSync.

📋 MDBList URL or Username/List Format

Using the Raw URL:

1. Navigate to your MDBList list in your browser.
2. Copy the URL from the address bar. Example:
   • https://mdblist.com/lists/username/listname
3. Paste the URL directly into ListSync.

Using Username/List Format:

1. You can also use the simpler format:
   • username/listname
2. ListSync will automatically expand this to the full URL.

📋 Steven Lu's Popular Movies

This is a curated list of popular movies maintained by Steven Lu, available at:

• https://s3.amazonaws.com/popular-movies/movies.json

To enable this list, simply add the below vairable:

• STEVENLU_LISTS=stevenlu

This will be recognized as the Steven Lu Popular Movies list.

---

📋 Notes

• Security Best Practices: Please read scripts you find online before running them.
• API Credentials: Always keep your API credentials secure.
• Rate Limiting: Be mindful of Overseerr's rate limiting policies during imports.
• Permissions: Only import and manage media you have the rights to handle.

💰 Support ListSync's Development

If you find ListSync useful and would like to support its development, consider becoming a sponsor:

➡️ Sponsor us on GitHub

Thank you for your support!

---

📖 Documentation

For comprehensive documentation, visit our Documentation Hub or explore specific guides:

• User Guide - Complete usage guide with examples
• Installation Guide - Detailed installation instructions
• Configuration Guide - Environment setup and configuration
• API Documentation - Complete REST API reference
• Architecture Overview - Technical architecture and design

🛠 Troubleshooting

If you encounter any issues while using ListSync, please check our Troubleshooting Guide for solutions to common problems.

🤝 Contributing

We welcome contributions! For guidelines on how to contribute, please see our Contributing Guide.

📄 License

This project is licensed under the MIT License. Review the LICENSE file for more details.

🛡️ Legal Information

For important legal information about using ListSync, please refer to our Legal Disclaimer.

Star History