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 Reel과 해당 게시자의 프로필에서 구조화된 데이터를 추출하는 오픈소스 툴킷입니다. 단일 재사용 엔진(Reelminner)을 기반으로 하며, 네 가지 방식으로 제공됩니다:

모든 인터페이스는 동일한 파싱, 세션, 속도 제한 로직을 공유하므로, 어떤 프런트엔드를 사용하든 결과는 동일합니다.

✨ 기능

• 다중 소스 릴 파싱 — Reelminner는 여러 계층(내장 JSON, GraphQL 응답, 라이브 DOM 폴백)에서 데이터를 읽으므로 Instagram이 그중 하나를 변경해도 계속 작동합니다.

• 게시자 프로필 보강 — 각 릴에 대해 게시자의 username, full_name, bio, followers, is_verified, reels_count를 자동으로 가져올 수 있습니다.

• 팔로워 수 추출 — Instagram의 GraphQL UserByRestrictedView / GraphQLOwnerInfo 쿼리를 통해 가져오며, DOM 폴백과 페이지네이션을 지원합니다 (프로필 스크롤을 통해 "1.2M"과 같은 제한된 팔로워 수치 처리).

• 음악 메타데이터 — 릴 오디오의 music_title, music_artist, music_id.

• 참여 지표 — views, likes, comments, 그리고 직접적인 video_url / thumbnail.

• 세션 및 로그인 관리 — 대화형 QR/로그인, EditThisCookie 내보내기에서 쿠키 가져오기, 그리고 24시간 세션 갱신으로 반복 로그인 없이 사용 가능.

• 동시 스크래핑 — 스레드 풀(--workers, 기본 3)과 요청 간 적절한 지연 (--delay, 기본 2초), Instagram이 BLOCKED / RATE_LIMITED를 반환할 때 적응형 백오프를 지원합니다.

• 탄력적인 상태 추적 — 모든 행에는 status 코드(OK, PARSED_PARTIAL, FAILED, NO_DATA, BLOCKED, RATE_LIMITED)가 포함되어 정확히 무엇이 성공했는지 알 수 있습니다.

• 다중 내보내기 형식 — CSV(기본), JSON, Excel(openpyxl을 통한 .xlsx).

• MCP 서버 — AI 에이전트(Claude, Cursor 등)가 스크래핑, 상태 확인, 쿠키 가져오기, 중지, 내보내기를 할 수 있는 5가지 안정적인 도구.

• 데스크톱 GUI — 내장 다크 테마, URL 붙여넣기 상자, 실시간 결과 테이블, 우클릭 URL 복사 / 릴 열기, 원클릭 내보내기.

• 테스트 완료 — 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. 세션 로드 — 저장된 쿠키(sessionid, csrftoken, ds_user_id, ig_did, mid, rur) 적용 또는 로그인.

3. 릴 페이지 가져오기 및 파싱 — 계층적 폴백 방식:

   • 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. 행 작성 — 각 행에 status를 포함하여 CSV / JSON / Excel로 작성.

🏗️ 프로젝트 아키텍처

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 (릴 데이터)와 선택적으로 _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) → _extract_text_html / _extract_text_raw 어댑터와 _PATTERNS 정규식 목록(좋아요/댓글/재생 수/팔로워 수)을 통한 DOM 폴백.

• 프로필 보강 — get_follower_count()는 Instagram의 GraphQL UserByRestrictedView / GraphQLOwnerInfo 쿼리를 사용하며, DOM으로 폴백하고 수치가 제한될 때 팔로워를 페이지네이션합니다(end_cursor가 있는 _fetch_followers).

• 출력 — 행은 ReelData 딕셔너리로 수집되며 write_csv(csv_columns 준수), export_json, 또는 export_excel(openpyxl 필요)로 작성됩니다.

이 구조의 이유

• 테스트 용이성 — 모든 파싱은 브라우저 의존성 없이 parsers.py에 있으므로 tests/test_parsers.py가 저장된 HTML/JSON 픽스처에 대해 검증할 수 있습니다.

• 단일 진실 소스 — 모든 인터페이스가 동일한 Reelminner를 공유하므로 엔진의 수정이 GUI, CLI, MCP 서버에 동시에 적용됩니다.

• 안전한 패키징 — GUI/CLI가 얇은 셸이므로 PyInstaller EXE는 엔진 + 최소 UI만 번들하여 바이너리를 작게 유지합니다.

📦 설치

요구 사항: 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 전용: 데스크톱 앱은 표준 Python 설치에 포함된 tkinter를 사용합니다. 추가 패키지가 필요 없습니다. GUI는 Windows에서 가장 완성도가 높습니다.

선택적 개발/테스트 도구:

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

💡 시작 전에: Reelminner는 로그인된 Instagram 세션에서 가장 잘 작동합니다 — 일부 릴과 모든 게시자/팔로워 데이터는 인증이 필요합니다. python scraper.py --login을 한 번 실행하거나(대화형 QR), 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

• 로그인을 클릭합니다(선택 사항이지만 권장 — 성공률이 높아집니다).

• 한 줄에 릴 URL 하나씩 상자에 붙여넣습니다(또는 Ctrl+A로 모두 선택).

• Workers 슬라이더를 끌어당긴 다음 Scrape를 클릭합니다.

• 결과가 테이블에 표시되는 것을 확인합니다.

• 행을 마우스 오른쪽 버튼으로 클릭하여 URL 복사 또는 릴 열기를 수행합니다.

• 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 서버(AI 에이전트용)

Reelminner는 AI 클라이언트가 구동할 수 있도록 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는 Python 내장 tkinter를 사용합니다. Windows에서 가장 완성도가 높습니다. Linux/macOS에서는 창이 실행되지 않으면 Tk 패키지를 설치하세요(예: sudo apt install python3-tk).

스크립트 실행 시 ModuleNotFoundError가 발생합니다 → 저장소 또는 가상 환경 밖에 있을 가능성이 높습니다. 프로젝트 폴더로 cd한 후 python scraper.py를 실행하기 전에 venv를 활성화하세요(Windows에서는 .venv\Scripts\activate, macOS/Linux에서는 source .venv/bin/activate).

한 번에 많은 릴을 스크레이프하려면 어떻게 하나요? → 텍스트 파일에 한 줄에 URL 하나씩 넣고 python scraper.py -f urls.txt -o out.csv를 실행하세요.

AI 에이전트가 이 도구를 사용할 수 있나요? → 네 — python mcp_server.py를 실행하고 포함된 .mcp.json을 MCP 클라이언트(Claude Desktop, Cursor 등)에 지정하세요. MCP 서버를 참조하세요.

🤝 기여하기

1. 저장소를 포크하고 기능 브랜치를 만듭니다.

2. pip install -r requirements-dev.txt

3. tests/에 테스트를 추가/조정하고 pytest 및 python run_qa.py --quick을 실행합니다.

4. 변경 사항과 QA 결과를 설명하는 풀 리퀘스트를 엽니다.

📄 라이선스

MIT 라이선스로 배포됩니다 — LICENSE를 참조하세요.

🏷️ 이름

프로젝트의 최종 공개 이름은 Reelminner("Reel miner")입니다. 이전 내부 코드명은 폐기되었습니다. 포크하면 원하는 대로 이름을 바꿀 수 있습니다 — gui.py와 이 README의 제목만 업데이트하면 됩니다.