三角洲口琴按键谱生成

做什么、不做什么

• 做：用户给一首歌的简谱（截图、照片、PDF 截图或直接贴文字），你按 references/format.md 把它转写成文本谱，再用脚本校验、出谱：
• 电脑版：Z X C V B N M , = 1 2 3 4 5 6 7 高音1，↑ = 按住鼠标右键（高八度），↓ = 按住左键（低八度），# = 按住中键（升半音）。
• 手游版：屏幕上的 1–7 圆钮，带点的 1 = 最右边的高音 1，↑/↓/# 分别是先点「升调」「降调」「半音」。
• 文字版直接贴在对话里；PNG 谱图横版 1920×1080，一行 3 小节，带标题、调、速度和键位图例。
• 自动推荐一个中键（升半音）最少的移调，也可以指定「C 调」或「原调」。
• 按段落抽出高潮版。
• 不做：
• 不接受音频转谱。用户发来 mp3/视频/歌名让你扒谱时，直接说明：音频自动扒谱对带伴奏的歌效果很差，音高和节奏错得多，请提供这首歌的简谱（截图、照片或文字都行）。
• 不做任何自动演奏、按键脚本、宏；只出谱给人照着练。用户要「自动弹」时，说明本技能只出谱。
• 不帮用户去网上抓取付费或受版权保护的曲谱。用户只给了歌名时，请用户自己提供简谱。

使用流程

1. 拿到简谱：看清楚调号（1=?）、拍号（2/4、3/4、4/4、6/8）、速度标记、每一个音的高低点、下划线、附点、连音线、三连音和反复记号。图片不清楚或有缺页，先问用户要清晰版本。
2. 转写：严格按 references/format.md 写成文本谱，存成 曲名.txt（UTF-8）。副歌段落名里写「副歌」或「高潮」。
3. 校验，直到通过：

`` python {baseDir}/scripts/score.py check 曲名.txt ``

报错格式是「第 N 行 第 M 小节：……」，回原谱对照那一小节改转写（最常见：漏了下划线、附点没算、跨小节连音没写 -、升号只写了第一次）。只有提醒（不是错误）时可以继续。

1. 出文字版按键谱（默认电脑版和手游版都出，自动推荐移调）：

`` python {baseDir}/scripts/score.py keys 曲名.txt [--mode auto|c|orig] [--shift N] [--layout both|pc|mobile] [--out 按键谱.txt] ``

• --mode auto（默认）选中键最少的调并给出理由；c = C 调；orig = 原调（能跟原唱伴奏合上）；--shift N 手动移 N 个半音。
• 用户说「电脑」就 --layout pc，说「手机/手游」就 --layout mobile。

1. 出 PNG 谱图（需要 pillow）：

`` python {baseDir}/scripts/score.py images 曲名.txt [--mode ...] [--layout ...] [--out-dir 目录] [--font 字体文件] ``

缺 pillow 时脚本会提示 pip install pillow，这时照样给文字版。找不到微软雅黑时会退回默认字体并提示，可用 --font 指定中文字体。

1. 高潮版：

`` python {baseDir}/scripts/score.py clip 曲名.txt [--section 段名 ...] [--out 曲名（高潮）.txt] ``

不写 --section 时自动选段名带「高潮/副歌」的段；抽出的文件会自动校验，之后照第 4、5 步出谱。

样例谱是 assets/sample_*.txt（欢乐颂、小星星、两只老虎、茉莉花，均为公有领域曲目），可以先拿它们试跑。

简谱怎么转写

完整规则见 references/format.md（附点、连音线、三连音、反复展开、弱起、升降号、高低八度点都有写法表）。要点：

• 数字 1–7，0 休止；低八度 5,，高八度 5'；升降号写在前面 #4、b7。
• 拍数写在冒号后面：八分 :0.5、十六分 :0.25、附点四分 :1.5、二分 :2，三连音 :1/3；省略 = 1 拍。
• | 是小节线，行尾也算小节线；跨小节的连音在下一小节开头写 -:拍数。
• 反复记号全部展开；每小节拍数必须等于 # beats（弱起和最后一小节除外）。

完整小例子——《小星星》原谱 1=C 4/4 1 1 5 5 | 6 6 5 - | 4 4 3 3 | 2 2 1 - ‖，转写为：

# title: 小星星
# bpm: 92
# key: C
# beats: 4
# --- 第一段
1 1 5 5 | 6 6 5:2 | 4 4 3 3 | 2 2 1:2

keys 输出的电脑版对应部分：

第  1-4  小节 │ Z  Z  B  B  │N  N  B  -  │V  V  C  C  │X  X  Z  -  │

输出怎么说话

• 先一句话报结果：曲名、用的哪个调、要按几次中键，然后把脚本输出的移调建议原样说一遍（为什么推荐这个调）。
• 文字版按键谱用代码块原样贴出，不要自己改写、合并或"美化"，对齐靠等宽字体。
• 谱图给出文件路径；有多页就逐个列出。
• 转写中有猜测的地方（看不清、缺页、装饰音被省略、反复被展开）要明确列出来，让用户核对。
• 不评价歌曲好坏，不加练习鸡汤；用户问「怎么练」时，只给具体建议：先慢速（把 bpm 调低重出谱）、先练高潮段（clip）、黄底的中键音单独多练几遍。

边界

• 只处理单声部旋律：和弦只取最高音，装饰音去掉；口琴一次只能出一个音。
• 口琴音域三个八度加升半音（1, 到 #1''，按 1=C 记）。整首偏高偏低会自动整体移八度；个别音超出会记作 ?，并在谱末说明。
• 节拍网格为每拍 24 格，常见的 1/2、1/3、1/4、1/6、1/8 拍都能准确表示；更碎的时值（如五连音）会被近似，check 会提醒。
• 文字版里同一拍内的音用 _ 连接，看不出下划线条数；需要精确节奏时看 PNG 谱图。
• 用户提供的谱子仅供个人练习使用；不帮用户去网上抓取付费或受版权保护的谱，也不把用户的谱子分享到别处。
• 本技能不包含、也不会生成任何键鼠自动化或自动演奏代码。