youtube-guitar-tab-parser: 将 YouTube 吉他教学视频转换为 PDF 谱表

youtube-guitar-tab-parser: 将 YouTube 吉他教学视频转换为 PDF 谱表

概述

youtube-guitar-tab-parser 是一个命令行界面 (CLI) 工具，旨在自动从 YouTube 教学视频中提取吉他谱表。通过将视频处理工具与 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 的图像数量。
  • 谱表行号分析: Claude 视觉模型会读取每行开头打印的节拍或小节号。工具仅保留每个不同小节号的首次出现，并丢弃非谱表帧（例如标题卡或介绍部分）。

4. PDF 生成

使用 pdf-lib，该工具将唯一的谱表行按其在视频中出现的顺序垂直堆叠在 A4 页面上。最终文档在第一页的标题处以及元数据中包含视频标题。

安装与使用

要求

  • Node.js: 版本 20 或更高。
  • 系统依赖: 必须在系统 PATH 中安装并可用 yt-dlp 和 ffmpeg。
  • 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