ytcollector 1.4.1
YouTube 콘텐츠 수집기 - 얼굴, 번호판, 타투, 텍스트 감지
License: MIT
Requires Python: >=3.8
Keywords: youtube, downloader, video-analysis, face-detection, ocr

# YouTube 콘텐츠 수집기

유튜브에서 특정 카테고리(얼굴, 번호판, 타투, 텍스트)의 영상을 자동으로 검색, 다운로드, 분석하여 수집하는 CLI 도구입니다.

## 설치

### PyPI에서 설치

```bash
pip install ytcollector
```

### 수동 설치 (개발용)

```bash
pip install yt-dlp[default]
```

> **참고**: `yt-dlp[default]`는 `mutagen`, `pycryptodomex`, `yt-dlp-ejs` 등 필수 extras를 포함합니다.

### 분석 기능 (권장)

```bash
pip install ytcollector[analysis]
```

또는 개별 설치:
```bash
pip install opencv-python easyocr numpy ultralytics
```

### JavaScript 런타임 (필수)

YouTube의 n-challenge 해결을 위해 **Node.js 20+** 가 필요합니다.
```bash
# macOS
brew install node

# Ubuntu/Debian
sudo apt install nodejs
```

## 사용법

### 기본 실행

```bash
ytcollector
```

기본값: 얼굴 카테고리 5개, 최대 90분 영상 수집 후 3분 트리밍

### 옵션

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `-c`, `--categories` | 수집할 카테고리 | `face` |
| `-n`, `--count` | 카테고리당 다운로드 수 | `5` |
| `-d`, `--duration` | 최대 영상 검색 길이(분) | `90` |
| `-o`, `--output` | 저장 경로 | `.` (현재 폴더) |
| `--fast` | 고속 모드 (병렬 다운로드) | 비활성화 |
| `-w`, `--workers` | 병렬 다운로드 수 | `3` |
| `--proxy` | 프록시 주소 | 없음 |
| `--cookies-from-browser` | 브라우저 쿠키 사용 (rate limit 우회) | 없음 |

### 카테고리 종류

| 카테고리 | 설명 | 검색 소스 |
|----------|------|-----------|
| `face` | 얼굴/인물 | SBS/MBC/tvN/JTBC 인터뷰, 기자회견 등 |
| `license_plate` | 자동차 번호판 | SBS 드라마 자동차/추격/주차장 씬 등 |
| `tattoo` | 타투/문신 | 타투 시술, 타투이스트 작업 영상 |
| `text` | 텍스트/자막 | SBS/tvN/JTBC/MBC 예능, 유튜버 자막 편집 등 |

## 예시

### 단일 카테고리

```bash
# 얼굴 영상 10개 수집
ytcollector -c face -n 10

# 번호판 영상 수집 (최대 90분 검색)
ytcollector -c license_plate -d 90

# 타투 영상 수집
ytcollector -c tattoo -n 5
```

### 여러 카테고리

```bash
# 얼굴과 텍스트 각 10개씩
ytcollector -c face text -n 10

# 모든 카테고리 수집
ytcollector -c face license_plate tattoo text -n 5
```

### 고속 모드

```bash
# 병렬 다운로드 (기본 3개 동시)
ytcollector -c face -n 10 --fast

# 5개 동시 다운로드
ytcollector -c face -n 10 --fast -w 5
```

### 저장 경로 지정

```bash
ytcollector -c face -o /path/to/save
```

### 프록시 사용

```bash
ytcollector -c face --proxy http://proxy.server:8080
```

### 쿠키 인증 (rate limit 우회)

```bash
# Chrome 브라우저 쿠키 사용
ytcollector -c face -n 100 --cookies-from-browser chrome

# Firefox 쿠키 사용
ytcollector -c license_plate --fast --cookies-from-browser firefox

# Safari 쿠키 사용 (macOS)
ytcollector -c tattoo --cookies-from-browser safari
```

지원 브라우저: `chrome`, `firefox`, `safari`, `edge`, `opera`, `brave`

## SBS Dataset 구축 (URL 리스트 기반)

URL 리스트를 기반으로 영상을 수집하고 특정 시점을 기준으로 자동으로 클리핑(3분 미만)하는 기능입니다. (v1.1.6에서 ROI 엔진 최적화 적용)

### 실행 방법

```bash
ytc-dataset youtube_url.txt
```

### youtube_url.txt 형식

`URL, MM:SS, TaskName` 형식으로 작성합니다.
```text
https://www.youtube.com/watch?v=aqz-KE-bpKQ, 00:10, sample_task
```

### 상세 옵션

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `file` | URL 리스트 파일 경로 | (필수) |
| `-o`, `--output` | 저장 루트 경로 | `.` |

### 특징
- **자동 트리밍**: 지정된 MM:SS 시점 기준 $\pm$ 1.5분(총 3분)을 자동으로 자릅니다.
- **멀티 클립 추출 (v1.2.5)**: 영상이 10분 초과인 경우, 한 영상에서 타겟이 여러 번 발견되면 겹치지 않는 3분 단위 클립들을 최대 3개까지 추출합니다. (10분 이하 영상은 1개만 추출)
- **중복 방지**: 인덱스 기반으로 이미 다운로드/클리핑된 영상은 건너뜁니다.
- **저장 구조**: `./video/` (원본), `./video_clips/` (클립) 폴더가 생성됩니다.

## 출력 폴더 구조

```
저장경로/
├── 얼굴/
│   ├── HR/            # 1080p 고해상도
│   │   └── face_0001.mp4
│   └── LR/            # 360p 저해상도
│       └── face_0001.mp4
├── 번호판/
│   ├── HR/
│   └── LR/
├── 번호판_미감지/     # 번호판 미감지 (수동 확인용)
├── 타투/
│   ├── HR/
│   └── LR/
├── 텍스트/
│   ├── HR/
│   └── LR/
├── .archive.txt       # 다운로드 기록
└── youtube_url_*.txt  # 카테고리별 성공 로그
```

## 파일 구조

```
ytcollector/
├── __init__.py        # 패키지 초기화
├── cli.py             # CLI 진입점
├── config.py          # 설정 (검색어, UA, 모델 경로 등)
├── analyzer.py        # 영상 분석 (YOLO, EasyOCR)
├── downloader.py      # 다운로드 및 수집 로직
├── utils.py           # 유틸리티 함수
├── dataset_builder.py # URL 리스트 기반 데이터셋 구축
└── models/
    ├── yolov12n-face.pt              # 얼굴 감지 모델
    ├── license_plate_detector.pt     # 번호판 감지 모델
    └── yolov8s_tattoo_manual_v3.pt   # 타투 감지 모델
```

## 분석 기능

| 감지 항목 | 사용 기술 | 설명 |
|-----------|-----------|------|
| 얼굴 | **YOLOv12 전용 모델** | v1.4.0: `yolov12n-face.pt` 모델로 정밀 감지 |
| 텍스트 | EasyOCR | 한국어/영어 문자 인식 |
| 번호판 | YOLOv8 전용 모델 + OCR | 번호판 전용 학습 모델 + 한국 번호판 패턴 매칭 |
| 타투 | YOLOv8 전용 모델 | 타투 전용 학습 모델 (`yolov8s_tattoo_manual_v3`) |

### 주요 최적화 (v1.1.5~1.2.5)
- **멀티 클립 추출** (v1.2.5): 10분 초과 영상 내 다수 지점 감지 시 겹치지 않는 3분 클립 최대 3개 저장 (파일명: `_1`, `_2`, `_3` 접미사)
- **최대 길이 확장** (v1.2.5): 수집 가능한 영상 길이를 기본 3분 → 90분으로 확장하여 더 많은 소스 확보
- **자막 영역 필터링** (v1.2.0): 화면 하단 60%~95% 영역만 자막으로 인식, 상단 로고/워터마크 제외
- **번호판 전용 모델** (v1.1.9): YOLO-World → 번호판 전용 학습 모델로 교체 (감지율 향상, 모델 크기 27MB→6MB)
- **오탐지 방지**: YOLO 감지 + OCR 패턴 매칭 둘 다 만족해야 번호판 판정, ROI 크기 필터링 추가
- **ROI 기반 감지**: 전체 화면이 아닌 YOLO가 지정한 영역만 OCR하여 속도와 정확도 향상
- **GPU 가속 지원**: CUDA 사용 가능 시 YOLO 및 OCR 자동 가속
- **로그 기반 중복 방지**: `youtube_url_*.txt` 기록을 참조하여 중복 분석 방지

### v1.4.0 업데이트
- **YOLOv12 얼굴 감지**: Haar Cascade → `yolov12n-face.pt` 전용 모델로 교체, 감지 정확도 대폭 향상
- **Node.js 런타임 자동 감지**: YouTube n-challenge 해결을 위한 `js_runtimes` 자동 설정
- **할당량 채우기 루프**: 목표 수량을 채울 때까지 자동 재검색 (최대 3라운드)
- **라이브 스트림 필터링**: 라이브/예정 방송 자동 건너뛰기
- **HR/LR 이중 저장**: 1080p + 360p 동시 저장 (1080p 없으면 LR만)
- **파일 경로 안정성**: 다운로드 후 실제 파일 검색 fallback 로직 추가

### v1.3.3 업데이트
- **타투 전용 YOLO 모델**: `yolov8s_tattoo_manual_v3` 모델로 정확도 향상
- **`--cookies-from-browser` 옵션**: 브라우저 쿠키로 rate limit 우회

## 주의사항

- 영상은 다운로드 후 분석하여 해당 카테고리가 감지된 경우에만 저장됩니다
- 번호판 카테고리는 미감지 영상도 별도 폴더에 보관됩니다 (수동 확인용)
- 이미 다운로드한 영상은 자동으로 스킵됩니다 (`.archive.txt` 기록)
- 비공개/삭제/저작권 영상은 자동 스킵됩니다

## 고속 모드 vs 일반 모드

| 항목 | 일반 모드 | 고속 모드 |
|------|-----------|-----------|
| 다운로드 | 순차 | 병렬 |
| 딜레이 | 0.5~1.5초 | 없음 |
| 재시도 | 3회 | 1회 |
| 타임아웃 | 30초 | 10초 |

고속 모드는 빠르지만 YouTube 차단 위험이 높아질 수 있습니다.