Plex TMDb Checker

Compara series en Plex Media Server contra The Movie Database (TMDb) para detectar episodios y temporadas faltantes, obtener plataformas de streaming disponibles, y enviar reporte diario por Telegram.

---

Características

• Compara episodios disponibles en Plex vs emitidos segun TMDb
• Detecta episodios y temporadas faltantes por serie
• Obtiene plataformas de streaming donde ver el contenido faltante
• 6 estrategias en cadena para encontrar el ID de TMDb (override manual, etiqueta {tmdb-XXXXX} en nombre de carpeta, busqueda por titulo, titulo original, variaciones de año)
• Reporte diario automatico por Telegram con formato Markdown
• Exclusion de series y secciones configurables via YAML
• Multi-threading para procesamiento paralelo
• Modo dry-run para previsualizar sin enviar a Telegram
• Logging detallado a archivo

---

Requisitos

• Python 3.12 o superior
• Servidor Plex Media Server accesible (con token de autenticacion)
• API key de TMDb (gratuita, solicitar aqui)
• (Opcional) Bot de Telegram y Chat ID

---

Instalacion

# Clonar o copiar los archivos
cd plex-tmdb-checker

# Crear entorno virtual
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\activate   # Windows

# Instalar dependencias
pip install -r requirements.txt

# Copiar y configurar .env (ver Configuracion)
# Editar .env con tus credenciales

---

Configuracion

.env

Crear archivo .env en la raiz del proyecto:

PLEX_URL=http://192.168.1.100:28888
PLEX_TOKEN=token_aqui
TMDB_API_KEY=api_key_aqui
TELEGRAM_BOT_TOKEN=bot_token_aqui    # vacio = solo dry-run
TELEGRAM_CHAT_ID=123456789           # ID del chat/grupo
WATCH_REGION=ES                      # opcional, default ES
MAX_WORKERS=8                        # hilos paralelos
DEBUG=false                          # logs detallados

exclusions.yaml

# Series a excluir (coincidencia exacta, case-sensitive)
exclude_series:
  - "Friends"
  - "Los Simpson"

# Secciones Plex a saltar (por ID numerico)
exclude_sections: []

# Override manual de TMDb ID para busquedas fallidas
tmdb_id_overrides:
  "M. El hijo del siglo (2025)": 212333

---

Uso

# Ejecucion normal
python main.py

# Modo debug (logs detallados)
python main.py --debug

# Solo previsualizar en consola, sin enviar a Telegram
python main.py --dry-run

Exit codes

Codigo	Significado
0	Ejecucion exitosa
1	Faltan credenciales o no hay secciones en Plex

---

Como Funciona

1. Carga configuracion (.env + exclusions.yaml)
2. Consulta secciones de series en Plex
3. Por cada serie (en paralelo):
   a. Busca su ID en TMDb (6 estrategias en cadena)
   b. Obtiene episodios por temporada desde TMDb
   c. Obtiene episodios por temporada desde Plex
   d. Compara y detecta faltantes
   e. Si falta contenido, busca plataformas de streaming
4. Acumula metricas globales
5. Envia reporte diario a Telegram (o lo muestra en consola)

---

Estructura del Proyecto

plex-tmdb-checker/
├── main.py                # Punto de entrada, orquestacion
├── config.py              # Carga configuracion (.env + YAML)
├── plex_client.py         # Cliente API XML de Plex
├── tmdb_client.py         # Cliente API REST de TMDb
├── comparator.py          # Logica de comparacion + dataclasses
├── id_extractor.py        # Extrae TMDb ID de rutas de archivo
├── telegram_bot.py        # Formateo y envio a Telegram
├── utils.py               # Utilidades (HTTP retry, rate limiter, logging)
├── exclusions.yaml        # Exclusiones configurables
├── requirements.txt       # Dependencias Python
├── .env                   # Configuracion local (no incluido en git)
├── .gitignore             # Archivos ignorados por git
├── AGENTS.md              # Documentacion para agentes IA
├── README.md              # Este archivo
├── logs/                  # Archivos de log (gitignorado)
└── venv/                  # Entorno virtual (gitignorado)

---

Estrategia de Busqueda de TMDb ID

Para cada serie, se intentan 6 estrategias en orden:

1. Override manual — exclusions.yaml → tmdb_id_overrides
2. Etiqueta en ruta — {tmdb-XXXXX} en nombre de carpeta/archivo
3. Titulo + año — busqueda directa en TMDb
4. Titulo original + año — si difiere del titulo
5. Titulo + año+1 — si el año no da resultado
6. Titulo original + año+1 — combinacion final

---

Ejemplo de Salida (Dry-Run)

📂 Series (id 1)
🕧 Series encontradas: 150
  ↳ Faltante: 3
  ↳ No encontradas: 1
  ↳ Completas: 146
  ↳ Excluidas: 0

🔎 Breaking Bad (2008)
✅ TMDb ID: 1396
📊 Faltante:
  ↳ T5: 9-16
📺 Netflix, AMC+

📊 Reporte generado:
  • Series con faltante: 3
  • Temporadas pendientes: 5
  • Episodios faltantes: 24
  • Tiempo ejecucion: 45.2s
  • Top plataformas: [('Netflix', 2), ('HBO Max', 1)]

---

Licencia

MIT License — ver LICENSE.

Copyright (c) 2026