03-sep: [videoclub] Busqueda global (miles de pelis) via Cinemeta+Torrentio con /busca /torrents /bajar a NAS

documentacion/guia-busqueda-global-videoclub-2026-09-03.md

@@ -0,0 +1,67 @@
+# Guía — Búsqueda global del videoclub (miles de películas)
+
+**Fecha:** 3 Septiembre 2026
+**Autor:** asistente laboratorio
+
+## Qué resuelve
+
+El catálogo de Torrentio/RealDebrid (`/pelicula`, `/serie`) solo muestra lo que
+**ya tienes** en tu cuenta de RealDebrid (tus 51 items). Para buscar películas y
+series que **NO tienes todavía** —es decir, "miles de películas" de todo
+internet— se añade la **búsqueda global** con los comandos `/busca`, `/torrents`
+y `/bajar`.
+
+## Cómo funciona (2 pasos internos)
+
+```
+/busca <texto>
+   ↓  Cinemeta (Stremio, sin clave): texto → títulos + id IMDb
+  1. Interstellar        tt0816692
+  2. The Science of...   tt4415360
+   ↓  /torrents <n>
+  1. 4K  | 7.5GB | 👤37 | Interstellar...2160p...x265-QTZ.mkv
+  2. 1080p| 4.2GB | 👤511| Interstellar.2014.PROPER.IMAX.1080p...
+   ↓  /bajar <n>
+  Magnet → Download Station del NAS  (baja y deja sembrando)
+```
+
+1. **Texto → título:** `Cinemeta` (v3-cinemeta.strem.io) resuelve tu texto a los
+   títulos top con su id IMDb. Sin API key.
+2. **Título → torrents:** `Torrentio` (/stream/movie|series/{imdb}.json) escanea
+   en tiempo real **1337x, PirateBay, TorrentGalaxy, Wolfmax4k, MejorTorrent...**
+   y devuelve decenas/cientos de torrents reales por título (de ahí las
+   "miles de pelis").
+3. **Torrent → NAS:** construimos el `magnet` desde el `infoHash` y lo enviamos a
+   Synology Download Station, que se descarga la película.
+
+## Cómo usarlo (desde Telegram)
+
+- `/busca `<b>interstellar</b> → lista de títulos numerados
+- `/torrents `2` → torrents reales del título 2 (calidad, tamaño, seeders)
+- `/bajar `1` → descarga al NAS el torrent 1
+
+Cada número se elige en un comando nuevo. El bot recuerda tu última búsqueda por
+chat, así que no hace falta repetir el nombre.
+
+## Archivos nuevos/modificados
+
+- `videoclub/global_buscar.py` — módulo nuevo de búsqueda global
+  - `buscar_titulos(texto)` → Cinemeta
+  - `torrents_de(imdb_id, tipo)` → Torrentio
+  - `filtrar_torrents()` → filtra calidad mala, ruso/tamil/otros idiomas
+  - `magnet_de(torrent)` → magnet a partir de infoHash
+  - `formatear_titulos()` / `formatear_torrents()` → mensajes numerados
+- `vigilancia/pi_bot.py` — comandos `/busca`, `/torrents`, `/bajar` +
+  estado por chat
+- Reutiliza `vigilancia/nas_dl.py` (Download Station) y
+  `videoclub/videoclub_buscador.py` (filtros de idioma/calidad)
+
+## Notas
+
+- Los filtros quitan CAMrips, y releases en ruso/tamil/hindi/etc. para quedarse
+  con contenido en **castellano o inglés**.
+- Los resultados se ordenan por calidad (4K → 1080p → 720p) y luego por seeders.
+- Torrentio consulta muchos proveedores en tiempo real: para títulos raros puede
+  tardar unos segundos o devolver pocos resultados.
+- Para desplegar en la Pi: `git pull` + reiniciar el servicio `pi-bot`
+  (la búsqueda global necesita que `np`/`python` tenga salida a internet).