🍿 ListSync - Bridge Your Watchlist & Media Server 🎬

---

🚀 What is ListSync?

ListSync automatically syncs your watchlists from IMDb, Trakt, and Letterboxd 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

---

📚 Quick Links

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

---

How Does It Work?

ListSync seamlessly syncs your watchlists with your media server in three simple steps:

1. Fetch Watchlists

ListSync retrieves your watchlists from IMDb, Trakt or Letterboxd using Selenium web scraping techniques.

2. Search Media on Media Server

ListSync searches for each item on your media server (Overseerr or Jellyseerr) using its API. It handles edge cases like special characters or multiple results for accurate matches.

3. Request Media

ListSync checks if the media is already available or requested. If not, it automatically requests the item:

• For Movies, it requests the title.
• For TV Shows, it requests all available seasons.

Why Use ListSync?

• Save Time: Automates adding movies and TV shows to your media server.
• Stay Organized: Keeps your media server in sync with your watchlists.
• Flexible: Works with IMDb, Trakt, Letterboxd, Overseerr, and Jellyseerr.
• Customizable: Set sync intervals to match your preferences.

---

Currently in Development for v0.6.0

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

🎬 Demo

---

🚀 Getting Started

There are two ways to run ListSync:

Option 1: Quick Start (Recommended)

The fastest way to get started is with our Docker one-liner:

Installation Method	Command
	docker pull ghcr.io/woahai321/list-sync:main && docker run -it --rm -v "$(pwd)/data:/usr/src/app/data" -e TERM=xterm-256color ghcr.io/woahai321/list-sync:main

Option 2: Using Docker Compose 🐳

Option 2: Using Docker Compose

Create and configure your .env file with your settings:

# Overseerr Configuration
OVERSEERR_URL=https://your-overseerr-instance
OVERSEERR_API_KEY=your-api-key-here
OVERSEERR_USER_ID=1

# Sync interval in hours (default: 24)
SYNC_INTERVAL=24

# Lists Configuration (comma-separated)
IMDB_LISTS=ls123456789,ur123456789,top,boxoffice
TRAKT_LISTS=12345,67890
LETTERBOXD_LISTS=https://letterboxd.com/username/list/listname/

Run using Docker Compose:

Installation Method	Command
	docker-compose build && docker-compose up

Option 3: Manual Installation 🛠️

Option 3: Manual Installation

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

For detailed installation instructions, please refer to our Installation Guide.

---

📊 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
• Real-Debrid Integration: Direct integration with Real-Debrid for content retrieval

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 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	Currently supported
	✅ Supported	Currently supported
	✅ Supported	Currently supported

🔍 Obtaining List IDs

ListSync supports IMDb, Trakt and Letterboxd lists, and you can add them using either the raw URL or the list ID. This flexibility allows you to simply copy and paste from your browser’s URL bar or follow the instructions below to extract the list ID. Additionally, ListSync now supports IMDb charts, making it even easier to sync popular lists like the Top 250 or Box Office.

IMDb List ID or URL

You can add IMDb lists using either the raw URL or the list ID. Here’s how:

Using the Raw URL:

1. Navigate to your IMDb list in your browser.
2. Copy the URL from the address bar. It will look like one of the following:
   • For custom lists: https://www.imdb.com/list/ls012345678/
   • For IMDb charts: https://www.imdb.com/chart/top/ (Top 250), https://www.imdb.com/chart/boxoffice/ (Box Office), etc.
   • For watchlists: https://www.imdb.com/user/ur12345678/watchlist
3. Paste the URL directly into ListSync.

Using the List ID:

1. Navigate to your IMDb list in your browser.
2. Look at the URL. It will be in one of the following formats:
   • For custom lists: https://www.imdb.com/list/ls012345678/ → The list ID is ls012345678.
   • For IMDb charts: The chart name (e.g., top, boxoffice, moviemeter, tvmeter) is the list ID.
   • For watchlists: https://www.imdb.com/user/ur12345678/watchlist → The list ID is ur12345678.
3. Use the list ID in ListSync.

Supported IMDb Charts:

ListSync supports the following IMDb charts by name:

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

Trakt List ID or URL

You can add Trakt lists using either the raw URL or the list ID. Here’s how:

Using the Raw URL:

1. Navigate to your Trakt list in your browser.
2. Copy the URL from the address bar. It will look like one of the following:
   • For user lists: https://trakt.tv/users/username/lists/example-list
3. Paste the URL directly into ListSync.

Using the List ID:

1. Go to your Trakt list in your browser.
2. Look for the blue "Share" button, located in the list.
3. 
4. Hover over it, and it should say "Copy Link".
5. The copied link will be in the format: https://trakt.tv/lists/12345678 or https://trakt.tv/users/username/lists/12345678.
6. The list ID is the number at the end. In this example, it would be 12345678.

Letterboxd URL

Using the Raw URL:

1. Navigate to your Letterboxd list in your browser.
2. Copy the URL from the address bar. It will look like one of the following:
   • For user lists: https://letterboxd.com/user/list/example-list/
3. Paste the URL directly into ListSync.

Adding Multiple List IDs

When inputting list IDs or URLs, you can add multiple lists by separating them with commas. For example:

• IMDb: ls012345678,12345678,https://www.imdb.com/chart/top/,ur987654321,https://trakt.tv/lists/87654321

This allows you to sync multiple lists at once, whether they are custom lists, charts, or watchlists.

📋 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.

💰 Donations

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

• BTC (Bitcoin): bc1qxjpfszwvy3ty33weu6tjkr394uq30jwkysp4x0
• ETH (Ethereum): 0xAF3ADE79B7304784049D200ea50352D1C717d7f2

Thank you for your support!

🔎 How it Works

For detailed information on how ListSync works, please refer to our How it Works document.

🛠 Troubleshooting

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

🛤️ Roadmap

To see our plans for future development and features, visit our Roadmap.

🤝 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 Disclaimer

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

Star History