Table of Contents

Known Issues & Lessons Learned

포맷
공통 이슈

[2026-03-08] PowerShell curl — Invoke-WebRequest 충돌
[2026-03-08] PowerShell npm — 실행 정책 오류

프로젝트별 이슈

[2026-03-24] 히스토그램 비교 — Tab 프레임 구분 불가
[2026-03-24] split 감지 — 밝은 배경 오분류
[2026-03-24] overlay 크롭 크기 불일치
[2026-03-25] pHash 16×16 — Tab 프레임 과도합병
[2026-03-25] 1080p 프레임 — 메모리 부족/프로세스 행
[2026-03-25] yt-dlp 다운로드 — 360p 폴백

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Known Issues & Lessons Learned

이 파일은 SSOT(Single Source of Truth)입니다. 디버깅이나 구현 전에 반드시 이 파일을 확인하세요. 세션 종료 시 새로 발견된 이슈를 이 파일에 추가합니다.

포맷

각 항목은 아래 형식을 따릅니다:

### [날짜] [키워드] — 한줄 요약
- **증상**: 무엇이 잘못되었는가
- **원인**: 근본 원인
- **해결**: 올바른 해결 방법
- **주의**: 재발 방지를 위한 교훈

공통 이슈

[2026-03-08] PowerShell curl — Invoke-WebRequest 충돌

증상: curl 명령이 예상과 다른 응답 형식을 반환
원인: PowerShell에서 curl은 Invoke-WebRequest의 별칭
해결: **curl.exe**를 명시적으로 사용
주의: HTTP 관련 모든 명령에서 curl.exe 사용 필수

[2026-03-08] PowerShell npm — 실행 정책 오류

증상: npm run 명령이 실행 정책 관련 오류로 실패
원인: PowerShell 스크립트 실행 정책이 제한적으로 설정됨
해결: cmd /c npm run dev 형식으로 cmd를 통해 실행
주의: npm 관련 명령은 항상 cmd /c 접두어 사용 권장

프로젝트별 이슈

[2026-03-24] 히스토그램 비교 — Tab 프레임 구분 불가

증상: 서로 다른 Tab 페이지가 "동일"로 판정되어 프레임 수가 과소 추출
원인: 히스토그램 상관관계는 밝기 분포만 비교 — Tab 용지 배경이 같으면 다른 내용도 동일로 판정
해결: MSE 픽셀 비교로 전환 (320px 리사이즈, factor 8)
주의: MSE scaling factor는 영상 타입에 따라 다르게 동작할 수 있음

[2026-03-24] split 감지 — 밝은 배경 오분류

증상: 밝은 배경 기타 연주 영상(空奏列車)이 split으로 오분류
원인: 흰 셔츠/밝은 배경이 상단 밝기 조건 통과, 기타줄이 _has_tab_lines 통과
해결: split 검증 강화 (top>180, bottom<100, diff>80, 4+ lines) + overlay 우선 검사
주의: 패턴 감지 순서는 반드시 overlay → split → scroll 유지

[2026-03-24] overlay 크롭 크기 불일치

증상: overlay 프레임 비교 시 모든 프레임이 "다르다"로 판정 (1000+개 추출)
원인: _detect_tab_overlay가 프레임마다 다른 크기의 바운딩박스 반환 (69~360px)
해결: 320×120 흰색 캔버스에 정규화 후 비교 + 슬라이딩 윈도우(5프레임)
주의: overlay 프레임 수 최적화는 아직 진행 중 (추가 튜닝 필요)

[2026-03-25] pHash 16×16 — Tab 프레임 과도합병

증상: 서로 다른 Tab 페이지가 pHash 클러스터링에서 동일 그룹으로 합병 (20→9 프레임)
원인: 16×16 dHash(256비트)는 Tab 구조(6선 + 숫자)를 구분하기엔 해상도 부족. 모든 Tab이 유사한 hash 생성
해결: dHash 32×32(1024비트)로 확대 + max_hamming 50→20 조정
주의: hash_size와 max_hamming은 항상 쌍으로 조정해야 함 (비트수 대비 비율)

[2026-03-25] 1080p 프레임 — 메모리 부족/프로세스 행

증상: 1920×1080 프레임 500+개 로딩 시 프로세스 무한 대기 (3.5GB+ RAM)
원인: extract_frames가 모든 프레임을 list에 보관, 1080p는 프레임당 ~6MB
해결: MAX_FRAME_WIDTH=1280 캡 + gc.collect() 추가. 4K→1280px 다운스케일
주의: 영상 3개 순차 처리 시 GC 없으면 누적 메모리로 swap thrashing 발생

[2026-03-25] yt-dlp 다운로드 — 360p 폴백

증상: bestvideo[height>=720] 포맷으로 요청했으나 640×360 파일 다운로드
원인: format string의 /best 폴백이 720p 없을 때 360p 선택. 또는 mp4 전용 필터가 해상도 제한
해결: 명시적 1080p 우선 + 720p 폴백 체인 분리 (bestvideo[height>=1080]/.../best[height>=720]/best)
주의: 캐시된 파일이 있으면 재다운로드 안 함 — 해상도 변경 시 기존 파일 삭제 필요