reelminner

💡 Hinweis zum Namen: Der endgültige öffentliche Name dieses Projekts ist Reelminner. Die Python-Engine-Klasse heißt Reelminner (siehe scraper.py), CLI/GUI und MCP-Server sind als reelminner gebrandet, und das GitHub-Repository heißt reelminner. Der frühere Arbeitscodename ReelSnipe wurde vollständig eingestellt. Weitere Namensideen findest du unter Namensoptionen.

📚 Inhaltsverzeichnis

• Was ist Reelminner

• ✨ Funktionen

• 🧠 So funktioniert es

• 🏗️ Projektarchitektur

• 📦 Installation

• 🚀 Schnellstart

• 💻 Verwendung

  • Desktop-GUI

  • Kommandozeile (CLI)

  • MCP-Server (für KI-Agenten)

  • Python-API

• 📊 Ausgabeformat

• ⚙️ Konfiguration

• 🗂️ Projektstruktur

• 🧪 Tests & QA

• 📦 Erstellen einer eigenständigen EXE

• ⚠️ Rechtlicher & ethischer Haftungsausschluss

• 🤝 Mitwirken

• 📄 Lizenz

• 🆘 Fehlerbehebung & FAQ

• 🏷️ Name

Related MCP server: Instagram Complete MCP Server

Was ist Reelminner

Reelminner ist ein Open-Source-Toolkit, das strukturierte Daten aus Instagram-Reels und den Profilen, die sie gepostet haben, extrahiert. Es basiert auf einer einzigen, wiederverwendbaren Engine (Reelminner), die auf vier verschiedene Arten bereitgestellt wird:

Alles teilt sich dieselbe Parsing-, Sitzungs- und Rate-Limit-Logik, sodass die Ergebnisse identisch sind, egal welche Oberfläche du verwendest.

✨ Funktionen

• Mehrschichtiges Reel-Parsing — Reelminner liest Daten aus mehreren Ebenen (eingebettetes JSON, GraphQL-Antworten und einen Live-DOM-Fallback), sodass es auch dann weiter funktioniert, wenn Instagram eine davon ändert.

• Anreicherung des Besitzerprofils — für jedes Reel kann automatisch username, full_name, bio, followers, is_verified und reels_count des Posters abgerufen werden.

• Follower-Zahlen-Extraktion — abgerufen über Instagrams GraphQL-UserByRestrictedView-/GraphQLOwnerInfo-Query, mit DOM-Fallback und Paginierung (behandelt gekappte Follower-Zahlen wie „1,2 Mio.“ durch Scrollen des Profils).

• Musik-Metadaten — Reel-Audio music_title, music_artist und music_id.

• Engagement-Kennzahlen — views, likes, comments sowie die direkte video_url / thumbnail.

• Sitzungs- & Login-Verwaltung — interaktiver QR-Code/Login, Cookie-Import aus EditThisCookie-Exporten und eine 24-Stunden-Sitzungsaktualisierung, damit du dich nicht ständig neu anmelden musst.

• Paralleles Scraping — ein Thread-Pool (--workers, Standard 3) mit höflichen Verzögerungen zwischen Anfragen (--delay, Standard 2s) und adaptivem Back-off, wenn Instagram BLOCKED / RATE_LIMITED zurückgibt.

• Robuste Statusverfolgung — jede Zeile trägt einen status-Code (OK, PARSED_PARTIAL, FAILED, NO_DATA, BLOCKED, RATE_LIMITED), sodass du genau weißt, was erfolgreich war.

• Mehrere Exportformate — CSV (Standard), JSON und Excel (.xlsx über openpyxl).

• MCP-Server — fünf stabile Tools, damit ein KI-Agent (Claude, Cursor usw.) scrapen, den Status prüfen, Cookies importieren, stoppen und exportieren kann.

• Desktop-GUI — integriertes dunkles Design, URL-Eingabefeld, Live-Ergebnistabelle, Rechtsklick URL kopieren / Reel öffnen und Export mit einem Klick.

• Getestet — pytest-Suite plus ein End-to-End-QA-Harness, der Datenqualitäts-Gates durchsetzt.

🧠 So funktioniert es

┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
│   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. URL normalisieren (normalize_reel_url), sodass sowohl /reel/X/ als auch /reel/s/…/ funktionieren.

2. Sitzung laden — gespeicherte Cookies anwenden (sessionid, csrftoken, ds_user_id, ig_did, mid, rur) oder einloggen.

3. Reel-Seite abrufen & parsen mit einem mehrschichtigen Fallback:

   • parse_reel_page → eingebettetes window.__additionalData / sharedData-HTML-JSON

   • parse_reel_json → rohe GraphQL-GQL-Antwort

   • parse_graphql_reel → shortcodeMedia-Objekt

   • DOM-Fallback → _extract_text_raw fragt die Live-Seite nach Likes / Kommentaren / Aufrufen / Followern über Regex-Adapter ab.

4. Besitzer anreichern (außer bei --no-profiles): Profil abrufen und followers, full_name, bio, is_verified, reels_count lesen.

5. Limits respektieren: delay zwischen Anfragen abwarten; bei Blockierung Back-off und erneuter Versuch.

6. Zeilen schreiben in CSV / JSON / Excel mit einem status pro Zeile.

🏗️ Projektarchitektur

Reelminner ist ein Ein-Engine-, Multi-Schnittstellen-Design. Eine Kern-Engine (Reelminner) erledigt die gesamte eigentliche Arbeit; GUI, CLI, MCP-Server und Python-API sind dünne Frontends, die darauf zugreifen. Dadurch bleiben Parsing, Sitzungsverwaltung und Rate-Limiting an jedem Einstiegspunkt identisch.

                         ┌─────────────────────────────┐
        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

Modulverantwortlichkeiten

Engine-Interna (Reelminner)

• Sitzungsebene — _SESSION_COOKIE_NAMES (sessionid, csrftoken, ds_user_id, ig_did, mid, rur); _apply_cookies(), _refresh_if_needed() (24h), login() (interaktiver QR-Code), clear_session().

• Parallelität — scrape() startet einen ThreadPoolExecutor(max_workers=workers); jede URL wird von _worker → _scrape_url verarbeitet, das _gather_metadata (Reel-Daten) und optional _gather_article (Besitzerprofil) aufruft. Ein Semaphor + _sleep() erzwingen Höflichkeit; status_code / retcode steuern eine adaptive Wiederholungs-/Back-off-Schleife, wenn Instagram BLOCKED / RATE_LIMITED zurückgibt.

• Parsing-Pipeline (mehrschichtiger Fallback) — innerhalb von _gather_metadata versucht die Engine der Reihe nach: parse_reel_page (eingebettetes HTML-JSON) → parse_reel_json (rohe GraphQL-GQL) → parse_graphql_reel (shortcodeMedia) → DOM-Fallback über die _extract_text_html- / _extract_text_raw-Adapter und die _PATTERNS-Regex-Liste (Likes/Kommentare/Aufrufe/Follower).

• Profil-Anreicherung — get_follower_count() verwendet Instagrams GraphQL-UserByRestrictedView- / GraphQLOwnerInfo-Query, fällt auf das DOM zurück und paginiert Follower (_fetch_followers mit end_cursor), wenn Zahlen gekappt sind.

• Ausgabe — Zeilen werden als ReelData-Dicts gesammelt und von write_csv (unter Beachtung von csv_columns), export_json oder export_excel (benötigt openpyxl) geschrieben.

Warum dieses Layout

• Testbarkeit — das gesamte Parsing lebt in parsers.py ohne Browser-Abhängigkeit, sodass tests/test_parsers.py auf gespeicherten HTML/JSON-Fixtures Assertions ausführen kann.

• Eine einzige Quelle der Wahrheit — jede Schnittstelle teilt sich dieselbe Reelminner-Engine, sodass ein Fix in der Engine GUI, CLI und MCP-Server gleichzeitig verbessert.

• Sicheres Packaging — die dünnen GUI/CLI-Hüllen bedeuten, dass die PyInstaller-EXE nur die Engine + eine minimale UI bündelt, was die Binärdatei klein hält.

📦 Installation

Anforderungen: Python 3.10+ und die Playwright-Browser-Engine.

# 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

Nur GUI: Die Desktop-App verwendet tkinter, das bei Standard-Python-Installationen enthalten ist. Kein zusätzliches Paket nötig. Die GUI ist auf Windows am ausgereiftesten.

Optionale Entwicklungs-/Test-Tools:

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

💡 Bevor du loslegst: Reelminner funktioniert am besten mit einer angemeldeten Instagram-Sitzung — einige Reels und alle Besitzer-/Follower-Daten erfordern eine Authentifizierung. Führe einmal python scraper.py --login aus (interaktiver QR-Code) oder importiere Cookies, die mit der EditThisCookie-Browsererweiterung exportiert wurden, über python scraper.py --import-cookies cookies.json. Es liest nur öffentliche Inhalte, die du ohnehin ansehen darfst.

🚀 Schnellstart

# 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

💻 Verwendung

1. Desktop-GUI

python gui.py

• Klicken Sie auf Login (optional, aber empfohlen — verbessert die Erfolgsquote).

• Fügen Sie eine Reel-URL pro Zeile in das Feld ein (oder Strg+A, um alles auszuwählen).

• Ziehen Sie den Workers-Regler und klicken Sie dann auf Scrape.

• Beobachten Sie, wie die Ergebnisse in der Tabelle erscheinen.

• Rechtsklick auf eine Zeile zum URL kopieren oder Reel öffnen.

• Export als CSV / Excel / JSON oder Ergebnisordner öffnen.

Die letzten Ergebnisse werden automatisch unter results/_last_results.json gespeichert.

2. Kommandozeile (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. MCP-Server (für KI-Agenten)

Reelminner enthält einen MCP-Server (Model Context Protocol), damit ein KI-Client ihn steuern kann.

python mcp_server.py            # stdio transport

Konfigurieren Sie Ihren MCP-Client (.mcp.json ist im Repository enthalten):

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

Bereitgestellte Tools (5, stabil):

Umgebungsvariablen-Überschreibungen: RMIN_HEADLESS, RMIN_WORKERS, RMIN_DELAY, RMIN_WITH_PROFILES.

4. Python-API

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"])

Wichtige Mitglieder von Reelminner:

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

• login() — interaktive Anmeldung

• 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) — öffentlicher Helfer

• csv_columns — die geordnete Liste der Ausgabefelder

• DEFAULT_STATE_FILE — Standard-storage_state.json

📊 Ausgabeformat

Jede Reel wird zu einer Zeile. Das vollständige CSV-Schema (scraper.csv_columns):

⚙️ Konfiguration

Cookies / Sitzung

• Melden Sie sich mit python scraper.py --login an (speichert storage_state.json).

• Oder exportieren Sie Cookies aus Ihrem Browser über die EditThisCookie-Erweiterung und führen Sie python scraper.py --import-cookies cookies.json aus.

Umgebungsvariablen (werden vom MCP-Server und den CLI-Standardwerten verwendet)

Eine Vorlage ist enthalten: Kopieren Sie mcp.env.example → mcp.env, um die MCP-Standardwerte zu überschreiben.

🗂️ Projektstruktur

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)

🧪 Tests & Qualitätssicherung

# 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

Die QA-Umgebung erzwingt Schwellenwerte wie Parsed-Rate, Verified-Rate, Non-Empty-Rate, Blocked-Rate und maximale Laufzeit und schreibt results/qa/qa_report.json + qa_results.csv.

📦 Erstellen einer eigenständigen EXE

Unter Windows erzeugen Sie eine portable .exe (Endbenutzer benötigen kein Python):

pip install pyinstaller
python build_exe.py

Ausgabe: dist/Reelminner.exe (Ein-Datei-Build über Reelminner.spec).

⚠️ Rechtlicher und ethischer Haftungsausschluss

Reelminner wird nur für Bildungszwecke und autorisierte/persönliche Nutzung bereitgestellt.

• Das Scraping von Instagram kann gegen dessen Nutzungsbedingungen verstoßen. Verwenden Sie es nur für Inhalte, die Sie besitzen oder auf die Sie zugreifen dürfen.

• Respektieren Sie die Ratenbegrenzungen (--delay, weniger --workers) und verwenden Sie es nicht für Spam, Belästigung oder kommerzielle Massenextraktion.

• Sie sind für die Art und Weise verantwortlich, wie Sie dieses Tool verwenden, und für die Einhaltung geltender Gesetze (einschließlich DSGVO-/Datenschutzbestimmungen) in Ihrer Rechtsordnung.

• Die Autoren sind nicht mit Instagram/Meta verbunden und übernehmen keine Haftung.

🆘 Fehlerbehebung & FAQ

playwright meldet, dass der Browser nicht installiert ist / Seiten sich nicht öffnen lassen → Stellen Sie sicher, dass Sie sowohl pip install -r requirements.txt als auch playwright install chromium ausgeführt haben. Ohne den Chromium-Download startet nichts.

Die meisten Felder sind leer, oder ich erhalte BLOCKED / RATE_LIMITED → Melden Sie sich an (python scraper.py --login) oder importieren Sie Cookies, und verlangsamen Sie dann: --delay 4 und weniger Worker (-w 1). Instagram drosselt anonymen/nicht authentifizierten Datenverkehr am stärksten, daher ist eine authentifizierte Sitzung der größte Erfolgsfaktor.

Eine Reel gibt NO_DATA zurück → Der Beitrag ist möglicherweise privat, gelöscht oder regionsgesperrt, oder Instagram hat eine Anmeldewand angezeigt. Versuchen Sie es erneut mit einer angemeldeten Sitzung.

Das GUI-Fenster öffnet sich nicht oder die Schriftarten sehen falsch aus → Die GUI verwendet Pythons eingebautes tkinter. Unter Windows ist es am ausgereiftesten. Unter Linux/macOS installieren Sie das Tk-Paket, wenn das Fenster nicht startet (z. B. sudo apt install python3-tk).

ModuleNotFoundError beim Ausführen eines Skripts → Sie befinden sich wahrscheinlich außerhalb des Repos oder seiner virtuellen Umgebung. Wechseln Sie mit cd in den Projektordner und aktivieren Sie die venv (.venv\Scripts\activate unter Windows, source .venv/bin/activate unter macOS/Linux), bevor Sie python scraper.py ausführen.

Wie scrape ich viele Reels auf einmal? → Fügen Sie eine URL pro Zeile in eine Textdatei ein und führen Sie python scraper.py -f urls.txt -o out.csv aus.

Kann ein KI-Agent dies verwenden? → Ja — führen Sie python mcp_server.py aus und richten Sie einen beliebigen MCP-Client (Claude Desktop, Cursor usw.) auf die enthaltene .mcp.json. Siehe MCP-Server.

🤝 Mitwirken

1. Forken Sie das Repo und erstellen Sie einen Feature-Branch.

2. pip install -r requirements-dev.txt

3. Fügen Sie Tests in tests/ hinzu/passen Sie sie an; führen Sie pytest und python run_qa.py --quick aus.

4. Eröffnen Sie einen Pull-Request, der die Änderung und das QA-Ergebnis beschreibt.

📄 Lizenz

Veröffentlicht unter der MIT-Lizenz — siehe LICENSE.

🏷️ Name

Der endgültige öffentliche Name des Projekts ist Reelminner („Reel-Miner"). Frühere interne Codenamen wurden ausgemustert. Wenn Sie es forken, können Sie es beliebig umbenennen — aktualisieren Sie einfach den Titel in gui.py und diese README.