gdown-helper/docs/MEDIA_CAPTURE_PLAN.md

Media Capture Implementation Plan (Commercial Grade)

Goal

• 웹페이지에서 노출되는 mp4, m3u8, hls 계열 URL을 안정적으로 수집하고,
• 사용자에게 캡처 목록을 제공한 뒤,
• 선택 URL을 gdown(native host -> addUri)로 전송한다.

Product Requirements

1. 탐지 신뢰성

• 단순 확장자 기반 + content-type 기반 병행
• webRequest 레벨에서 응답 헤더 관찰
• 중복 제거(동일 URL/동일 탭 다중 발생 억제)

2. UX

• 팝업에서 최근 캡처 목록 확인 가능
• 항목별 즉시 전송 버튼
• 전체 비우기
• 상태/실패 사유 표시

3. 운영/확장성

• 캡처 저장소 분리 (storage.local)
• 타입/모델 분리
• 향후 DASH(.mpd), DRM 힌트 감지 등 단계적 확장 가능

Step-by-Step

1. Step 1 (이번 구현)

• webRequest.onHeadersReceived 기반 캡처 엔진
• mp4/m3u8/m3u/hls mime 감지
• 팝업 목록 + Add/Clear
• 페이지 URL -> yt-dlp 전송(현재 탭 버튼, 우클릭 페이지 fallback)

2. Step 2

• content script 보조 탐지(video/source/player script)
• referer/cookie/user-agent 전달 강화

3. Step 3

• 사이트별 노이즈 필터링 룰
• 품질별 그룹핑/정렬
• 실패 자동 재시도 UX

4. Step 4

• 고급모드(세그먼트 playlist vs master playlist 구분)
• 진단 로그 뷰