dgongut/torrent-controller-bot repository overview

⁠Torrent-Controller-Bot

VERSIÓN EN ESPAÑOL | ENGLISH VERSION⁠

Lleva el control de tu gestor de torrents desde un único lugar.

• ✅ Panel de control con estado general: velocidades, espacio libre y torrents agrupados por estado
• ✅ Listado de torrents con filtros (descargando, compartiendo, pausados, completados, con error...) y paginación
• ✅ Búsqueda de torrents por nombre o por ruta
• ✅ Añadir torrents enviando un fichero .torrent, un enlace magnet o una URL a un fichero .torrent, eligiendo el directorio de descarga
• ✅ Pausar, reanudar, verificar y borrar torrents (con o sin sus datos)
• ✅ Mover torrents de directorio con aviso al terminar el movimiento
• ✅ Renombrado con sugerencia automática para películas y series (The.Matrix.1999.1080p.mkv → The Matrix (1999) - 1080p.mkv)
• ✅ Renombrado de los archivos que hay dentro de un torrent, uno a uno o en lote, arrastrando los subtítulos
• ✅ Acciones masivas sobre un filtro o búsqueda: reanudar, pausar, borrar o mover todos
• ✅ Filtro de torrents por tracker e información del tracker en el detalle de cada torrent
• ✅ Ajustes del gestor: modo tortuga y límites de velocidad de subida/bajada
• ✅ Notificaciones de descarga completada y de errores en torrents (activables desde los ajustes)
• ✅ Descarga automática sin preguntar la ruta, con directorio configurable
• ✅ Renombrado automático al añadir un torrent, opcionalmente también de los archivos que contiene (activable desde los ajustes)
• ✅ Aviso si el torrent que añades puede no caber en el disco
• ✅ Ajustes del bot persistentes entre reinicios (volumen /config)
• ✅ Notificación al administrador al arrancar el bot
• ✅ Diseñado para bibliotecas grandes (probado con más de 10.000 torrents)
• ✅ Imagen multiarquitectura (amd64, arm64, armv7…) compatible con Raspberry Pi, NAS y servidores estándar
• ✅ Soporte de idiomas (Spanish, English)

Actualmente soporta Transmission, qBittorrent y Deluge como gestores de torrents. La arquitectura interna es agnóstica al cliente, por lo que en el futuro podrán añadirse otros gestores.

¿Lo buscas en ?

⁠Crear tu bot de Telegram

Antes de levantar el contenedor necesitas un bot propio en Telegram y conocer tu identificador de usuario.

1. Abre @BotFather⁠ en Telegram y envía /newbot. Sigue las instrucciones (un nombre y un username acabado en bot).

1. BotFather te devolverá el token del bot. Guárdalo: irá en la variable TELEGRAM_TOKEN.
2. Para conocer tu propio chat ID (lo necesitas para TELEGRAM_ADMIN), habla con @MissRose_bot⁠ y envíale /id. Te responderá con un número, ese es tu ID.
3. (Opcional) Si vas a usar el bot dentro de un grupo, añádelo, hazlo administrador y obtén el chat ID del grupo de la misma forma; ese valor irá en TELEGRAM_GROUP.
4. (Opcional) Si quieres ponerle el icono oficial al bot, descarga la imagen en alta resolución aquí⁠ y envíasela a @BotFather⁠ usando la opción /setuserpic.

⁠Comandos disponibles

⁠Renombrado inteligente

Al pulsar ✏️ Renombrar sobre un torrent, el bot intenta generar una sugerencia de nombre limpio:

• Películas: The.Matrix.1999.1080p.BluRay.x264.mkv → The Matrix (1999) - 1080p.mkv
• Series: Operaciones Especiales Lioness [HDTV 1080p][Cap.103] → 1x03 - Operaciones Especiales Lioness - 1080p (soporta formatos Cap.103, S01E03 y 3x05)

Si no puede generar sugerencia, siempre puedes escribir el nombre manualmente.

⁠Archivos dentro del torrent

Desde el detalle de un torrent, el botón 🗂️ Archivos lista los ficheros que contiene y permite renombrarlos uno a uno o todos de golpe (con previsualización antes de confirmar). Los archivos heredan del nombre del torrent lo que no llevan encima (título, año y temporada, nunca el episodio), así que un episodio suelto como 01.mkv dentro de Show.Name.S02.1080p se convierte en 2x01 - Show Name - 1080p.mkv. Los subtítulos que acompañan a un vídeo se renombran con él para no romper el emparejamiento, y todo se hace a través del gestor de torrents, por lo que el seeding se mantiene.

⁠Título del episodio

El campo {titulo_episodio} recoge el texto que va después del marcador de episodio, así que Family.Guy.S01E01.Death.Has.a.Shadow.1080p.mkv conserva Death Has a Shadow. No todos los episodios lo traen, por lo que conviene usarlo siempre entre corchetes:

{temporada}x{episodio.2} - {titulo}[ - {titulo_episodio}][.{extension}]

⁠Relleno con ceros

{temporada} y {episodio} admiten un sufijo .N que rellena el número con ceros hasta N dígitos en total, para que las temporadas y los episodios queden alineados:

Detalles a tener en cuenta:

• El número nunca se recorta: con {episodio.2}, el episodio 123 sigue siendo 123.
• En rangos se rellena cada lado por separado, así que S01-S08 con {temporada.2} da 01-08.
• Solo funciona en {temporada} y {episodio}; en cualquier otro campo el bot rechaza la plantilla.
• {capitulo} no se ve afectado: mantiene siempre su formato de dos dígitos (1x03, T2).

⁠Configuración en las variables del Docker Compose

⁠Ejemplo de Docker-Compose para su ejecución normal

services:
    torrent-controller-bot:
        environment:
            - TELEGRAM_TOKEN=
            - TELEGRAM_ADMIN=
            - TZ=Europe/Madrid
            - TORRENT_CLIENT=transmission
            - TORRENT_CLIENT_HOST=
            #- TELEGRAM_GROUP=
            #- TELEGRAM_THREAD=1
            #- LANGUAGE=ES
            #- TORRENT_CLIENT_PORT=9091
            #- TORRENT_CLIENT_USER=
            #- TORRENT_CLIENT_PASSWORD=
        image: dgongut/torrent-controller-bot:latest
        container_name: torrent-controller-bot
        restart: always
        tty: true
        volumes:
            - /ruta/de/tu/eleccion:/config # Ajustes persistentes del bot

⁠Anotaciones

⁠Solo para desarrolladores

⁠Ejecución con código local

Para su ejecución en local y probar nuevos cambios de código, se necesita renombrar el fichero .env.example a .env con los valores necesarios para su ejecución. Es necesario establecer un TELEGRAM_TOKEN y un TELEGRAM_ADMIN correctos y diferentes al de la ejecución normal.

La estructura de carpetas debe quedar:

torrent-controller-bot/
    ├── .env
    ├── .gitignore
    ├── LICENSE
    ├── requirements.txt
    ├── README.md
    ├── bot_settings.py
    ├── config.py
    ├── logger.py
    ├── message_queue.py
    ├── name_parser.py
    ├── torrent-controller-bot.py
    ├── Dockerfile_local
    ├── docker-compose.yaml
    ├── torrent_clients
    │   ├── __init__.py
    │   ├── base.py
    │   ├── deluge_client.py
    │   ├── factory.py
    │   ├── qbittorrent_client.py
    │   └── transmission_client.py
    └── locale
        ├── en.json
        └── es.json

Para levantarlo habría que ejecutar en esa ruta: docker compose -f docker-compose.yaml up -d --build --force-recreate utilizando el Dockerfile_local.

También puede ejecutarse directamente con Python:

pip install -r requirements.txt
set -a && source .env && set +a
LOCALE_PATH=./locale python3 torrent-controller-bot.py