skills/musicXML-ocr/SKILL.md

name, description

name	description
musicXML-ocr	乐谱图片 OCR 技能。将五线谱图片（PNG/JPG/PDF）识别并转换为 MusicXML 格式。使用 Audiveris 进行光学音乐识别（OMR）。当用户提到"识别乐谱"、"图片转 MusicXML"、"打谱"、"手抄谱转数字"时触发此技能。

MusicXML OCR Skill

功能概述

将五线谱图片（PNG/JPG）或 PDF 通过 OCR 识别转换为 MusicXML 格式，支持：

• 扫描/拍摄的手拍乐谱图片 → MusicXML
• PDF 中的乐谱页面 → MusicXML
• 音符、节拍、调号识别
• 钢琴谱 grand staff 结构
• 输出可在 MuseScore、Finale 等软件打开

触发场景

• "识别这张乐谱"
• "把图片转成 MusicXML"
• "帮我打谱"
• "手抄谱数字化"
• "识别五线谱"

---

推荐 Workflow

PDF → 图片提取 → Audiveris 识别 → MuseScore 合并修正

Step 1: PDF → 图片

如果 PDF 无法被 Audiveris 直接处理，需要先提取图片：

import fitz  # PyMuPDF

pdf_path = r"input.pdf"
output_dir = r"temp\sheets"
os.makedirs(output_dir, exist_ok=True)

doc = fitz.open(pdf_path)
for page_num in range(len(doc)):
    page = doc[page_num]
    images = page.get_images()
    for img_idx, img in enumerate(images):
        xref = img[0]
        pix = fitz.Pixmap(doc, xref)
        if pix.n - pix.alpha < 4:
            pix.save(f'{output_dir}/page{page_num+1}_img{img_idx+1}.png')
        else:
            pix1 = fitz.Pixmap(fitz.csRGB, pix)
            pix1.save(f'{output_dir}/page{page_num+1}_img{img_idx+1}.png')
doc.close()

Step 2: Audiveris 识别

# 单张图片识别
& "C:\Program Files\Audiveris\Audiveris.exe" -batch -export -output "D:\output" "D:\input\sheet.png"

# PDF 直接处理（如果支持）
& "C:\Program Files\Audiveris\Audiveris.exe" -batch -export -output "D:\output" "D:\input\score.pdf"

输出文件：

• .omr - Audiveris 项目文件（可再次打开编辑）
• .mxl / .xml - MusicXML 格式

Step 3: MuseScore 合并与修正

推荐在 MuseScore 中手动处理：

1. 打开第一页的 .mxl 文件
2. 菜单 → 文件 → 导入 → 选择第二页的 .xml
3. 或直接复制粘贴各部分

在 MuseScore 中修正：

• 删除错误识别的符号（选中 → Delete）
• 修正小节号（双击小节号直接编辑）
• 合并后的文件另存为 .mscz 或 .mxl

---

安装 Audiveris

Windows：

winget install --id Audiveris.Audiveris --accept-package-agreements --accept-source-agreements

手动下载：

• https://github.com/Audiveris/audiveris/releases

路径：

C:\Program Files\Audiveris\Audiveris.exe

---

方案对比

方案	准确率	可靠性	推荐度
Audiveris → MuseScore 手动合并	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	✅ 推荐
Audiveris 直接处理 PDF	⭐⭐⭐⭐	⭐⭐⭐	备选
homr	⭐⭐⭐	⭐⭐⭐	⚠️ 备选

经验总结：

• Audiveris 识别准确率高（第一小节测试完全正确）
• homr 存在 dewarping 问题，识别可能完全错误
• XML 合并不可靠，建议在 MuseScore 中手动合并
• 分页处理时，每页是独立的乐谱，小节号需要手动修正

---

脚本工具

脚本	功能	依赖
extract_pdf_images.py	从 PDF 提取五线谱图片	fitz (PyMuPDF)
audiveris_to_musescore.py	Audiveris 完整流水线	Audiveris 已安装

使用方法

# 1. 提取 PDF 图片
python scripts/extract_pdf_images.py "D:\scores\sheet.pdf" "D:\output\sheets"

# 2. Audiveris 识别
& "C:\Program Files\Audiveris\Audiveris.exe" -batch -export -output "D:\output" "D:\output\sheets\page1.png"

# 3. 在 MuseScore 中合并修正
# 打开 .omr 文件，手动修正后导出

---

验证清单

处理完成后，检查 MuseScore 中的结果：

• 音符位置与原图对应
• 小节号连续正确
• 钢琴谱上下两行用花括号连接
• 无多余/重复的符号

---

故障排除

问题	解决方案
Audiveris 无法处理 PDF	先用 extract_pdf_images.py 提取图片
识别有多余符号	在 Audiveris 中选中删除，或在 MuseScore 中修正
小节号不连续	在 MuseScore 中手动修正小节号
XML 合并出错	在 MuseScore 中手动复制粘贴合并
homr 识别全错	改用 Audiveris