🍿 ListSync - Bridge Your Watchlist & Media Server 🎬

Welcome to the ListSync Tool! 🎉

This powerful tool automates the import of your carefully curated IMDB and Trakt lists into Overseerr, transforming movie and TV show management into a breeze. Whether you're a cinephile, a librarian for multiple collections, or someone enchanted by the magic of automation, this tool is here to simplify your experience.

🎬 Demo

🔑 Key Features

Feature	Status
List Management
- Simultaneous List Import	✅
- Support for IMDB & Trakt Lists	✅
- Multi-page Trakt List Fetching	✅
- List Management Menu	✅
Media Processing
- Fetch & Import Movies & TV Shows	✅
- Identify Media Already Requested	✅
- Identify Media Already Available	✅
Performance
- Thread Pool Executor for Concurrent Processing	✅
Configuration & Security
- Encrypted Configuration Storage	✅
- Configurable Sync Interval	✅
User Experience
- Real-time Detailed Logging	✅
- Graceful Exit During Sleep	✅
- Dry Run Mode	✅

📊 Compatibility

Application	Status	Notes
	✅ Supported	Full functionality with Overseerr
	✅ Supported	Full functionality with Jellyseerr
	✅ Supported	Started with supporting movies
	✅ Supported	Now also supports TV shows

Supported List Services

Service	Status	Notes
	✅ Supported	Currently supported
	✅ Supported	Currently supported

Future List Services

Service	Status	Notes
	❌ Not Yet	Future support planned

🚀 Getting Started

Installation Methods

Installation Method	Command	Notes
	`sudo docker pull ghcr.io/woahai321/list-sync:main && sudo docker run -it --rm -v "$(pwd)/data:/usr/src/app/data" -e TERM=xterm-256color ghcr.io/woahai321/list-sync:main`	Easy containerized deployment
	`pip install -r requirements.txt && python add.py`	Requires Python 3.7+
	`poetry install && poetry run python add.py`	Simplifies dependency management

Docker (Recommended)

To ensure the tool runs consistently across different environments, use Docker.

Install Docker:

Ensure Docker is installed on your system. If it's not, follow the installation guide for your operating system.
Create a working directory:

Make a folder to house the application's log files (e.g. list-sync)

Pull and Run the Docker Image:

Navigate to your directory and use the following one-liner to pull and run the Docker image:

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

Use this command for subsequent runs:

Use the following command to run the Docker image:

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

Standard Python Environment

If you prefer running the tool in a standard Python environment, follow these steps:

Clone the Repository and Navigate to the Directory:

git clone https://github.com/woahai321/list-sync.git
cd list-sync

Install Dependencies:

Make sure you have Python 3.9 or higher installed, then install the required dependencies:
```
pip install -r requirements.txt
```
Run the Script:
```
python add.py
```

Poetry

Poetry offers several advantages over traditional Python dependency management methods:

Ease of Use: Simplifies the installation process with a single command and manages virtual environments automatically.
Version Control: Tracks exact package versions, making it easier to reproduce environments and avoid version drift.
Security: Integrates with security tools to scan for vulnerabilities in dependencies.
Cross-Platform Compatibility: Ensures consistent behaviour across different operating systems.

Installation and Usage with Poetry

Install Poetry:

curl -sSL https://install.python-poetry.org | python3 -

Clone the Repository and Navigate to the Directory:

git clone https://github.com/woahai321/list-sync.git
cd list-sync

Install Dependencies:

Make sure you have Python 3.9 or higher installed, then install the required dependencies:
```
poetry install
```
Run the Script:
```
poetry run python add.py
```

Alternatively, use devcontainer to bootstrap a pre-built dev environment: DevContainer documentation

Configuration

Run the Script and Fill in the Required Details When Prompted:
- Overseerr URL: Your Overseerr instance's base URL.
- API Key: The API key from your Overseerr account.
- IMDB List ID(s): The ID(s) of the IMDB list(s) you want to import.
- Trakt List ID(s): The ID(s) of the Trakt list(s) you want to import.
Saving Configuration:
- The script will prompt you to enter a password to encrypt your configuration.
- This encrypted configuration will be saved and reused for future imports.

🔍 Obtaining List IDs

IMDB List ID

To obtain an IMDB list ID:

Navigate to your IMDB list.
Look at the URL. It should be in the format: https://www.imdb.com/list/ls012345678/
The list ID is the ls number. In this example, it would be ls012345678.

Trakt List ID

To obtain a Trakt list ID:

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

Adding Multiple List IDs

When inputting list IDs, you can add multiple IDs by separating them with commas.

🔎 How it Works

The ListSync Tool is a Python-based application that leverages several libraries and the Overseerr API to seamlessly integrate your IMDB and Trakt lists with Overseerr. Here's a detailed breakdown of its functionality:

Authentication and Security:
- Credentials are encrypted using the cryptography library's Fernet symmetric encryption.
- Encrypted data is stored locally, ensuring your sensitive information remains protected.
List Fetching and Parsing:
- For IMDB lists:
  - Utilizes requests to fetch the HTML content of the IMDB list.
  - Employs BeautifulSoup to parse the HTML and extract structured data.
- For Trakt lists:
  - Nearly the same process 1:1
  - Parses the HTML response to extract media information.
Overseerr Integration:
- Interacts with the Overseerr API using the requests library.
- Implements minimal rate limiting to prevent overwhelming the Overseerr server and webhooks.
- Performs media searches, status checks, and request submissions via API endpoints.
Intelligent Processing:
- Differentiates between movies and TV shows for appropriate handling.
- For TV shows, it determines the number of seasons and requests all available seasons.
- Checks if media is already available or requested before submitting new requests.
Error Handling and Logging:
- Implements comprehensive error handling for network issues, API errors, and parsing problems.
- Utilises Python's logging module to maintain detailed logs for troubleshooting.
- Provides real-time status updates in the console using the colorama and halo libraries.
Periodic Syncing:
- Offers the option to set up recurring syncs at user-defined intervals.
- Implements a sleep mechanism that can be interrupted for on-demand actions.
User Interface:
- Presents a user-friendly command-line interface with color-coded outputs.
- Displays ASCII art and banners for an engaging user experience.
- Provides summary statistics after each sync operation.

🛠 Troubleshooting

Common Issues and Solutions

Invalid API Credentials
- Symptom: Error messages related to API authentication or 401 Unauthorised responses.
- Solution:
  - Double-check your Overseerr URL and API key in the Overseerr settings.
  - Ensure there are no trailing spaces in the URL or API key.
  - Try regenerating your API key in Overseerr and updating the script's configuration.
Script Crashes or Unexpected Behavior
- Symptom: Script terminates unexpectedly or produces unexpected results.
- Solution:
  - Check the overseerr_sync.log file in the ./data directory for detailed error messages.
  - Look for Python tracebacks which can pinpoint the exact line causing the issue.
  - Ensure all required Python libraries are installed and up-to-date.
  - Verify that your Python version meets the minimum requirements (Python 3.7+).
Failed to Fetch List
- Symptom: Error messages indicating failure to retrieve IMDB or Trakt lists.
- Solution:
  - Verify that the list ID is correct and the list is publicly accessible.
  - Check your internet connection and firewall settings.
  - For IMDB lists, ensure the list URL follows the format: https://www.imdb.com/list/ls012345678/
  - For Trakt lists, confirm the list URL is in the format when copied: https://trakt.tv/lists/1234567
Decryption Error
- Symptom: Unable to decrypt configuration or "Incorrect password" error.
- Solution:
  - Ensure you're entering the correct password used during initial setup.
  - If you've forgotten the password, delete the config.enc file in the ./data directory and run the script again to reconfigure.
  - Check file permissions to ensure the script has read/write access to the ./data directory.
Rate Limiting Issues
- Symptom: Frequent "Too Many Requests" errors or slow processing.
- Solution:
  - Increase the delay between requests by adjusting the time.sleep() value in the script.
  - Consider reducing the size of your lists or splitting them into smaller chunks.
Media Not Found in Overseerr
- Symptom: Many items reported as "Not found" during processing.
- Solution:
  - Verify that Overseerr is properly connected to your media sources (Radarr/Sonarr).
  - Check if the titles in your lists match exactly with how they appear in Overseerr's search.
  - For TV shows, try using the original title rather than localised versions.

If you encounter persistent issues not covered here, please remeber this is in beta development and you will find bugs.

🛤️ Roadmap

Small Tasks

Enhanced Error Messages: Improve error descriptions for easier troubleshooting.
Advanced Error Handling: Improved error messages for clearer troubleshooting.
Secure User Profiles: Ability to save and load Overseerr details from an encrypted configuration file.
Real-time Progress Updates: Real-time progress updates for importing movies and TV shows.

Medium Tasks

Integration with Other Services: Trakt
Interruptible Sleep Mode: Functionality for interrupting sleep mode for on-demand sync or clean exit.
Configuration Management: Save and reuse configuration setups.
Batch Processing: Enable batch processing for multiple lists simultaneously.
Support for TV Shows: Extend functionality to import TV shows from IMDB and Trakt lists.
Database Integration: Implement a real database to track sync history and metrics, not just a file.
Integration with Other Services: Letterboxd, etc.
Customisation Options: Allow users to fully customise the UI and behaviour of the tool.

Big Tasks

Automated Syncing: Schedule automatic syncing between IMDB/Trakt and Overseerr.
Movie Status Identification: Identify movies already available, already requested, or to be requested.
TV Series Status Identification: Identify TV series already available, already requested, or to be requested.
Encrypted Configuration Storage: Implemented encrypted storage for Overseerr API credentials.
External Notifications: Add webhook notifications for sync status and errors.
Web Dashboard: Create a web-based interface for more user-friendly interaction.
Advanced Analytics Dashboard: Provide detailed analytics and insights into the sync operations.
Machine Learning Suggestions: Use ML to suggest movies and TV shows based on user preferences and history.

📋 Notes

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

📞 Contact

Need help or have questions? Don't hesitate to raise an issue on this repo; we're here to help!

🤝 Contributing

We appreciate your contributions! Here's how to get involved:

Fork the repository on GitHub.
Create a new branch for your feature or bug fix.
Make your changes and commit them with descriptive messages.
Submit a pull request for review.

📄 License

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

🎉 Fun Zone: Get to Know Your Tool!

Buckle up for some fun insights and interesting facts! Your ListSync Tool is more than just software; it's your new best friend in movie and TV show management.

🤓 Fun Facts

Cinema History: The first drive-in theater opened in 1933 in New Jersey. 🚗🎥 Source
Legendary Cameo: Alfred Hitchcock made cameo appearances in 39 of his 52 surviving major films! 🎭 Source
Oscar Records: Walt Disney holds the record for the most Oscars with 22 wins and 59 nominations. 🏆 Source
Expensive Set: "Pirates of the Caribbean: On Stranger Tides" is one of the most expensive movies ever made, with a budget of $379 million. 🏴‍☠️ Source
Film Length: The longest movie ever made is the experimental film "Modern Times Forever," which runs for 240 hours (10 days). 🎬 Source
Box Office King: "Avengers: Endgame" surpassed "Avatar" to become the highest-grossing film of all time. 💰 Source

🛡️ Legal Disclaimer

Using the ListSync Tool responsibly and in accordance with Overseerr's, IMDB's & Trakt's Terms of Service (ToS) and policies is crucial! Here are some key points:

Compliance with Overseerr and IMDB:
- Users must adhere to the ToS of all third parties in use.
No Spamming or Abuse:
- This tool should not be used for spam or unauthorised import activities. Respect the guidelines and policies of the platforms.
Managing Rate Limits:
- Use the tool thoughtfully to avoid hitting rate limits set by Overseerr. Excessive usage can lead to rate limiting or bans.
User Consent:
- Ensure you have the necessary permissions to import and manage media from IMDB lists.
Security:
- Protect your API credentials and never share them publicly.
Responsibility:
- Users are responsible for their actions while using this tool. The creators of the ListSync Tool are not liable for any misuse or legal consequences arising from its use.

Name		Name	Last commit message	Last commit date
Latest commit History 93 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
ReadMe.md		ReadMe.md
add.py		add.py
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt

Woahai321/list-sync

Folders and files

Latest commit

History

Repository files navigation