youtube-guitar-tab-parser: YouTube 기타 레슨을 PDF 타브 악보로 변환하기

youtube-guitar-tab-parser: YouTube 기타 레슨을 PDF 타브 악보로 변환하기

개요

youtube-guitar-tab-parser는 교육용 YouTube 영상을 통해 기타 타브 악보를 자동으로 추출하도록 설계된 명령줄 인터페이스(CLI) 도구입니다. 비디오 프로세싱 도구와 AI 비전 기능을 결합하여, 이 도구는 화면에서 악보가 포함된 영역을 식별하고, 중복된 프레임을 제거하며, 남은 고유한 라인들을 포맷팅된 PDF 문서로 병합합니다.

기술 아키텍처 및 워크플로우

이 도구는 스트리밍 비디오를 정적 문서로 변환하기 위해 다단계 파이프라인을 따릅니다. 비디오 획득을 위해 yt-dlp를, 프레임 추출을 위해 ffmpeg를, 공간 분석 및 콘텐츠 검증을 위해 Anthropic Claude 비전 모델을 사용합니다.

1. 비디오 획득 및 프레임 샘플링

프로세스는 yt-dlp를 사용하여 비디오를 다운로드하는 것으로 시작됩니다. 처리 시간과 API 비용을 최적화하기 위해, 도구는 다운로드 해상도를 제한합니다( --max-height 플래그를 통해 기본값 720p로 설정). 그 후 ffmpeg가 설정 가능한 간격(기본값 2초마다)으로 프레임을 추출합니다.

2. 타브 영역 탐지

화면에서 기타 타브 위치를 찾기 위해, 이 도구는 종종 부정확할 수 있는 AI에게 원본 픽셀 좌표를 요청하는 대신 그리드 기반 탐지 방법을 사용합니다. 프레임의 작은 샘플(기본값 6개)에 대해 라벨이 지정된 수평 밴드 그리드를 그립니다. Claude 비전은 어떤 밴드가 악보를 포함하고 있는지 식별하며, 도구는 수직 크롭 영역을 결정하기 위해 첫 번째와 마지막 음악 밴드의 중앙값을 계산합니다. 프레임의 전체 너비는 유지됩니다.

3. 중복 제거 및 필터링

재생 커서가 움직임에 따라 단일 음악 라인이 여러 프레임에 걸쳐 나타날 수 있기 때문에, 도구는 2단계 중복 제거 프로세스를 사용합니다:

  • Perceptual Hashing: dHash(차이 해시)를 사용하여 거의 동일한 연속적인 크롭 이미지를 제거합니다. 이는 AI로 전송되는 이미지 수를 최소화하여 비용을 제어하는 조치로 활용됩니다.
  • Bar-Number Analysis: Claude 비전은 각 라인의 시작 부분에 인쇄된 마디(bar) 번호를 읽습니다. 도구는 각 고유한 마디 번호의 첫 번째 등장만 유지하고, 타이틀 카드나 인트로와 같은 타브가 아닌 프레임을 제거합니다.

4. PDF 생성

pdf-lib를 사용하여, 도구는 비디오에 나타난 순서대로 고유한 타브 라인을 A4 페이지에 수직으로 쌓습니다. 최종 문서는 첫 페이지의 헤딩과 메타데이터에 비디오 제목을 포함합니다.

설치 및 사용법

요구 사항

  • Node.js: 버전 20 이상.
  • 시스템 종속성: yt-dlp와 ffmpeg가 설치되어 있어야 하며 시스템 PATH에서 사용 가능해야 합니다.
  • API 액세스: 유효한 Anthropic API 키.

빠른 시작

npm install
npm run build
cp .env.example .env # Add ANTHROPIC_API_KEY here
node --env-file=.env dist/cli.js "https://www.youtube.com/watch?v=WgU5tDGC-Vc"

설정 옵션

| 옵션 | 설명 | 기본값 | | :--- | :--- | | -i, --interval | 스크린샷 간격(초) | 2 | | --model | Claude 비전 모델 ID | claude-sonnet-5 | | --sample | 영역 탐지를 위해 샘플링된 프레임 수 | 6 | | --dedup-threshold | Pre-dedup Hamming distance | 12 | | --max-height | 최대 다운로드 해상도 | 720 | | --keep-temp | 중간 프레임 및 크롭 이미지 유지 여부 | False |

커뮤니티 인사이트 및 한계점

기술적 제약

사용자와 개발자들은 특정 비디오 포맷에 대한 잠재적 한계점을 지적했습니다. 예를 들어, 현재의 정적 수직 영역 크롭 방식은 재생 헤드가 중앙에 머물고 음악이 뒤로 움직이는

Sources