marcelpanse/youtube-guitar-tab-parser

来源：https://github.com/marcelpanse/youtube-guitar-tab-parser

YouTube 吉他谱解析器

命令行工具，将 YouTube 吉他教学视频转换为包含吉他谱的 PDF。它会下载视频、采样帧、使用 Claude 视觉能力定位乐谱区域、将每一帧裁剪到该区域、根据谱面每行打印的小节号去重，最后将不同的谱线垂直拼接成 PDF。开箱即用，无需配置——PDF 输出到 out/<视频标题>.pdf，第一页标题和文档元数据均使用视频标题。

系统要求

• Node.js ≥ 20
• PATH 中包含 yt-dlp（https://github.com/yt-dlp/yt-dlp）和 ffmpeg（https://ffmpeg.org/）（brew install yt-dlp ffmpeg）
• Anthropic API 密钥

安装

npm install
npm run build
cp .env.example .env
# 然后在 .env 中填入你的 ANTHROPIC_API_KEY

使用

# 使用 .env 文件
node --env-file=.env dist/cli.js "https://www.youtube.com/watch?v=WgU5tDGC-Vc"

# 或直接导出密钥
export ANTHROPIC_API_KEY=sk-ant-...
node dist/cli.js "https://www.youtube.com/watch?v=WgU5tDGC-Vc"

开发时可以跳过构建步骤：

node --env-file=.env --import tsx src/cli.ts "<视频URL>"

结果写入 out/<视频标题>.pdf（路径也会输出到 stdout）；进度信息输出到 stderr。

选项

所有选项均有合理默认值，通常只需提供 URL。

-i, --interval          截图间隔（秒），默认 2
    --model             Claude 视觉模型，默认 claude-sonnet-5
    --sample            用于检测乐谱区域的采样帧数，默认 6
    --dedup-threshold   预去重 Hamming 距离阈值（成本控制），默认 12
    --max-height        下载分辨率上限，默认 720
    --keep-temp         保留中间帧/裁剪结果

工作原理

1. 下载——yt-dlp 拉取视频（不超过 --max-height）。
2. 帧提取——ffmpeg 每 --interval 秒提取一帧。
3. 检测——在 --sample 帧上绘制带标签的水平带状网格，Claude 视觉模型报告哪些带状区域包含谱面。取中位数首/末乐谱带状位置（可抵抗异常值）得到垂直范围；宽度保持全幅。（带标签的粗粒度带状区域比要求视觉模型给出精确像素坐标更可靠。）
4. 裁剪——用 sharp 将每一帧裁剪到该区域。
5. 预去重——使用 dHash 感知哈希去除连续近似的裁剪帧。这仅用于成本控制，减少下一步中视觉调用次数。
6. 小节号去重——Claude 读取每行开头打印的小节号，并判断该裁剪是否为真实谱面。工具对每个不同的小节号只保留一个裁剪（首次出现者胜出），丢弃非谱面裁剪（标题卡、片头/片尾）。由于在播放光标扫过一行时小节号保持不变，仅在谱面推进时才改变，因此所有近似的光标帧都会被压缩为单独一页。
7. PDF 生成——pdf-lib 将不同的谱线按视频中出现顺序垂直堆叠在 A4 页面上。视频标题（从 yt-dlp 读取）成为文件名、第一页标题和文档元数据标题。输出：out/<视频标题>.pdf。