ytpiano2sheet

ytpiano2sheet 是做什么的？

ytpiano2sheet.py（位于此文件夹中）读取钢琴教程视频中的下落式彩色条块。这些条块源自钢琴家自己的 MIDI，因此比转录音频精确得多：在两个测试视频中，它与手动验证的转录在 990 个音符中匹配了 989 个，与独立的按键读取在 947 个中匹配了 947 个。它仅适用于显示条块落在（或从键盘上升起的）视频。

转录结果仅供用户个人练习使用：音乐归属于其作曲家、编曲者和视频创作者。请勿代用户上传、发布或共享输出结果；如果用户要求，请引导他们阅读 README 中的“个人使用和法律说明”部分。

使用 uv run <此文件夹路径>/ytpiano2sheet.py ... 运行所有内容；uv 会自动安装 Python 依赖项。下面，$BS 表示此文件夹的绝对路径。

1. 首先询问

如果用户没有提供链接或视频文件，请以纯文本形式询问。

然后通过一次 AskUserQuestion 调用同时询问这两个问题（跳过用户已经回答的问题）：

1. “你想要哪些输出？”（multiSelect: true）
   • “PDF 乐谱”（格式 pdf）
   • “MIDI 文件”（格式 mid）
   • “可听的音频 (m4a)”（格式 m4a）
   • “MusicXML + MuseScore 文件”（格式 musicxml,mscz，用于编辑乐谱） “其他”可以指定 wav 或 review（显示条块和检测到的音符的图像）。
2. “你将在哪种键盘上演奏？”
   • “88 键，全钢琴（推荐）”（88）
   • “76 键”（76）
   • “61 键”（61）
   • “49 键”（49） “其他”可以是其他尺寸（73、37、32、25）或像 C2-C7 这样的范围（中央 C 是 C4）。键盘外的音符会按整个八度移动，因此和声保持不变。

2. 前置条件

1. uv --version。如果缺少 uv，请先询问是否安装（brew install uv，或 curl -LsSf https://astral.sh/uv/install.sh | sh）。
2. uv run $BS/ytpiano2sheet.py --check --formats <formats>。它会列出缺少的内容（pdf/mscz 需要 MuseScore，音频需要 fluidsynth 和音色库，m4a 需要 ffmpeg）以及安装每个内容的命令。
3. 如果缺少某些内容，请用 AskUserQuestion 询问是否安装，说明每个项目及其命令（例如“brew install --cask musescore”、“下载 32 MB 音色库到 ~/.cache/ytpiano2sheet”）。如果他们同意，请在步骤 3 的运行中添加 --install。如果安装需要 sudo（Linux 上的 apt-get），请让用户自己用 ! 前缀运行该命令，然后再次检查。如果他们不同意，请删除需要缺失工具的格式，并说明删除了哪些。

3. 运行

uv run $BS/ytpiano2sheet.py "<链接或文件>" -f <格式>,review -k <键盘> -o <输出文件夹> [--install]

• 即使没有要求，也要始终添加 review：你需要步骤 4 中的图像。之后删除 review 文件夹，除非用户要求保留。
• 默认输出文件夹：用户当前项目中的 out/ 文件夹，除非另有指定。每首歌曲在其中有自己的文件夹，以视频标题命名：out/<歌曲>/<歌曲>.pdf 等，out/<歌曲>/review/，以及用于较小键盘的 <歌曲> (61 键).*。
• 对于 2-3 分钟的视频（含下载）大约需要一分钟。日志会报告检测到的键盘、条块速度、音符数量，以及乐谱的猜测调号和拍号。
• 可选标志：--meter 3 或 --meter 4 以及 --key D / --key d（d 小调）覆盖乐谱的猜测。乐谱仅猜测 3/4 或 4/4：当你知道曲子是复合拍子（肖邦的夜曲 Op. 9 No. 2 是 12/8，船歌是 6/8），或者 4/4 曲子的三连音（月光奏鸣曲）使乐谱出现过多的 3/4 小节时，传入 --meter 12/8、6/8 或 9/8；当视频的键盘在异常键处被截断时（日志在不得不猜测时会发出警告），使用 --lowest C2；当开头或结尾画面仍出现在检查图像中时，使用 --start / --end（秒）；当某些条块（通常是深色条块）没有矩形框时，使用 --threshold N（低于日志记录的阈值）。

如果它停止并显示“在键盘上方未找到移动的条块”，则视频没有下落式条块（例如拍摄的钢琴）。告诉用户此工具无法读取它。

4. 报告前检查

使用 Read 工具打开几张检查图像：第一张、中间一张、最后一张，以及任何看起来密集的图像。每个明亮的条块都应带有一个包含音符名称的矩形框，并且没有矩形框落在空白区域上。还要检查：

• 日志中的键盘行显示 88 键 A0-C8，或合理的较小范围；
• 乐谱的调号与音乐匹配（日志行 sheet: key ...）；
• 对于 PDF，第 1 页看起来像钢琴乐谱。在 macOS 上用 sips -s format png <pdf> --out page1.png 或 MuseScore 的 -o page1.png 转换，然后查看。

如果条块缺失或错误，请使用时间戳说明，不要隐瞒。首先尝试标志：当只有乐谱的拍号或调号看起来错误时（MIDI 不会改变），使用 --meter 或 --key；当日志中的键盘范围不正确时，使用 --lowest。

如果阅读器本身错误且没有标志有帮助，请不要默默编辑脚本。一个修复可能使一个视频工作，但会破坏其他视频，而错误的结果看起来仍然像合理的乐谱。解释看起来错误的内容及原因，然后使用 AskUserQuestion 询问是否修补本地副本。如果用户同意：

1. 在编辑之前，将要更改的每个脚本复制到歌曲文件夹（ytpiano2sheet.py.orig、sheet.py.orig）。
2. 做出能修复原因的最小更改，重新运行，并重做上述检查。然后运行 uv run $BS/test_ytpiano2sheet.py；如果失败，恢复原文件。
3. 在歌曲文件夹中编写 bug-report.md：视频链接、错误的时间戳、相关的日志行，以及每个更改与其 .orig 文件的 diff -u，以便作者可以针对参考视频测试修复并将其发布给所有人。
4. 使用 AskUserQuestion 询问是否用该报告向上游提交 issue。只有在同意的情况下，并且只有安装了 gh 且已登录时才执行：gh issue create --repo <所有者/名称（来自 git -C $BS remote get-url origin）> --title "<失败视频风格的简短描述>" --body-file <歌曲文件夹>/bug-report.md，然后向用户提供 issue 链接。如果没有 gh，或者 $BS 不是 git 克隆，请告诉用户 bug-report.md 的位置，以便他们自己发布。

5. 报告

列出写入的文件、音符数量、使用的调号和拍号、键盘折叠移动的任何音符（日志行 keyboard ...: N notes moved），以及步骤 4 中任何看起来有问题的地方。如果脚本被修补，请如实说明并指出 bug-report.md。保持简短。