From cc7b20e85dd0f9aecbc6e084fb701d95e8eb548d Mon Sep 17 00:00:00 2001 From: WoahAI <115117306+Woahai321@users.noreply.github.com> Date: Sat, 26 Oct 2024 07:41:27 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=8F=81=20=E2=9C=85=20Final=20v0.5.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ReadMe.md | 412 ++++------------------------------------ docs/contributing.md | 75 ++++++++ docs/how-it-works.md | 51 +++++ docs/installation.md | 116 +++++++++++ docs/legal-disclamer.md | 45 +++++ docs/roadmap.md | 55 ++++++ docs/troubleshooting.md | 70 +++++++ 7 files changed, 452 insertions(+), 372 deletions(-) create mode 100644 docs/contributing.md create mode 100644 docs/how-it-works.md create mode 100644 docs/installation.md create mode 100644 docs/legal-disclamer.md create mode 100644 docs/roadmap.md create mode 100644 docs/troubleshooting.md diff --git a/ReadMe.md b/ReadMe.md index 5a16a72..69687b0 100644 --- a/ReadMe.md +++ b/ReadMe.md @@ -10,205 +10,46 @@ [![Website](https://img.shields.io/badge/Website-soluify.com-blue?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==)](https://soluify.com/) [![LinkedIn](https://img.shields.io/badge/LinkedIn-blue?style=for-the-badge&logo=linkedin)](https://www.linkedin.com/company/soluify) - -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. +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. ## πŸ“œ Table of Contents -1. [Demo](#-demo) -2. [Key Features](#-key-features) -3. [Compatibility](#-compatibility) -4. [Getting Started](#-getting-started) - - [Installation: Docker (Recommended)](#installation-docker-recommended) - - [Standard Python Environment](#standard-python-environment) - - [Poetry](#poetry) - - [Configuration](#configuration) -5. [Obtaining List IDs](#-obtaining-list-ids) -6. [How it Works](#-how-it-works) -7. [Troubleshooting](#-troubleshooting) -8. [Roadmap](#-roadmap) -9. [Notes](#-notes) -10. [Contact](#-contact) -11. [Contributing](#-contributing) -12. [License](#-license) -13. [Fun Zone: Get to Know Your Tool!](#-fun-zone-get-to-know-your-tool) -14. [Legal Disclaimer](#-legal-disclaimer) - -## 🎬 Demo - -![Bot In Action](https://share.woahlab.com/-BZtwSD96LN) - ---- - -### πŸ”‘ 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 | βœ… | - ---- +1. [Compatibility](#-compatibility) +2. [Getting Started](#-getting-started) +3. [Obtaining List IDs](#-obtaining-list-ids) +4. [How it Works](/docs/how-it-works.md) +5. [Troubleshooting](/docs/troubleshooting.md) +6. [Roadmap](/docs/roadmap.md) +7. [Notes](#-notes) +8. [Contributing](#-contributing) +9. [License](#-license) ## πŸ“Š Compatibility -| Application | Status | Notes | -|:-----------:|:------:|:------| -| ![Overseerr](https://img.shields.io/badge/Overseerr-1.33.2+-blue?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABB0lEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Full functionality with Overseerr | +| Application | Status | Notes | +| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------: | :--------------------------------- | +| ![SeerrBridge](https://img.shields.io/badge/SeerrBridge-Compatible-blue?style=for-the-badge&logo=github) | βœ… Supported | Fully compatible | +| ![Overseerr](https://img.shields.io/badge/Overseerr-1.33.2+-blue?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABB0lEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Full functionality with Overseerr | | ![Jellyseerr](https://img.shields.io/badge/Jellyseerr-1.9.2+-purple?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABB0lEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Full functionality with Jellyseerr | -| ![Radarr](https://img.shields.io/badge/Radarr-5.11.0+-orange?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Started with supporting movies | -| ![Sonarr](https://img.shields.io/badge/Sonarr-4.0.9+-5cad7b?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABB0lEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Now also supports TV shows | +| ![Radarr](https://img.shields.io/badge/Radarr-5.11.0+-orange?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Started with supporting movies | +| ![Sonarr](https://img.shields.io/badge/Sonarr-4.0.9+-5cad7b?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABB0lEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Now also supports TV shows | ### Supported List Services -| Service | Status | Notes | -|:-------:|:------:|:------| -| ![IMDB](https://img.shields.io/badge/IMDB-green?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Currently supported | +| Service | Status | Notes | +| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------: | :------------------ | +| ![IMDB](https://img.shields.io/badge/IMDB-green?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Currently supported | | ![Trakt](https://img.shields.io/badge/Trakt-green?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | βœ… Supported | Currently supported | -### Future List Services - -| Service | Status | Notes | -|:-------:|:------:|:------| -| ![Letterboxd](https://img.shields.io/badge/Letterboxd-red?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAABKElEQVQ4jZXTMUoDQRQG4C+7YmFhYSHYWFgIHkAQPICFhYcQBEEQxGNYWHgIC0H0BsELWFhYWAQLC2GzxSzsLrOz2f0hMDDvzXvfzLz3ZkopKKMxxrjHJc7wjjd0UgpfZRYVgbM4P2AevZzEHlZwiU5KYa8QmMUNtnCMh5TCqCR0jgF6eEQfq1jHFfbRxHFKYVQQWMQIZxjGehObeEUH7ZTCJCcYx2Ub99jGEEtYwDnWsIk2LlIK/ZzALK7RwlKsPWMppfAc/m+0UwrTnKCBHt7iZnlp5/GCVkrhKyd4wg5WYv6NTkrhNSdoRd0b2Cg0z0dOcIj9uHnePG/+t/k3wR/kyUNUdQE+UAAAAABJRU5ErkJgg==) | ❌ Not Yet | Future support planned | - ---- - ## πŸš€ Getting Started -### Installation Methods - -| Installation Method | Command | Notes | -|:-------------------:|:-------:|:------| -| ![Docker](https://img.shields.io/badge/Docker-ready-blue?style=for-the-badge&logo=docker) | `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 | -| ![Python](https://img.shields.io/badge/Python-3.7%2B-blue?style=for-the-badge&logo=python) | `pip install -r requirements.txt && python add.py` | Requires Python 3.7+ | -| ![Poetry](https://img.shields.io/badge/Poetry-ready-blue?style=for-the-badge&logo=poetry) | `poetry install && poetry run python add.py` | Simplifies dependency management | - - -### Docker (Recommended) - -To ensure the tool runs consistently across different environments, use Docker. - -1. **Install Docker**: - - Ensure Docker is installed on your system. If it's not, follow the [installation guide](https://docs.docker.com/get-docker/) for your operating system. - -2. **Create a working directory**: - - Make a folder to house the application's log files (e.g. list-sync) - -3. **Pull and Run the Docker Image**: - - Navigate to your directory and use the following one-liner to pull and run the Docker image: - - ```sh - 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 - ``` - -4. **Use this command for subsequent runs**: - - Use the following command to run the Docker image: - - ```sh - 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: - -1. **Clone the Repository and Navigate to the Directory**: - - ```sh - git clone https://github.com/woahai321/list-sync.git - cd list-sync - ``` - -2. **Install Dependencies**: +| Installation Method | Command | +| :----------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | +| ![Docker](https://img.shields.io/badge/Docker-ready-blue?style=for-the-badge&logo=docker) | `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` | +| ![Python](https://img.shields.io/badge/Python-3.7%2B-blue?style=for-the-badge&logo=python) | `pip install -r requirements.txt && python add.py` | +| ![Poetry](https://img.shields.io/badge/Poetry-ready-blue?style=for-the-badge&logo=poetry) | `poetry install && poetry run python add.py` | - Make sure you have Python 3.9 or higher installed, then install the required dependencies: - - ```sh - pip install -r requirements.txt - ``` - -3. **Run the Script**: - - ```sh - 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 - -1. **Install Poetry**: - - ```sh - curl -sSL https://install.python-poetry.org | python3 - - ``` - -2. **Clone the Repository and Navigate to the Directory**: - - ```sh - git clone https://github.com/woahai321/list-sync.git - cd list-sync - ``` - -3. **Install Dependencies**: - - Make sure you have Python 3.9 or higher installed, then install the required dependencies: - - ```sh - poetry install - ``` - -4. **Run the Script**: - - ```sh - poetry run python add.py - ``` - -Alternatively, use [devcontainer](.devcontainer/devcontainer.json) to bootstrap a pre-built dev environment: [DevContainer documentation](https://containers.dev/) - -### Configuration - -1. **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. - -2. **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. - ---- +For detailed installation instructions, please refer to our [Installation Guide](/docs/installation.md). ## πŸ” Obtaining List IDs @@ -225,7 +66,7 @@ To obtain an IMDB list ID: To obtain a Trakt list ID: 1. Go to your Trakt list. -2. Look for the blue "Share" button, located in the list +2. Look for the blue "Share" button, located in the list. 3. ![trakt-help](https://share.woahlab.com/-Nx5VJnbUEY) 4. Hover over it, it should say "**Copy Link**". 5. The copied link will be in the format: `https://trakt.tv/lists/12345678` @@ -234,220 +75,47 @@ To obtain a Trakt list ID: ### 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](https://api-docs.overseerr.dev/#/) to seamlessly integrate your IMDB and Trakt lists with Overseerr. Here's a detailed breakdown of its functionality: - -1. **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. - -2. **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. - -3. **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. - -4. **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. - -5. **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. - -6. **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. - -7. **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. - ---- +For detailed information on how ListSync works, please refer to our [How it Works](/docs/how-it-works.md) document. ## πŸ›  Troubleshooting -### Common Issues and Solutions - -1. **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. - -2. **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+). - -3. **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` - -4. **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. - -5. **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. - -6. **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. - ---- +If you encounter any issues while using ListSync, please check our [Troubleshooting Guide](/docs/troubleshooting.md) for solutions to common problems. ## πŸ›€οΈ Roadmap -### Small Tasks - -- [x] **Enhanced Error Messages:** Improve error descriptions for easier troubleshooting. -- [x] **Advanced Error Handling:** Improved error messages for clearer troubleshooting. -- [x] **Secure User Profiles:** Ability to save and load Overseerr details from an encrypted configuration file. -- [x] **Real-time Progress Updates:** Real-time progress updates for importing movies and TV shows. - -### Medium Tasks - -- [x] **Integration with Other Services:** Trakt -- [x] **Interruptible Sleep Mode:** Functionality for interrupting sleep mode for on-demand sync or clean exit. -- [x] **Configuration Management:** Save and reuse configuration setups. -- [x] **Batch Processing:** Enable batch processing for multiple lists simultaneously. -- [x] **Support for TV Shows:** Extend functionality to import TV shows from IMDB and Trakt lists. -- [x] **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 - -- [x] **Automated Syncing:** Schedule automatic syncing between IMDB/Trakt and Overseerr. -- [x] **Movie Status Identification:** Identify movies already available, already requested, or to be requested. -- [x] **TV Series Status Identification:** Identify TV series already available, already requested, or to be requested. -- [x] **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. - ---- +To see our plans for future development and features, visit our [Roadmap](/docs/roadmap.md). ## πŸ“‹ 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! - ---- - -## πŸ’° Donations - -If you find our work useful and would like to support us, feel free to make a donation using the addresses below: - -- BTC (Bitcoin): `bc1qxjpfszwvy3ty33weu6tjkr394uq30jwkysp4x0` -- ETH (Ethereum): `0xAF3ADE79B7304784049D200ea50352D1C717d7f2` - -Thank you for your support! - ---- +- **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. ## 🀝 Contributing -We appreciate your contributions! Here's how to get involved: - -1. **Fork the repository** on GitHub. -2. **Create a new branch** for your feature or bug fix. -3. **Make your changes** and commit them with descriptive messages. -4. **Submit a pull request** for review. - ---- +We welcome contributions! For guidelines on how to contribute, please see our [Contributing Guide](/docs/contributing.md). ## πŸ“„ License This project is licensed under the [MIT License](https://opensource.org/license/mit). Review the LICENSE file for more details. ---- +## πŸ›‘οΈ Legal Disclaimer -# πŸŽ‰ Fun Zone: Get to Know Your Tool! +For important legal information about using ListSync, please refer to our [Legal Disclaimer](/docs/legal-disclaimer.md). -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. +## πŸ’° Donations +If you find ListSync useful and would like to support its development, consider making a donation: -## πŸ€“ Fun Facts +- BTC (Bitcoin): `bc1qxjpfszwvy3ty33weu6tjkr394uq30jwkysp4x0` +- ETH (Ethereum): `0xAF3ADE79B7304784049D200ea50352D1C717d7f2` -- **Cinema History:** The first drive-in theater opened in 1933 in New Jersey. πŸš—πŸŽ₯ [Source](https://en.m.wikipedia.org/wiki/File:First_drive-in_theater_Camden_NJ_1933.jpg#:~:text=in%20Pennsauken%2C%20near%20Camden%2C%20New,Adolphe%20Menjou%27s%20Wife%20Beware.) -- **Legendary Cameo:** Alfred Hitchcock made cameo appearances in 39 of his 52 surviving major films! 🎭 [Source](https://hitchcock.fandom.com/wiki/Alfred_Hitchcock_cameo_appearances#:~:text=English%20film%20director%20Alfred%20Hitchcock,trying%20to%20spot%20his%20cameos.) -- **Oscar Records:** Walt Disney holds the record for the most Oscars with 22 wins and 59 nominations. πŸ† [Source](https://www.emmys.com/bios/walt-disney#:~:text=As%20a%20film%20producer%2C%20Disney,Emmy%20Award%2C%20among%20other%20honors.) -- **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](https://en.wikipedia.org/wiki/Pirates_of_the_Caribbean:_On_Stranger_Tides#:~:text=Filming%20employed%203D%20cameras%20similar,the%20time%20of%20its%20release.) -- **Film Length:** The longest movie ever made is the experimental film "Modern Times Forever," which runs for 240 hours (10 days). 🎬 [Source](https://www.forbesindia.com/article/explainers/longest-films-by-running-time/93944/1#:~:text=Directed%20by%20the%20Finnish%20art,the%20building%27s%20transformation%20over%20time.) -- **Box Office King:** "Avengers: Endgame" surpassed "Avatar" to become the highest-grossing film of all time. πŸ’° [Source](https://variety.com/2021/film/news/avatar-avengers-endgame-highest-grossing-movie-all-time-1234929216/#:~:text=β€œAvengers%3A%20Endgame”%20eclipsed%20that,to%20a%20historic%20%242.7926%20billion.) +Thank you for your support! ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=Woahai321/list-sync&type=Date)](https://star-history.com/#Woahai321/list-sync&Date) - ---- - -## πŸ›‘οΈ 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: - -1. **Compliance with Overseerr and IMDB:** - - - Users must adhere to the ToS of all third parties in use. - -2. **No Spamming or Abuse:** - - - This tool should not be used for spam or unauthorised import activities. Respect the guidelines and policies of the platforms. - -3. **Managing Rate Limits:** - - - Use the tool thoughtfully to avoid hitting rate limits set by Overseerr. Excessive usage can lead to rate limiting or bans. - -4. **User Consent:** - - - Ensure you have the necessary permissions to import and manage media from IMDB lists. - -5. **Security:** - - - Protect your API credentials and never share them publicly. - -6. **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. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..06f2a20 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,75 @@ +# Contributing to ListSync + +We're thrilled that you're interested in contributing to ListSync! This document provides guidelines for contributing to the project. By participating in this project, you agree to abide by its terms. + +## Table of Contents + +1. [Code of Conduct](#code-of-conduct) +2. [Getting Started](#getting-started) +3. [How to Contribute](#how-to-contribute) +4. [Style Guidelines](#style-guidelines) +5. [Commit Messages](#commit-messages) +6. [Pull Requests](#pull-requests) +7. [Reporting Bugs](#reporting-bugs) +8. [Suggesting Enhancements](#suggesting-enhancements) +9. [Questions](#questions) + +## Code of Conduct + +This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [project_email@example.com]. + +## Getting Started + +1. Fork the repository on GitHub. +2. Clone your fork locally: `git clone https://github.com/your-username/list-sync.git` +3. Create a branch for your changes: `git checkout -b your-branch-name` +4. Make your changes and commit them (see [Commit Messages](#commit-messages)). +5. Push your changes to your fork: `git push origin your-branch-name` +6. Create a pull request (see [Pull Requests](#pull-requests)). + +## How to Contribute + +- Fix bugs or implement new features. +- Improve documentation. +- Write tests to increase code coverage. +- Review pull requests. + +## Style Guidelines + +- Follow PEP 8 style guide for Python code. +- Use meaningful variable and function names. +- Write clear, concise comments and docstrings. +- Keep functions small and focused on a single task. + +## Commit Messages + +- Use the present tense ("Add feature" not "Added feature"). +- Use the imperative mood ("Move cursor to..." not "Moves cursor to..."). +- Limit the first line to 72 characters or less. +- Reference issues and pull requests liberally after the first line. + +## Pull Requests + +1. Ensure your code adheres to the style guidelines. +2. Update the README.md with details of changes, if applicable. +3. Increase version numbers in any examples files and the README.md to the new version that this Pull Request would represent. +4. You may merge the Pull Request once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you. + +## Reporting Bugs + +1. Use the GitHub issue tracker to report bugs. +2. Describe the bug in detail, including steps to reproduce. +3. Include information about your environment (OS, Python version, etc.). +4. If possible, provide a minimal code example that demonstrates the issue. + +## Suggesting Enhancements + +1. Use the GitHub issue tracker to suggest enhancements. +2. Provide a clear and detailed explanation of the feature you want to see. +3. Explain why this enhancement would be useful to most ListSync users. + +## Questions + +If you have any questions about contributing, please open an issue with your question. We'll do our best to provide guidance and clarification. + +Thank you for contributing to ListSync! Your efforts help make this project better for everyone. diff --git a/docs/how-it-works.md b/docs/how-it-works.md new file mode 100644 index 0000000..d5e6d5a --- /dev/null +++ b/docs/how-it-works.md @@ -0,0 +1,51 @@ +# How ListSync Works + +ListSync is a powerful tool that bridges your IMDB and Trakt lists with Overseerr, automating the process of importing and managing your media requests. Here's a detailed breakdown of its functionality: + +## 1. Authentication and Security + +- ListSync uses the `cryptography` library's Fernet symmetric encryption to secure your credentials. +- Your encrypted data is stored locally, ensuring that your sensitive information remains protected. + +## 2. List Fetching and Parsing + +### IMDB Lists + +- The tool uses the `requests` library to fetch the HTML content of your IMDB list. +- It then employs `BeautifulSoup` to parse the HTML and extract structured data about movies and TV shows. + +### Trakt Lists + +- A similar process is used for Trakt lists. +- The HTML response is parsed to extract media information. + +## 3. Overseerr Integration + +- ListSync interacts with the Overseerr API using the `requests` library. +- It implements minimal rate limiting to prevent overwhelming the Overseerr server and webhooks. +- The tool performs media searches, status checks, and request submissions via API endpoints. + +## 4. Intelligent Processing + +- ListSync differentiates between movies and TV shows for appropriate handling. +- For TV shows, it determines the number of seasons and requests all available seasons. +- The tool checks if media is already available or requested before submitting new requests. + +## 5. Error Handling and Logging + +- Comprehensive error handling is implemented for network issues, API errors, and parsing problems. +- ListSync uses Python's `logging` module to maintain detailed logs for troubleshooting. +- Real-time status updates are provided in the console using the `colorama` and `halo` libraries. + +## 6. Periodic Syncing + +- Users can set up recurring syncs at user-defined intervals. +- A sleep mechanism is implemented that can be interrupted for on-demand actions. + +## 7. User Interface + +- ListSync presents a user-friendly command-line interface with color-coded outputs. +- ASCII art and banners are displayed for an engaging user experience. +- Summary statistics are provided after each sync operation. + +By leveraging these components, ListSync provides a seamless, automated solution for managing your media library through Overseerr. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..83aeeb8 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,116 @@ +# Installation Guide + +This guide provides detailed instructions for installing and setting up ListSync using different methods. Choose the method that best suits your needs and technical expertise. + +## Table of Contents + +1. [Docker Installation (Recommended)](#docker-installation-recommended) +2. [Standard Python Environment](#standard-python-environment) +3. [Poetry Installation](#poetry-installation) +4. [Configuration](#configuration) + +## Docker Installation (Recommended) + +Docker ensures ListSync runs consistently across different environments. + +### Prerequisites + +- Docker installed on your system. If not, follow the [official Docker installation guide](https://docs.docker.com/get-docker/). + +### Steps + +1. **Create a working directory:** + Make a folder to house the application's log files (e.g., list-sync) + +2. **Pull and Run the Docker Image:** + Navigate to your directory and use the following command: + + ```sh + 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 + ``` + +3. **For subsequent runs:** + Use this command: + + ```sh + 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 ListSync in a standard Python environment: + +### Prerequisites + +- Python 3.9 or higher installed on your system + +### Steps + +1. **Clone the Repository:** + + ```sh + git clone https://github.com/woahai321/list-sync.git + cd list-sync + ``` + +2. **Install Dependencies:** + + ```sh + pip install -r requirements.txt + ``` + +3. **Run the Script:** + ```sh + python add.py + ``` + +## Poetry Installation + +Poetry offers advantages in dependency management and environment isolation. + +### Prerequisites + +- Python 3.9 or higher installed on your system + +### Steps + +1. **Install Poetry:** + + ```sh + curl -sSL https://install.python-poetry.org | python3 - + ``` + +2. **Clone the Repository:** + + ```sh + git clone https://github.com/woahai321/list-sync.git + cd list-sync + ``` + +3. **Install Dependencies:** + + ```sh + poetry install + ``` + +4. **Run the Script:** + ```sh + poetry run python add.py + ``` + +## Configuration + +After installation, follow these steps to configure ListSync: + +1. Run the script using your chosen installation method. +2. You will be prompted to enter the following information: + - 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 +3. Enter a password to encrypt your configuration when prompted. +4. Your encrypted configuration will be saved for future use. + +For more information on obtaining list IDs, refer to the [Obtaining List IDs](/docs/obtaining-list-ids.md) guide. + +If you encounter any issues during installation or configuration, please refer to our [Troubleshooting Guide](/docs/troubleshooting.md). diff --git a/docs/legal-disclamer.md b/docs/legal-disclamer.md new file mode 100644 index 0000000..2bd8aeb --- /dev/null +++ b/docs/legal-disclamer.md @@ -0,0 +1,45 @@ +# Legal Disclaimer + +This legal disclaimer applies to the use of ListSync, a tool designed to automate the import of IMDB and Trakt lists into Overseerr. By using ListSync, you agree to comply with this disclaimer and all applicable laws and regulations. + +## Terms of Use + +1. **Compliance with Third-Party Terms of Service:** + Users of ListSync must adhere to the Terms of Service (ToS) of all third-party services utilized by the tool, including but not limited to Overseerr, IMDB, and Trakt. It is your responsibility to review and comply with these terms. + +2. **Prohibited Activities:** + ListSync should not be used for any unauthorized or illegal activities, including but not limited to: + + - Spamming or abusive behavior + - Unauthorized access to third-party services + - Violation of copyright or other intellectual property rights + +3. **Rate Limiting and Responsible Use:** + Users must use ListSync responsibly and be mindful of rate limits set by third-party services. Excessive use that leads to rate limiting or bans is solely the responsibility of the user. + +4. **User Consent and Permissions:** + Ensure you have the necessary rights and permissions to import and manage media from IMDB and Trakt lists. Do not import or manage media that you do not have the legal right to access or distribute. + +5. **Security and API Credentials:** + Protect your API credentials and never share them publicly. You are responsible for maintaining the security of your account and credentials. + +6. **No Warranty:** + ListSync is provided "as is" without any warranties of any kind, either express or implied. The creators and contributors of ListSync do not warrant that the tool will be error-free or uninterrupted. + +7. **Limitation of Liability:** + The creators and contributors of ListSync shall not be liable for any direct, indirect, incidental, special, consequential, or exemplary damages resulting from the use or inability to use the tool. + +8. **Indemnification:** + You agree to indemnify, defend, and hold harmless the creators and contributors of ListSync from any claims, liabilities, damages, losses, and expenses arising from your use of the tool or violation of this disclaimer. + +9. **Changes to the Tool and Disclaimer:** + The creators of ListSync reserve the right to modify, suspend, or discontinue the tool at any time without notice. This disclaimer may also be updated periodically, and continued use of the tool constitutes acceptance of any changes. + +10. **Governing Law:** + This disclaimer shall be governed by and construed in accordance with the laws of [Your Jurisdiction], without regard to its conflict of law provisions. + +## Responsibility + +By using ListSync, you acknowledge that you are solely responsible for your actions while using this tool. The creators and contributors of ListSync are not liable for any misuse, legal consequences, or damages arising from its use. + +If you do not agree with any part of this disclaimer, please refrain from using ListSync. diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..358936e --- /dev/null +++ b/docs/roadmap.md @@ -0,0 +1,55 @@ +# ListSync Roadmap + +This document outlines our plans for future development and features for ListSync. Our roadmap is divided into small, medium, and big tasks to give you an idea of what to expect in upcoming releases. + +## βœ… Completed Tasks + +### Small Tasks + +- Enhanced Error Messages: Improved error descriptions for easier troubleshooting. +- Advanced Error Handling: Implemented more robust error handling for clearer troubleshooting. +- Secure User Profiles: Added ability to save and load Overseerr details from an encrypted configuration file. +- Real-time Progress Updates: Implemented real-time progress updates for importing movies and TV shows. + +### Medium Tasks + +- Integration with Trakt: Successfully integrated Trakt list support. +- Interruptible Sleep Mode: Added functionality for interrupting sleep mode for on-demand sync or clean exit. +- Configuration Management: Implemented save and reuse of configuration setups. +- Batch Processing: Enabled batch processing for multiple lists simultaneously. +- Support for TV Shows: Extended functionality to import TV shows from IMDB and Trakt lists. +- Database Integration: Implemented a real database to track sync history and metrics. + +### Big Tasks + +- Automated Syncing: Implemented scheduled automatic syncing between IMDB/Trakt and Overseerr. +- Movie Status Identification: Added ability to identify movies already available, already requested, or to be requested. +- TV Series Status Identification: Added ability to identify TV series already available, already requested, or to be requested. +- Encrypted Configuration Storage: Implemented encrypted storage for Overseerr API credentials. + +## πŸš€ Upcoming Features + +### Short-term Goals + +- [ ] Improve error handling for network connectivity issues +- [ ] Add support for custom list naming conventions +- [ ] Implement a command-line interface for advanced users + +### Medium-term Goals + +- [ ] Integration with Letterboxd +- [ ] Customization Options: Allow users to fully customize the UI and behavior of the tool +- [ ] Add support for additional media management systems (e.g., Jellyfin, Emby) + +### Long-term Goals + +- [ ] 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 + +## πŸ’‘ Feature Requests + +We welcome feature requests from our users! If you have an idea for a new feature or improvement, please submit it as an issue on our GitHub repository. We'll review all suggestions and update this roadmap accordingly. + +Please note that this roadmap is subject to change based on user feedback, technical constraints, and project priorities. We'll do our best to keep this document updated as we progress. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..5da6fa0 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,70 @@ +# Troubleshooting Guide + +If you're experiencing issues with ListSync, this guide covers common problems and their solutions. + +## 1. Invalid API Credentials + +**Symptom:** Error messages related to API authentication or 401 Unauthorized 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. + +## 2. 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+). + +## 3. 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: `https://trakt.tv/lists/1234567` + +## 4. 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. + +## 5. 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. + +## 6. 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 localized versions. + +## Still Having Issues? + +If you're encountering persistent issues not covered here, please remember that ListSync is in beta development and you may encounter bugs. We appreciate your patience and feedback as we continue to improve the tool. + +For additional support, please raise an issue on the GitHub repository with a detailed description of your problem and any relevant log files.