liebharc/homr

homr – AI驱动的光学乐谱识别：将乐谱图像转换为 MusicXML

功能

• 将乐谱的照片或 PDF 转换为 MusicXML 文件，这是 MuseScore 等音乐程序可读取的数字格式。
• 转换通过命令行工具（homr <图像>）在本地运行。输出文件保存在输入图像旁边。

工作原理

1. 分割 – UNet 风格的神经网络（借用自 oemer 项目）扫描图像并识别基本视觉元素：谱线、音符符头、符干、休止符、谱号、小节线等。为每个元素生成边界框。
2. 谱表重建 – 使用检测到的元素，代码找到“谱表锚点”（谱号、小节线）并估计谱线之间的距离（单位大小）。即使照片倾斜或间距不均匀，也能重建五线谱。还检测花括号/方括号，以便合并大谱表（钢琴）或多个声部。
3. 符号识别 – 每个谱表进行去畸变（透视校正）后输入变换器模型（基于 Polyphonic‑TrOMR）。变换器预测一系列音乐符号：音符时值、音高、临时记号、休止符、连音和部分演奏记号。模型还会为每个符号输出粗略的图像位置，并作为注释存储在 MusicXML 中。
4. MusicXML 导出 – 将符号序列转换为可在 MuseScore、Sibelius 或其他乐谱软件中打开的标准 MusicXML 文件。

快速开始

• 需要 Python 3.11/3.12。
• 通过 uv（最快）或 Poetry 安装。CPU 推理的 uv 示例：

  uvx --from 'homr[cpu]' homr path/to/score.png
  

• 对于 GPU 加速，将 extra 替换为 cuda（NVIDIA）或 rocm（AMD）。
• 一次运行多个图像：homr img1.png img2.png → 生成 img1.musicxml、img2.musicxml。
• 使用外部工具 relieur 合并多个 MusicXML 文件。

演示与资源

• 在线快速演示：https://homr.site（或启动提供的 Colab 笔记本）。
• Android 前端：Andromr 应用在底层使用此库。

当前限制

• 侧重于高音谱号和低音谱号中的音高和节奏。
• 不处理力度、除少数标记外的演奏记号、重升/重降号或许多其他高级记谱符号。

技术亮点

• 两阶段流水线（分割 → 变换器）反映了最先进的 OMR 研究。
• 使用 oemer 的预训练 UNet 模型和 Polyphonic‑TrOMR 的变换器模型。
• 在 MusicXML 中为每个音符添加位置注释（<!-- imgpos: x, y -->），便于下游处理。

适用人群

• 希望快速数字化印刷乐谱的音乐家或档案管理员。
• 尝试音乐相关机器学习流水线的研究人员。
• 需要摄取乐谱的应用程序（如练习应用、音乐搜索引擎）开发人员。

引用 如果在学术工作中使用 homr，请按 README 中的说明引用原始 oemer 和 Polyphonic‑TrOMR 项目。

---

摘要 – homr 是一个开源 Python 工具，应用现代深度学习（UNet + 变换器）将乐谱图像转换为可编辑的 MusicXML 文件，可通过简单的命令行在 CPU 或 GPU 上运行。