youtube-guitar-tab-parser: 將 YouTube 吉他教學轉換為 PDF 譜表

youtube-guitar-tab-parser: 將 YouTube 吉他教學轉換為 PDF 譜表

概覽

youtube-guitar-tab-parser 是一款命令列介面 (CLI) 工具，旨在自動從教學類的 YouTube 影片中提取吉他譜表 (tabs)。透過結合影片處理工具與 AI 視覺能力，該工具能識別螢幕中包含樂譜的區域，移除冗餘的影格，並將剩餘的唯一行譜表縫合為格式化的 PDF 文件。

技術架構與工作流程

該工具遵循多階段流水線，將串流影片轉換為靜態文件。它依賴 yt-dlp 進行影片獲取，使用 ffmpeg 進行影格提取，並利用 Anthropic Claude 視覺模型進行空間分析與內容驗證。

1. 影片獲取與影格採樣

處理流程始於使用 yt-dlp 下載影片。為了優化處理時間與 API 成本，工具會限制下載解析度（透過 --max-height 旗標預設為 720p）。接著，ffmpeg 會以可配置的間隔（預設為每 2 秒）提取影格。

2. 譜表區域檢測

為了定位螢幕上的吉他譜表，該工具採用基於網格的檢測方法，而非要求 AI 提供原始像素座標（這通常不夠精確）。它會在少量的樣本影格（預設為 6 個）上繪製標記過的水平帶狀網格，Claude 視覺模型會識別哪些帶狀區域包含樂譜，接著工具會計算第一個與最後一個音樂帶狀區域的中位數，以決定垂直裁剪區域。影格的完整寬度將會被保留。

3. 去重與過濾

由於播放游標移動時，單行音樂可能會出現在許多影格中，因此工具使用了兩層去重流程：

  • 感知雜湊 (Perceptual Hashing)： 使用 dHash (difference hash) 來捨棄近乎相同的連續裁剪圖。這作為一種成本控制措施，以減少傳送給 AI 的影像數量。
  • 條號分析 (Bar-Number Analysis)： Claude 視覺模型會讀取每行開頭印製的小節或條號。工具僅保留每個不同小節號碼的第一次出現，並捨棄非譜表的影格（例如標題卡或介紹部分）。

4. PDF 生成

使用 pdf-lib，工具會將唯一的譜表行依序垂直堆疊在 A4 頁面上，順序與其在影片中出現的順序一致。最終文件會在第一頁以標題形式包含影片標題，並將其包含在元數據中。

安裝與使用

必要條件

  • Node.js： 版本 20 或更高。
  • 系統依賴： 必須安裝 yt-dlp 與 ffmpeg 並使其在系統 PATH 中可用。
  • API 存取： 一個有效的 Anthropic API 金鑰。

快速開始

npm install
npm run build
cp .env.example .env # 在此處添加 ANTHROPIC_API_KEY
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 | 預去重 Hamming 距離 | 12 | | --max-height | 最大下載解析度 | 720 | | --keep-temp | 保留中間影格與裁剪圖 | False |

社群見解與限制

技術限制

使用者與開發者已注意到針對特定影片格式的潛在限制。例如，目前裁剪靜態垂直區域的方法，對於「捲動式」譜表（播放游標保持在中心，而音樂在後方移動）可能不起作用。

成本與效率

部分使用者對使用大型語言模型 (LLM) 進行視覺任務的成本表示擔憂。一位使用者建議，手動標註譜表區域或使用傳統的電腦視覺技術，可能比使用 Claude 視覺模型更具成本效益。

倫理與法律考量

該工具引發了關於從影片中提取譜表的倫理爭議。有些創作者使用這些工具來規避支付 PDF 譜表的費用，而內容創作者則認為這構成了一種盜竊行為：

"幾乎所有那些人都會針對 PDF 收費。他們知道 PDF 比影片更有用，這就是為什麼影片是免費的... 這是一種盜竊行為，而且極其不道德。"

此外，有些音樂家指出，YouTube 上的編曲版本往往是獨特的，且可能與官方印刷樂譜有所不同，這可能導致練習時使用了錯誤的版本。

Sources