guitar_score/.agent/references/known-issues.md

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)
• 주의: 캐시된 파일이 있으면 재다운로드 안 함 — 해상도 변경 시 기존 파일 삭제 필요

[2026-03-27] OpenCV SIFT 트래킹 — 마커 보호 실패

• 증상: 동일한 반주(코러스)가 반복될 때 SIFT 매칭 알고리즘이 화면을 과거로 건너뛰어 합병시킴(마디 삭제됨)
• 원인: Red 채널 추출 시 노란색 마커가 흰색 배경과 동화되어 사라짐. 특징점이 동일해져서 과거 코러스 패턴과 100% 일치한다고 오판
• 해결: 트래킹 엔진 전용 채널(Blue) 도입(노란색 마커를 거대한 검은 블럭으로 전환하여 강력한 특징점 제공) + 렌더링용 Red 채널 분리 독립
• 주의: SIFT나 matchTemplate를 사용할 때, 이동을 측정하려면 특징점(마커)의 시각적 명확성이 음악적 물리 구조보다 절대적으로 우선되어야 함

[2026-03-27] pHash — 반복 파트 원천 삭제

• 증상: 4:45분짜리 영상(128+ 마디)이 15조각(약 48마디)으로 압축됨
• 원인: 해시화(_dedup_by_hash)가 1280px 해상도를 8x8로 축소 비교하면서 1절과 2절이 동일한 프레임으로 오인되어 삭제당함
• 해결: 스크롤 방식에서는 오직 물리적 마디 구분선(|)을 기준으로 분절 후 재배치하는 타일 엔진 도입
• 주의: Scroll 파노라마 같은 선형 시계열 구조에서는 지엽적 Hash 기반 중복제거를 적용하면 안 됨

[2026-03-28] Crop 마진 — 마디 번호 소실 (Decapitation)

• 증상: 입력 영상 최상단에 존재하는 숫자(마디 번호)가 출력물에서 무차별적으로 잘려나감
• 원인: 밀도 필터(row_dark > 0.02)에서 숫자 픽셀이 차지하는 비율이 가로폭 대비 0.4%에 불과하여 여백으로 간주됨
• 해결: 필터링 임계점을 0.002로 대폭 완화 및 Top Clearance Margin을 120px로 확장
• 주의: 심볼 밀도가 극히 낮은 구역 통과 시 % 기반의 밀도 크롭 알고리즘은 치명적으로 작용함

[2026-03-28] 씬전환 오탐 — 스크롤 가속도 조건

• 증상: 스크롤 속도가 급격히 변하는 구간(예: 빠른 이동)에서 씬전환으로 오탐 → 세그먼트 9개로 과다 분리
• 원인: _merge_scroll_candidates의 abs(s_px - prev_s_px) > 100 조건이 스크롤 가속을 씬전환으로 오인
• 해결: 해당 조건 제거. confidence 기반 조건(conf <= 0.15, prev_conf - conf > 0.4)만 유지
• 주의: 스크롤 속도는 영상마다 다르므로 절댓값 기반 조건은 신뢰할 수 없음

[2026-03-28] 파노라마 병합 임계치 — 반복 구간 분리

• 증상: 코러스처럼 유사한 구간에서 merge_panoramas_list 매칭 스코어가 0.56~0.59에 머물러 파노라마가 3개로 분리됨
• 원인: max_val > 0.60 임계치가 반복성 악보의 픽셀 유사도를 커버하지 못함
• 해결: 임계치 0.60 → 0.50으로 완화
• 주의: 임계치를 낮추면 오매핑 위험이 있으므로 0.50 이하로는 내리지 말 것

[2026-03-28] OCR-First 방식 — 스크롤 영상 적용 불가

• 증상: 각 프레임에서 마디번호 OCR 시도 시 인식률 4.8% (126프레임 중 6개만 인식)
• 원인: 스크롤 영상에서 마디번호는 화면 왼쪽 고정이 아닌 악보와 함께 이동 → 프레임마다 위치 다름. 오인식 결과(7→10→71→101→710)도 다수
• 해결: OCR-First 방식 폐기. 파노라마 스티칭 후 물리적 마디구분선(|) 탐지 방식 유지
• 주의: 스크롤 영상에서 마디번호 기반 중복제거는 파노라마를 완성한 뒤 적용해야 의미가 있음

[2026-03-28] ORB 특징점 패턴 매칭 실패 — 마디 무단 복제

• 증상: Сontinuous Scroll 뷰에서 12마디와 29마디 같은 특정 구간이 통째로 복제되어 (12 뒤에 12, 29 뒤에 29) 삽입되는 현상.
• 원인: 영상 내 플레이헤드의 옅은 회색 잔상(200~220)이 씬 전환을 오탐, 이후 이중 병합 시도. ORB/SIFT 기반의 특징점 추출기는 반복 화성이 많은 기타 탭 악보 특성상 "11마디와 12마디"를 시각적으로 같은 곳이라 착각하여 다른 마디 위치로 강제 Overlap 시킴.
• 해결: cv2.threshold(THRESH_BINARY_INV)로 플레이헤드를 물리적 삭제하여 씬오탐 근절. Canny Edge 기반 1D Morphological matchTemplate 스티칭으로 롤백. 스크롤 탭에서 불필요한 Full-Page 덮어쓰기 로직 원천 차단.
• 주의: 단순 배경/글자 매칭이 아닌 반복적 패턴이 생명인 악보에서는 부분 특징점 매칭(ORB) 알고리즘이 픽셀의 시계열 순서(Monotonicity)를 완전히 망가뜨림. 1D Correlation 윈도우 스티칭이 음악의 선형 복원에는 더 정교함.

[2026-03-29] <20><><B8><E9>(Area) <20><><B1><E2> <20>ǽ<C6>Ʈ<BA><C6AE><B7><B9> ? <20><><C0><E7> Ŀ<><C4BF> <20><><B0><A3><BC><B7><C0><B8> <20><><C0><CE> <20><><B9><AB> <20><><C6><E4><C0><CC> <20><><BA><B9>

• <C1><F5><BB><F3>: <20><><C1><A4><C0><FB> <20><><BF><C0><B9><F6><B7><B9> <20><><BF>󿡼<BB> <20><><C0><E7> Ŀ<><C4BF><BC><AD> <20><><C1>ݸ<B1> <20><><BF><F2><C1><F7><BF><A9> <20><><B5><BF> <20><><C6><E4><C0><CC><C1><F6> <20><><B9>Ѵ<C7><D1B4><EB> <20><><BA><B9>(43<34><33> <20>̻<C0>)<29><>
• <BF><F8><C0><CE>: <20>ȼ<C7> <20><><C2><F7> <20><><C3><D1>(Area)<29><><C0><B8> <20><><C6><E4><C0><CC> <20>ѱ<B3><D1B1><E8> <20><><C6><C7>. <20>Ķ<C6><C4B6><F5> <20><><C7><FC> Ŀ<><C4BF><BC><AD> <20><>ǥ<BD><C7A5> <20><><B0><A1><B8><AE> <20>̵<C0><CCB5><BF> <20><> <20>߻<B9><DFBB>ϴ<C7> <20>ȼ<C7> <20><><BE><E7> <20><><BD><C7> <20><><C6><E4><C0><CC> <20>ѱ<B3> <20>ȼ<C7> <20>纸<BE><E7BAB8> <20><><BC><F6><C7><D0><C0><FB><C0><B8> Ŀ<><C4BF><C1><F6> <20><><BF><AA> <20><><C7><F6> <20>߻<B9>
• <C7>ذ<E1>: <20><><B3><F4> <20><>(col_sums)<29><> <20>̿<C0><CCBF><EB> '<27><> <20><><B0><B3> <20><><BC><BC><B7><CE>(Column)'<27><> ũ<><C5A9> <20><><BA>ߴ<C7><DFB4><C2><C1><F6> <20><><C6><C7><C1>ϴ<C7> 1D <20><><B0><A1><B7><CE> <20><><BA><F1> <20>м<BA> <20><><B5><B5>. Ŀ<><C4BF><BC><AD> <20><><C1><BC> <20><><B0><A1> <20><><BD><BA>(<5%)<29><> <20><>õ <20><><B9><AB>
• <C1><D6><C0><C7>: <20><><BC><F6><C7><D0> <20><><C0><FC><C1><A6> <20><><BF><C0><BF><B0> <20><><BB><F3>(Ŀ<><C4BF> <20><><B8><E9> > <20><>ȭ <20><><B8><E9>)<29><><BF><A1><BC><AD> <20> Median<61>̳<C0> Tesseract <20><> <20><>ó<C4><C3B3> <20><><BF><A3><C1><F8> <20>ذ<C7>å<E1><C3A5> <20><> <20><> <20><><BE><F8>. <20><><BC><F6><BD><C4> <20><><BA><BB><C1><FA> <20><><C2><F7><BF><F8> <20><><BA><AF><B0>Ͽ<C7> Ǯ <20><>