reelminner

💡 Nota sobre el nombre: El nombre público final de este proyecto es Reelminner. La clase del motor Python es Reelminner (ver scraper.py), la CLI/GUI y el servidor MCP están marcados como reelminner, y el repositorio de GitHub es reelminner. El nombre en clave anterior ReelSnipe se ha retirado por completo. Otras ideas de nombre se enumeran en Opciones de nombre.

📚 Tabla de contenidos

• Qué es Reelminner

• ✨ Características

• 🧠 Cómo funciona

• 🏗️ Arquitectura del proyecto

• 📦 Instalación

• 🚀 Inicio rápido

• 💻 Uso

  • GUI de escritorio

  • Línea de comandos (CLI)

  • Servidor MCP (para agentes de IA)

  • API de Python

• 📊 Formato de salida

• ⚙️ Configuración

• 🗂️ Estructura del proyecto

• 🧪 Pruebas y control de calidad

• 📦 Creación de un EXE independiente

• ⚠️ Aviso legal y ético

• 🤝 Contribuciones

• 📄 Licencia

• 🆘 Solución de problemas y preguntas frecuentes

• 🏷️ Nombre

Related MCP server: Instagram Complete MCP Server

Qué es Reelminner

Reelminner es un conjunto de herramientas de código abierto que extrae datos estructurados de los Reels de Instagram y de los perfiles que los publicaron. Está construido alrededor de un único motor reutilizable (Reelminner) que se expone de cuatro formas diferentes:

Todo comparte la misma lógica de análisis, sesión y límite de velocidad, por lo que los resultados son idénticos sin importar qué interfaz utilices.

✨ Características

• Análisis de reels de múltiples fuentes — Reelminner lee datos de varias capas (JSON incrustado, respuestas GraphQL y un respaldo DOM en vivo) para que siga funcionando incluso cuando Instagram cambia una de ellas.

• Enriquecimiento del perfil del propietario — para cada reel puede obtener automáticamente el username, full_name, bio, followers, is_verified y reels_count del autor.

• Extracción del número de seguidores — obtenido mediante la consulta GraphQL UserByRestrictedView / GraphQLOwnerInfo de Instagram, con respaldo DOM y paginación (maneja cifras de seguidores limitadas como "1.2M" desplazándose por el perfil).

• Metadatos de música — audio del reel music_title, music_artist y music_id.

• Métricas de interacción — views, likes, comments y la video_url / thumbnail directa.

• Gestión de sesión e inicio de sesión — QR/inicio de sesión interactivo, importación de cookies desde exportaciones de EditThisCookie y una renovación de sesión de 24 horas para que no tengas que volver a iniciar sesión constantemente.

• Scraping concurrente — un grupo de hilos (--workers, por defecto 3) con retrasos corteses entre solicitudes (--delay, por defecto 2s) y retroceso adaptativo cuando Instagram devuelve BLOCKED / RATE_LIMITED.

• Seguimiento de estado resistente — cada fila lleva un código status (OK, PARSED_PARTIAL, FAILED, NO_DATA, BLOCKED, RATE_LIMITED) para que sepas exactamente qué ha tenido éxito.

• Múltiples formatos de exportación — CSV (por defecto), JSON y Excel (.xlsx mediante openpyxl).

• Servidor MCP — cinco herramientas estables para que un agente de IA (Claude, Cursor, etc.) pueda hacer scraping, comprobar el estado, importar cookies, detener y exportar.

• GUI de escritorio — tema oscuro integrado, cuadro para pegar URL, tabla de resultados en vivo, clic derecho para copiar URL / abrir reel y exportación con un clic.

• Probado — suite de pytest + un arnés de control de calidad de extremo a extremo que aplica controles de calidad de datos.

🧠 Cómo funciona

┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
│   GUI      │   │    CLI     │   │  MCP srv   │   │  Python    │
│  gui.py    │   │ scraper.py │   │mcp_server  │   │   import   │
└─────┬──────┘   └─────┬──────┘   └─────┬──────┘   └─────┬──────┘
      └────────────────┴────────────────┴────────────────┘
                       ▼
              ┌───────────────────────┐
              │  Reelminner  │  ← the engine (scraper.py)
              │  • session / cookies   │
              │  • thread pool         │
              │  • adaptive back‑off   │
              └───────────┬───────────┘
                          ▼
              ┌───────────────────────┐
              │  parsers.py            │  ← pure extraction helpers
              │  parse_reel_page / json│
              │  parse_owner / music   │
              │  regex adapters         │
              └───────────────────────┘

1. Normaliza la URL de entrada (normalize_reel_url) para que /reel/X/ y /reel/s/…/ funcionen ambos.

2. Carga la sesión — aplica las cookies guardadas (sessionid, csrftoken, ds_user_id, ig_did, mid, rur) o inicia sesión.

3. Obtiene y analiza la página del reel con un respaldo en capas:

   • parse_reel_page → JSON HTML incrustado window.__additionalData / sharedData

   • parse_reel_json → respuesta GraphQL GQL sin procesar

   • parse_graphql_reel → objeto shortcodeMedia

   • Respaldo DOM → _extract_text_raw consulta la página en vivo para obtener me gusta / comentarios / reproducciones / seguidores mediante adaptadores de expresiones regulares.

4. Enriquece el propietario (a menos que se use --no-profiles): obtiene el perfil y lee followers, full_name, bio, is_verified, reels_count.

5. Respeta los límites: espera delay entre solicitudes; si está bloqueado, retrocede y reintenta.

6. Escribe filas en CSV / JSON / Excel con un status por fila.

🏗️ Arquitectura del proyecto

Reelminner es un diseño de motor único, múltiples interfaces. Un motor central (Reelminner) hace todo el trabajo real; la GUI, la CLI, el servidor MCP y la API de Python son interfaces ligeras que lo invocan. Esto mantiene el análisis, la gestión de sesión y el límite de velocidad idénticos en todos los puntos de entrada.

                         ┌─────────────────────────────┐
        URL(s) in ──────▶│     Reelminner     │  scraper.py
                         │  ── engine / orchestrator ──  │
                         └───────┬───────────┬──────────┘
                  run scrapes    │           │  enrich owner
                                 ▼           ▼
                    ┌────────────────┐  ┌──────────────────┐
                    │   parsers.py    │  │ session + graphql│
                    │ pure extractors │  │ (followers/music)│
                    └───────┬────────┘  └─────────┬────────┘
                            └─────────┬────────────┘
                                      ▼
                            ReelData row + status
                                      ▼
                       CSV / JSON / Excel writers

Responsabilidades de los módulos

Detalles internos del motor (Reelminner)

• Capa de sesión — _SESSION_COOKIE_NAMES (sessionid, csrftoken, ds_user_id, ig_did, mid, rur); _apply_cookies(), _refresh_if_needed() (24h), login() (QR interactivo), clear_session().

• Concurrencia — scrape() inicia un ThreadPoolExecutor(max_workers=workers); cada URL es gestionada por _worker → _scrape_url, que llama a _gather_metadata (datos del reel) y opcionalmente a _gather_article (perfil del propietario). Un semáforo + _sleep() garantizan la cortesía; status_code / retcode impulsan un bucle adaptativo de reintento/retroceso cuando Instagram devuelve BLOCKED / RATE_LIMITED.

• Canalización de análisis (respaldo en capas) — dentro de _gather_metadata el motor intenta, en orden: parse_reel_page (JSON HTML incrustado) → parse_reel_json (GraphQL GQL sin procesar) → parse_graphql_reel (shortcodeMedia) → respaldo DOM mediante los adaptadores _extract_text_html / _extract_text_raw y la lista de expresiones regulares _PATTERNS (me gusta/comentarios/reproducciones/seguidores).

• Enriquecimiento de perfil — get_follower_count() utiliza la consulta GraphQL UserByRestrictedView / GraphQLOwnerInfo de Instagram, con respaldo al DOM y paginación de seguidores (_fetch_followers con end_cursor) cuando los recuentos están limitados.

• Salida — las filas se recopilan como diccionarios ReelData y se escriben mediante write_csv (respetando csv_columns), export_json o export_excel (necesita openpyxl).

Por qué esta estructura

• Capacidad de prueba — todo el análisis vive en parsers.py sin dependencia del navegador, por lo que tests/test_parsers.py puede hacer afirmaciones sobre fixtures HTML/JSON guardados.

• Una única fuente de verdad — cada interfaz comparte el mismo Reelminner, por lo que una corrección en el motor beneficia simultáneamente a la GUI, la CLI y el servidor MCP.

• Empaquetado seguro — las interfaces ligeras de GUI/CLI significan que el EXE de PyInstaller solo incluye el motor + una UI mínima, manteniendo el binario pequeño.

📦 Instalación

Requisitos: Python 3.10+ y el motor de navegador Playwright.

# 1. Clone
git clone https://github.com/ilovekushgola/reelminner.git
cd reelminner

# 2. (Recommended) create a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install the Chromium browser for Playwright
playwright install chromium

Solo GUI: la aplicación de escritorio usa tkinter, que viene con las instalaciones estándar de Python. No se necesita ningún paquete adicional. La GUI está más pulida en Windows.

Herramientas opcionales de desarrollo/pruebas:

pip install -r requirements-dev.txt   # pytest, coverage

💡 Antes de empezar: Reelminner funciona mejor con una sesión de Instagram iniciada — algunos reels y todos los datos de propietario/seguidores requieren autenticación. Ejecuta python scraper.py --login una vez (QR interactivo), o importa las cookies exportadas desde la extensión de navegador EditThisCookie con python scraper.py --import-cookies cookies.json. Solo lee contenido público que ya tienes permitido ver.

🚀 Inicio rápido

# Scrape a single reel from the command line
python scraper.py "https://www.instagram.com/reel/CxXYZ123/"

# …or many reels from a file (one URL per line)
python scraper.py -f urls.txt -o export.csv

# Launch the desktop GUI
python gui.py

💻 Uso

1. GUI de escritorio

python gui.py

• Haz clic en Login (opcional pero recomendado: mejora la tasa de éxito).

• Pega una URL de reel por línea en el cuadro (o Ctrl+A para seleccionar todo).

• Arrastra el control deslizante de Workers y luego haz clic en Scrape.

• Observa los resultados aparecer en la tabla.

• Clic derecho en una fila para Copiar URL o Abrir Reel.

• Exportar a CSV / Excel / JSON, o Abrir carpeta de resultados.

Los últimos resultados se guardan automáticamente en results/_last_results.json.

2. Línea de comandos (CLI)

python scraper.py [URL ...] [options]

# Headless, 5 workers, 1s delay, no profile enrichment
python scraper.py -f reels.txt -w 5 --delay 1 --headless --no-profiles -o out.csv

3. Servidor MCP (para agentes de IA)

Reelminner incluye un servidor MCP (Model Context Protocol) para que un cliente de IA pueda manejarlo.

python mcp_server.py            # stdio transport

Configura tu cliente MCP (el .mcp.json está incluido en el repositorio):

{
  "mcpServers": {
    "reelminner": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": ".",
      "env": { "RMIN_HEADLESS": "true" }
    }
  }
}

Herramientas expuestas (5, estables):

Anulaciones de entorno: RMIN_HEADLESS, RMIN_WORKERS, RMIN_DELAY, RMIN_WITH_PROFILES.

4. API de Python

from scraper import Reelminner, write_csv

scraper = Reelminner(workers=3, delay=2.0, headless=True)
rows, report = scraper.scrape(
    ["https://www.instagram.com/reel/CxXYZ123/"],
    with_profiles=True,
)
write_csv(rows, "out.csv")

for r in rows:
    print(r["username"], r["followers"], r["likes"], r["status"])

Miembros clave de Reelminner:

• scrape(urls, with_profiles=True) → (rows, report)

• login() — inicio de sesión interactivo

• has_session() / save_cookies_from_file(path) / clear_session()

• write_csv(rows, path), export_json(rows, path), export_excel(rows, path)

• normalize_reel_url(url) — helper público

• csv_columns — la lista ordenada de campos de salida

• DEFAULT_STATE_FILE — storage_state.json por defecto

📊 Formato de salida

Cada reel se convierte en una fila. El esquema CSV completo (scraper.csv_columns):

⚙️ Configuración

Cookies / sesión

• Inicia sesión con python scraper.py --login (guarda storage_state.json).

• O exporta cookies desde tu navegador mediante la extensión EditThisCookie y ejecuta python scraper.py --import-cookies cookies.json.

Variables de entorno (usadas por el servidor MCP y los valores predeterminados de la CLI)

Se proporciona una plantilla: copia mcp.env.example → mcp.env para anular los valores predeterminados de MCP.

🗂️ Estructura del proyecto

reelminner/
├── scraper.py          # Core engine: Reelminner + CLI
├── gui.py              # Tkinter desktop application
├── parsers.py          # Pure extraction helpers (HTML/JSON/music/regex)
├── mcp_server.py       # MCP server (5 tools for AI agents)
├── theme.py            # Dark‑theme styling for the GUI
├── build_exe.py        # PyInstaller build script
├── Reelminner.spec  # PyInstaller spec (one‑file EXE)
├── run_qa.py           # End‑to‑end QA harness with data‑quality gates
├── requirements.txt    # Runtime dependencies
├── requirements-dev.txt# Dev / test dependencies
├── mcp.env.example     # MCP env template
├── .mcp.json           # MCP client configuration
├── assets/             # Icons (icon.ico)
├── docs/               # SKILL.md, E2E test/fix plan
├── skills/             # Agent skill definition
├── tests/              # pytest suite + corpus.txt
└── results/            # Scrape outputs (git‑ignored)

🧪 Pruebas y control de calidad

# Unit / integration tests
pytest -q

# End‑to‑end data‑quality run (uses your saved session)
python run_qa.py                 # full run over tests/corpus.txt
python run_qa.py --quick         # 1 URL, headless, fast iteration
python run_qa.py --url <reel>    # custom single URL
python run_qa.py --report-only   # show last qa_report.json

El entorno de control de calidad aplica umbrales como tasa de análisis, tasa de verificación, tasa de no vacío, tasa de bloqueo y tiempo máximo de ejecución, y escribe results/qa/qa_report.json + qa_results.csv.

📦 Creación de un EXE independiente

En Windows, produce un .exe portátil (los usuarios finales no necesitan Python):

pip install pyinstaller
python build_exe.py

Salida: dist/Reelminner.exe (compilación de un solo archivo mediante Reelminner.spec).

⚠️ Aviso legal y ético

Reelminner se proporciona solo para uso educativo y autorizado/personal.

• El scraping de Instagram puede violar sus Términos de servicio. Úsalo solo en contenido que poseas o para el que tengas permiso de acceso.

• Respeta los límites de tasa (--delay, menos --workers) y no lo uses para spam, acoso o extracción comercial masiva.

• Eres responsable de cómo usas esta herramienta y de cumplir con las leyes aplicables (incl. GDPR / normativas de privacidad) en tu jurisdicción.

• Los autores no están afiliados a Instagram/Meta y no aceptan responsabilidad alguna.

🆘 Solución de problemas y preguntas frecuentes

playwright dice que el navegador no está instalado / las páginas no se abren → Asegúrate de haber ejecutado tanto pip install -r requirements.txt como playwright install chromium. Sin la descarga de Chromium, nada se iniciará.

La mayoría de los campos están vacíos, o recibo BLOCKED / RATE_LIMITED → Inicia sesión (python scraper.py --login) o importa cookies, luego reduce la velocidad: --delay 4 y menos trabajadores (-w 1). Instagram limita más el tráfico anónimo/no autenticado, por lo que una sesión autenticada es el factor de éxito más importante.

Un reel devuelve NO_DATA → La publicación puede ser privada, eliminada o bloqueada por región, o Instagram mostró un muro de inicio de sesión. Inténtalo de nuevo con una sesión iniciada.

La ventana de la GUI no se abre o las fuentes se ven mal → La GUI usa el tkinter integrado de Python. En Windows es la más pulida. En Linux/macOS instala el paquete Tk si la ventana no se inicia (p. ej. sudo apt install python3-tk).

ModuleNotFoundError al ejecutar un script → Probablemente estás fuera del repositorio o de su entorno virtual. cd a la carpeta del proyecto y activa el venv (.venv\Scripts\activate en Windows, source .venv/bin/activate en macOS/Linux) antes de ejecutar python scraper.py.

¿Cómo raspo muchos reels a la vez? → Pon una URL por línea en un archivo de texto y ejecuta python scraper.py -f urls.txt -o out.csv.

¿Puede un agente de IA usar esto? → Sí: ejecuta python mcp_server.py y apunta cualquier cliente MCP (Claude Desktop, Cursor, etc.) al .mcp.json incluido. Consulta Servidor MCP.

🤝 Contribuciones

1. Haz un fork del repositorio y crea una rama de características.

2. pip install -r requirements-dev.txt

3. Añade/ajusta pruebas en tests/; ejecuta pytest y python run_qa.py --quick.

4. Abre una solicitud de extracción (pull request) describiendo el cambio y el resultado del control de calidad.

📄 Licencia

Publicado bajo la Licencia MIT — consulta LICENSE.

🏷️ Nombre

El nombre público final del proyecto es Reelminner ("Reel miner"). Los nombres en clave internos anteriores se han retirado. Si haces un fork, puedes renombrarlo como quieras: solo actualiza el título en gui.py y este README.