谱子生成MP3单声部视唱跟唱（sheet-to-mp3-sight-singing）
把单声部谱面照片变成可跟唱的练习 MP3（钢琴 + 节拍器），并输出可编辑的 MusicXML。
能力范围（Scope）
能做：单声部旋律的识谱（标准五线谱、含调号/拍号/休止/附点/连音线/连奏线）、页码与谱表定位、
按用户要求渲染任意速度与是否反复、混节拍器、导出 MusicXML，以及"只改某一小节 → 重渲染"。
部分能做：和弦/复调（只取最高声部，需明确告知）、手写谱（只作辅助）、装饰音（默认不录入）、
低质量照片（需重拍或标注不确定处）、小型打击谱（不支持）。
不能做：整份总谱/多声部对齐、从录音转谱（需要另外的转写工具）、音色精修与混音母带、
速度渐变/自由速度的精确保留。
铁律（Non-negotiables）
- 连音线（tie）= 一个音，不重击；连奏线（slur）= 分音但连贯。读谱时必须按"是否同音高"区分二者，
编码时用tie/slur字段分别记录，渲染后要检查连音处没有新的击键。见references/reading.md、
references/encoding.md、references/verification.md。 - 不臆造音符。机器漏检（阴影/反光/弯曲）时必须留空并标注，向用户要重拍或确认，不许用均匀填充凑数。
- 先问后做。识谱完成后、渲染之前，按
references/intake.md的清单与用户确认（顺奏/反复、速度、
节拍器、音色、交付格式、命名、是否只留最终版……）；用户说"你定"时用清单里的默认值，并在交付说明里写明。 - 交付前自检：
references/verification.md的清单要跑一遍，特别是每小节拍数、总时长、
节拍器对齐、连音处无重击、最低/最高音八度抽查。
分层结构与流程（Stages → References）
| 阶段 | 做什么 | 读哪个 reference | 用什么脚本 |
|---|---|---|---|
| 0 收需求 | 收照片、确认范围，读 intake.md 的默认值 |
references/intake.md |
— |
| 1 识谱 | 照片质检 → 逐条谱表读音高/时值/连线/结构 | references/reading.md |
scripts/prep_for_omr.py、omr.py、read_system.py、rectify.py |
| 2 编码 | 写成 JSON（音高、时值、tie、slur），并自校验 | references/encoding.md |
scripts/check_spec.py |
| 3 确认 | 把识谱结果 + 问题清单交给用户确认（顺奏/速度/节拍器…） | references/intake.md |
— |
| 4 渲染 | MusicXML + MuseScore 渲染 + 混节拍器 | references/rendering.md |
scripts/render_practice_audio.py |
| 5 自检 | 时长、拍数、节拍器、连音、八度 | references/verification.md |
render_practice_audio.py（内置检查） |
| 6 交付 | 命名、版本、桌面 + outputs、说明文件 | references/intake.md §交付 |
— |
工具选型（Audiveris / MuseScore / Verovio / music21 以及各自的坑）见 references/tools.md。
最小可用命令
# 1) 照片预处理（OMR 或人工读谱都用得上）
python scripts/prep_for_omr.py page.png prep.png --crop L T R B --scale 1.2
# 2) 逐条谱表量测音高（resid > 0.25 说明五线拟合可疑，八度要复核）
python scripts/read_system.py prep.png TOP BOTTOM XL XR --key=Bb
# 3) 校验 JSON（每小节拍数、tie/slur 配对、音域范围）
python scripts/check_spec.py piece.json
# 4) 渲染（默认 MuseScore 真钢琴 + 节拍器；--synth 用内置合成器兜底）
python scripts/render_practice_audio.py piece.json --outdir out --version 3
