reelminner

💡 Примечание о названии: Окончательное публичное название этого проекта — Reelminner. Класс Python-движка называется Reelminner (см. scraper.py), CLI/GUI и MCP-сервер имеют бренд reelminner, а репозиторий GitHub — reelminner. Более раннее рабочее кодовое имя ReelSnipe полностью выведено из употребления. Другие варианты названий перечислены в Варианты названий.

📚 Содержание

• Что такое Reelminner

• ✨ Возможности

• 🧠 Как это работает

• 🏗️ Архитектура проекта

• 📦 Установка

• 🚀 Быстрый старт

• 💻 Использование

  • Настольный GUI

  • Командная строка (CLI)

  • MCP-сервер (для AI-агентов)

  • Python API

• 📊 Формат вывода

• ⚙️ Конфигурация

• 🗂️ Структура проекта

• 🧪 Тестирование и QA

• 📦 Сборка автономного EXE

• ⚠️ Правовое и этическое заявление

• 🤝 Вклад в проект

• 📄 Лицензия

• 🆘 Устранение неполадок и FAQ

• 🏷️ Название

Related MCP server: Instagram Complete MCP Server

Что такое Reelminner

Reelminner — это набор инструментов с открытым исходным кодом, который извлекает структурированные данные из Instagram Reels и профилей, которые их опубликовали. Он построен на едином, многократно используемом движке (Reelminner), который доступен четырьмя различными способами:

Все используют одну и ту же логику парсинга, сессий и ограничения скорости, поэтому результаты идентичны независимо от того, какой интерфейс вы используете.

✨ Возможности

• Многоуровневый парсинг Reel — Reelminner читает данные из нескольких слоёв (встроенный JSON, ответы GraphQL и резервный вариант на основе живого DOM), поэтому он продолжает работать, даже когда Instagram изменяет один из них.

• Обогащение профиля владельца — для каждого Reel он может автоматически получать username, full_name, bio, followers, is_verified и reels_count автора.

• Извлечение количества подписчиков — получается через GraphQL-запрос UserByRestrictedView / GraphQLOwnerInfo от Instagram, с резервным вариантом на основе DOM и пагинацией (обрабатывает ограниченные значения подписчиков, такие как «1.2M», прокручивая профиль).

• Метаданные музыки — аудио Reel: music_title, music_artist и music_id.

• Показатели вовлечённости — views, likes, comments, а также прямой video_url / thumbnail.

• Управление сессией и входом — интерактивный QR/вход, импорт cookie из экспорта EditThisCookie и 24-часовое обновление сессии, чтобы вам не приходилось постоянно входить заново.

• Параллельное извлечение — пул потоков (--workers, по умолчанию 3) с вежливыми задержками между запросами (--delay, по умолчанию 2 с) и адаптивной паузой при получении от Instagram BLOCKED / RATE_LIMITED.

• Устойчивое отслеживание статуса — каждая строка содержит код status (OK, PARSED_PARTIAL, FAILED, NO_DATA, BLOCKED, RATE_LIMITED), чтобы вы точно знали, что удалось.

• Несколько форматов экспорта — CSV (по умолчанию), JSON и Excel (.xlsx через openpyxl).

• MCP-сервер — пять стабильных инструментов, чтобы AI-агент (Claude, Cursor и т. д.) мог извлекать, проверять статус, импортировать cookie, останавливать и экспортировать.

• Настольный GUI — встроенная тёмная тема, поле для вставки URL, таблица результатов в реальном времени, правый клик копировать URL / открыть Reel и экспорт в один клик.

• Протестировано — набор pytest + сквозной QA-конвейер, который обеспечивает соблюдение порогов качества данных.

🧠 Как это работает

┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
│   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 (normalize_reel_url), чтобы работали и /reel/X/, и /reel/s/…/.

2. Загрузка сессии — применение сохранённых cookie (sessionid, csrftoken, ds_user_id, ig_did, mid, rur) или вход в систему.

3. Получение и парсинг страницы Reel с многоуровневым резервным вариантом:

   • parse_reel_page → встроенный window.__additionalData / sharedData HTML JSON

   • parse_reel_json → сырой GraphQL GQL ответ

   • parse_graphql_reel → объект shortcodeMedia

   • Резервный вариант на основе DOM → _extract_text_raw запрашивает живую страницу для лайков / комментариев / просмотров / подписчиков через адаптеры регулярных выражений.

4. Обогащение владельца (если не указано --no-profiles): получение профиля и чтение followers, full_name, bio, is_verified, reels_count.

5. Соблюдение ограничений: пауза delay между запросами; при блокировке — пауза и повтор.

6. Запись строк в CSV / JSON / Excel со статусом status для каждой строки.

🏗️ Архитектура проекта

Reelminner — это дизайн «один движок, несколько интерфейсов». Один основной движок (Reelminner) выполняет всю реальную работу; GUI, CLI, MCP-сервер и Python API — это тонкие интерфейсы, которые вызывают его. Это обеспечивает идентичность парсинга, обработки сессий и ограничения скорости во всех точках входа.

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

Обязанности модулей

Внутренности движка (Reelminner)

• Слой сессии — _SESSION_COOKIE_NAMES (sessionid, csrftoken, ds_user_id, ig_did, mid, rur); _apply_cookies(), _refresh_if_needed() (24 ч), login() (интерактивный QR), clear_session().

• Параллелизм — scrape() запускает ThreadPoolExecutor(max_workers=workers); каждый URL обрабатывается через _worker → _scrape_url, который вызывает _gather_metadata (данные Reel) и, при необходимости, _gather_article (профиль владельца). Семафор + _sleep() обеспечивают вежливость; status_code / retcode управляют адаптивным циклом повтора/паузы, когда Instagram возвращает BLOCKED / RATE_LIMITED.

• Конвейер парсинга (многоуровневый резервный вариант) — внутри _gather_metadata движок пробует по порядку: parse_reel_page (встроенный HTML JSON) → parse_reel_json (сырой GraphQL GQL) → parse_graphql_reel (shortcodeMedia) → резервный вариант на основе DOM через адаптеры _extract_text_html / _extract_text_raw и список регулярных выражений _PATTERNS (лайки/комментарии/просмотры/подписчики).

• Обогащение профиля — get_follower_count() использует GraphQL-запрос Instagram UserByRestrictedView / GraphQLOwnerInfo, переходя к DOM и пагинации подписчиков (_fetch_followers с end_cursor), когда значения ограничены.

• Вывод — строки собираются как словари ReelData и записываются через write_csv (с учётом csv_columns), export_json или export_excel (требуется openpyxl).

Почему такая структура

• Тестируемость — весь парсинг находится в parsers.py без зависимости от браузера, поэтому tests/test_parsers.py может проверять сохранённые HTML/JSON фикстуры.

• Единый источник истины — каждый интерфейс использует один и тот же Reelminner, поэтому исправление в движке одновременно улучшает GUI, CLI и MCP-сервер.

• Безопасная упаковка — тонкие оболочки GUI/CLI означают, что EXE PyInstaller включает только движок + минимальный интерфейс, что сохраняет небольшой размер бинарного файла.

📦 Установка

Требования: Python 3.10+ и браузерный движок 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

Только GUI: настольное приложение использует tkinter, который поставляется со стандартными установками Python. Дополнительный пакет не требуется. GUI наиболее отполирован на Windows.

Дополнительные инструменты для разработки/тестирования:

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

💡 Перед началом: Reelminner лучше всего работает с вошедшей в систему сессией Instagram — некоторые Reels и все данные о владельцах/подписчиках требуют аутентификации. Запустите python scraper.py --login один раз (интерактивный QR) или импортируйте cookie, экспортированные из расширения браузера EditThisCookie, с помощью python scraper.py --import-cookies cookies.json. Он читает только публичный контент, который вам уже разрешено просматривать.

🚀 Быстрый старт

# 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

💻 Использование

1. Настольный GUI

python gui.py

• Нажмите Login (необязательно, но рекомендуется — повышает успешность).

• Вставьте по одному URL рилса в строку в поле (или Ctrl+A, чтобы выбрать все).

• Перетащите ползунок Workers, затем нажмите Scrape.

• Наблюдайте за результатами в таблице.

• Правый клик по строке, чтобы скопировать URL или открыть Reel.

• Экспортируйте в CSV / Excel / JSON или Откройте папку с результатами.

Последние результаты автоматически сохраняются в results/_last_results.json.

2. Командная строка (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-сервер (для ИИ-агентов)

Reelminner включает MCP (Model Context Protocol) сервер, чтобы ИИ-клиент мог управлять им.

python mcp_server.py            # stdio transport

Настройте ваш MCP-клиент (.mcp.json включён в репозиторий):

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

Доступные инструменты (5, стабильные):

Переопределения окружения: 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"])

Ключевые члены Reelminner:

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

• login() — интерактивный вход

• 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) — публичный помощник

• csv_columns — упорядоченный список выходных полей

• DEFAULT_STATE_FILE — по умолчанию storage_state.json

📊 Формат вывода

Каждый рилс становится одной строкой. Полная схема CSV (scraper.csv_columns):

⚙️ Конфигурация

Куки / сессия

• Войдите с помощью python scraper.py --login (сохраняет storage_state.json).

• Или экспортируйте куки из браузера через расширение EditThisCookie и выполните python scraper.py --import-cookies cookies.json.

Переменные окружения (используются MCP-сервером и значениями по умолчанию CLI)

Предоставляется шаблон: скопируйте mcp.env.example → mcp.env, чтобы переопределить значения MCP по умолчанию.

🗂️ Структура проекта

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)

🧪 Тестирование и QA

# 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

Тестовый стенд QA обеспечивает соблюдение порогов, таких как доля успешно обработанных, доля проверенных, доля непустых, доля заблокированных и максимальное время выполнения, и записывает results/qa/qa_report.json + qa_results.csv.

📦 Сборка автономного EXE

В Windows создайте переносимый .exe (конечным пользователям не нужен Python):

pip install pyinstaller
python build_exe.py

Результат: dist/Reelminner.exe (однофайловая сборка через Reelminner.spec).

⚠️ Правовое и этическое предупреждение

Reelminner предоставляется только для образовательных и авторизованных/личных целей.

• Скрапинг Instagram может нарушать его Условия предоставления услуг. Используйте его только на контенте, которым вы владеете или к которому вам разрешён доступ.

• Соблюдайте ограничения скорости (--delay, меньше --workers) и не используйте его для спама, преследования или коммерческого массового извлечения данных.

• Вы несёте ответственность за то, как вы используете этот инструмент, и за соблюдение применимых законов (включая GDPR / правила конфиденциальности) в вашей юрисдикции.

• Авторы не связаны с Instagram/Meta и не несут ответственности.

🆘 Устранение неполадок и FAQ

playwright сообщает, что браузер не установлен / страницы не открываются → Убедитесь, что вы выполнили и pip install -r requirements.txt, и playwright install chromium. Без загрузки Chromium ничего не запустится.

Большинство полей пусты, или я получаю BLOCKED / RATE_LIMITED → Войдите (python scraper.py --login) или импортируйте куки, затем снизьте темп: --delay 4 и меньше рабочих процессов (-w 1). Instagram сильнее всего ограничивает анонимный/неаутентифицированный трафик, поэтому аутентифицированная сессия — самый важный фактор успеха.

Рилс возвращает NO_DATA → Пост может быть приватным, удалённым или ограниченным по региону, или Instagram показал стену входа. Попробуйте снова с выполненным входом.

Окно GUI не открывается или шрифты выглядят неправильно → GUI использует встроенный tkinter Python. В Windows он наиболее отполирован. В Linux/macOS установите пакет Tk, если окно не запускается (например, sudo apt install python3-tk).

ModuleNotFoundError при запуске скрипта → Вероятно, вы находитесь вне репозитория или его виртуального окружения. Перейдите в папку проекта и активируйте venv (.venv\Scripts\activate в Windows, source .venv/bin/activate в macOS/Linux) перед запуском python scraper.py.

Как скрапить много рилсов сразу? → Поместите по одному URL в строку в текстовый файл и выполните python scraper.py -f urls.txt -o out.csv.

Может ли ИИ-агент использовать это? → Да — запустите python mcp_server.py и укажите любому MCP-клиенту (Claude Desktop, Cursor и т.д.) на включённый .mcp.json. См. MCP-сервер.

🤝 Вклад в проект

1. Сделайте форк репозитория и создайте ветку для новой функции.

2. pip install -r requirements-dev.txt

3. Добавьте/скорректируйте тесты в tests/; запустите pytest и python run_qa.py --quick.

4. Откройте pull request с описанием изменения и результатом QA.

📄 Лицензия

Выпущено под лицензией MIT — см. LICENSE.

🏷️ Название

Финальное публичное название проекта — Reelminner («Reel miner»). Более ранние внутренние кодовые имена были отозваны. Если вы форкнете его, вы можете переименовать его как угодно — просто обновите заголовок в gui.py и этом README.