# Architecture

> YouTube 기타 TAB 영상 → PDF 자동 추출 파이프라인

## 프로젝트 개요

YouTube 기타 TAB 튜토리얼 영상을 입력받아, 컴퓨터 비전으로 TAB 악보 영역만 추출하고 중복을 제거하여 깨끗한 PDF/PNG로 출력하는 CLI 도구.

## 디렉토리 구조

```
project-root/
├── youtube_tab_to_pdf.py  # 메인 파이프라인 (단일 파일)
├── .env                   # yt-dlp 쿠키 경로 설정
├── .gitignore
├── output/                # 생성된 PDF/PNG/디버그 프레임
├── .agent/                # AI 에이전트 설정
│   ├── AGENT.md
│   ├── references/        # 프로젝트 문서
│   └── workflows/         # 워크플로우 정의
└── docs/devlog/           # 개발 로그
```

## 핵심 모듈 (youtube_tab_to_pdf.py 내부)

| 모듈 | 역할 | 비고 |
|------|------|------|
| `download_video()` | yt-dlp로 영상 다운로드 | .env의 쿠키 경로 사용 |
| `extract_frames()` | 영상 → 프레임 분리 (fps=2) | OpenCV VideoCapture |
| `detect_pattern()` | 영상 패턴 분류 (overlay→split→scroll) | 우선순위: overlay > split > scroll |
| `_detect_tab_overlay()` | 흰 박스 + Tab 라인 검출 | HoughLinesP 기반 |
| `_detect_split_screen()` | 상단 Tab + 하단 핸드캠 분할 검출 | 밝기 기준 (top>180, bottom<100) |
| `_has_tab_lines()` | 수평 Staff 라인 존재 여부 | 모폴로지 + HoughLinesP |
| `compare_frames()` | MSE 기반 프레임 유사도 비교 | 320px 리사이즈, factor 8 |
| `extract_unique_*()` | 패턴별 고유 프레임 추출 | scroll/overlay/split 3종 |
| `generate_pdf()` | 프레임 → A4 PDF + 롱 이미지 생성 | ReportLab + Pillow |

## 데이터 흐름

```mermaid
graph LR
    A[YouTube URL] --> B[yt-dlp 다운로드]
    B --> C[프레임 추출<br>fps=2]
    C --> D{패턴 감지}
    D -->|overlay| E1[Tab 오버레이 크롭<br>+ 정규화 비교]
    D -->|split| E2[상단 42% 크롭<br>+ 밝기/라인 필터]
    D -->|scroll| E3[상단 크롭]
    E1 --> F[중복 제거<br>MSE 비교]
    E2 --> F
    E3 --> F
    F --> G[PDF + PNG 생성]
```

## 패턴 감지 우선순위

1. **overlay** — 화면 위에 떠 있는 Tab 박스 (가장 구체적)
2. **split** — 상단 Tab 용지 + 하단 핸드캠 (엄격한 밝기 기준)
3. **scroll** — 상단 크롭 (기본 폴백)