Metadata-Version: 2.4
Name: ytcollector
Version: 1.0.7
Summary: SBS 데이터셋 수집기
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: yt-dlp>=2024.1.0
Requires-Dist: ultralytics>=8.1.0
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: imageio-ffmpeg>=0.4.9

# Downloader: SBS 데이터셋 수집기

YouTube 영상에서 얼굴, 자동차 번호판, 타투, 텍스트 자막을 수집하고 YOLO-World로 검증하는 자동화 파이프라인입니다.

## 1. 설치 및 시작

**필수 요구사항:**
- Python 3.8 이상
- FFmpeg (pip 설치 시 `imageio-ffmpeg`를 통해 자동으로 구성되나, 실패 시 Mac: `brew install ffmpeg` 설치 권장)

**설치:**
```bash
cd 260203_sbs_dataset
pip install -e .
```

**프로젝트 초기화 (최초 1회):**
필요한 폴더(`urls/`, `video/`)를 생성합니다.
```bash
ytcollector init
```

---

## 2. URL 관리

다운로드할 YouTube 영상 리스트는 텍스트 파일로 관리합니다.
**파일 위치:** `urls/<태스크이름>/youtube_url.txt` (예: `urls/face/youtube_url.txt`)

**파일 형식 (CSV 스타일):**
```text
task_type,url,timestamp_min,timestamp_sec,description
face,https://www.youtube.com/watch?v=VIDEO_ID,2,30,설명
```
* `init` 명령 실행 시 샘플 내용이 포함된 파일이 자동 생성됩니다.

---

## 3. 사용법 (다운로드 & 검증)

이 프로그램은 **다운로드 → YOLO 검증 → (성공 시) 저장** 순서로 작동합니다. 타겟 객체가 없으면 자동으로 삭제됩니다.

### 주요 명령어 예시
안정적으로 하나씩 다운로드하거나, 여러 태스크를 동시에 처리하고 목표 수량을 설정할 수 있습니다.

```bash
# 기본 다운로드 (태스크 하나)
ytcollector download --task face

# 여러 태스크 동시에 실행 및 목표 수량(-n) 설정
ytcollector download --task face tattoo text -n 100

# 🚀 Fast 모드 (병렬 다운로드)
ytcollector download --task face --fast
```
* **방화벽 우회**: 랜덤 딜레이(1~3초)가 적용되어 차단을 방지합니다.
* **에러 무시**: 중간에 에러가 나도 멈추지 않고 다음 영상으로 넘어갑니다.

### 저장 파일 규칙
* **파일명**: `face_0001.mp4`, `face_0002.mp4` ... (순차 번호)
* **중복 방지**: `download_history.json`에 기록하여, 이미 받은 URL은 중복해서 받지 않습니다.

---

## 4. NAS / 네트워크 저장 설정

영상을 로컬이 아닌 NAS에 저장하려면 설정을 수정하세요.
OS(Windows/Mac)를 자동 감지하여 적절한 경로를 사용합니다.

**설정 파일 수정:** `ytcollector/config.py`
```python
# Windows 예시
NAS_PATH_WINDOWS = r"\\NAS_SERVER_IP\Data\Private Dataset\..."

# Mac 예시 (/Volumes로 마운트된 경로 확인 필요)
NAS_PATH_MAC = "/Volumes/Data/Private Dataset/..."
```

---

## 5. 전체 명령어 목록

| 명령어 | 설명 | 예시 |
|--------|------|------|
| `init` | 프로젝트 초기화 | `ytcollector init` |
| `download` | 대량 다운로드 (여러 태스크, 개수 제한 가능) | `ytcollector download --task face tattoo -n 50` |
| `download-single` | URL 1개만 테스트 다운로드 | `ytcollector download-single --task face -u ...` |
| `verify` | 수동 YOLO 검증 (기존 파일) | `ytcollector verify --task face` |
| `list-tasks` | 지원하는 태스크 목록 확인 | `ytcollector list-tasks` |

## 6. 문제 해결
* **검증 실패가 너무 많음**: `config.py`에서 `CONFIDENCE_THRESHOLD` (기본 0.25) 값을 낮춰보세요.
* **IP 차단**: Fast 모드 사용 중 YouTube 접근이 막히면 잠시 기다린 후 다시 시도하거나 딜레이 시간을 늘리세요.
