ytcollector 1.1.8

YouTube 콘텐츠 수집기 - 얼굴, 번호판, 타투, 텍스트 감지

YouTube 콘텐츠 수집기

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

설치

필수 패키지

pip install yt-dlp

분석 기능용 패키지 (권장 - v1.1.6+)

분석 기능을 원활하게 사용하려면 아래 패키지들이 필요합니다. GPU(CUDA)가 설치된 경우 자동으로 가속이 활성화됩니다.

pip install opencv-python easyocr numpy ultralytics
# YOLO-World 기능을 사용하려면 아래 CLIP 라이브러리 수동 설치가 필요합니다.
pip install "git+https://github.com/ultralytics/CLIP.git"

사용법

기본 실행

ytcollector

기본값: 얼굴 카테고리 5개, 최대 3분 영상

옵션

옵션	설명	기본값
-c, --categories	수집할 카테고리	face
-n, --count	카테고리당 다운로드 수	5
-d, --duration	최대 영상 길이(분)	3
-o, --output	저장 경로	. (현재 폴더)
--fast	고속 모드 (병렬 다운로드)	비활성화
-w, --workers	병렬 다운로드 수	3
--proxy	프록시 주소	없음

카테고리 종류

카테고리	설명	검색 소스
face	얼굴/인물	SBS 인터뷰, 런닝맨, 미운우리새끼 등
license_plate	자동차 번호판	중고차 매물, 세차 영상, 신차 출고 등
tattoo	타투/문신	타투 시술, 타투이스트 작업 영상
text	텍스트/자막	SBS 예능 (런닝맨, 골목식당 등)

예시

단일 카테고리

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

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

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

여러 카테고리

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

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

고속 모드

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

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

저장 경로 지정

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

프록시 사용

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

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

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

실행 방법

ytc-dataset youtube_url.txt

youtube_url.txt 형식

URL, MM:SS, TaskName 형식으로 작성합니다.

https://www.youtube.com/watch?v=aqz-KE-bpKQ, 00:10, sample_task

상세 옵션

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

특징

• 자동 트리밍: 지정된 MM:SS 시점 기준 $\pm$ 1.5분(총 3분)을 자동으로 자릅니다.
• 중복 방지: 인덱스 기반으로 이미 다운로드/클리핑된 영상은 건너뜁니다.
• 저장 구조: ./video/ (원본), ./video_clips/ (클립) 폴더가 생성됩니다.

출력 폴더 구조

저장경로/
├── 얼굴/              # 얼굴 감지된 영상
├── 번호판/            # 번호판 감지된 영상
├── 번호판_미감지/     # 번호판 미감지 (수동 확인용)
├── 타투/              # 타투 감지된 영상
├── 텍스트/            # 텍스트 감지된 영상
├── .archive.txt       # 기본 다운로드 기록
└── youtube_url_*.txt  # 카테고리별 성공 로그 (v1.1.5+ 중복 체크에 활용)

파일 구조

260202_test/
├── main.py        # CLI 진입점
├── config.py      # 설정 (검색어, UA 등)
├── analyzer.py    # 영상 분석 (OpenCV, EasyOCR)
├── downloader.py  # 다운로드 로직
└── README.md      # 사용설명서

분석 기능

감지 항목	사용 기술	설명
얼굴	OpenCV Haar Cascade	정면 얼굴 감지
텍스트	EasyOCR	한국어/영어 문자 인식 (분석 품질 및 프레임 수 개선)
번호판	YOLO-World + ROI OCR	v1.1.6: YOLO로 감지 후 해당 영역만 OCR (속도 2x, 정확도 향상)
타투	OpenCV HSV 분석	피부 영역 내 잉크 패턴 감지

주요 최적화 (v1.1.5~1.1.6)

• ROI 기반 감지: 전체 화면이 아닌 YOLO가 지정한 영역만 OCR하여 속도와 정확도 대폭 향상
• GPU 가속 지원: CUDA 사용 가능 시 YOLO 및 OCR 자동 가속
• 로그 기반 중복 방지: 로컬 파일이 없어도 youtube_url_*.txt 기록을 참조하여 중복 분석 방지

주의사항

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

고속 모드 vs 일반 모드

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

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