---
name: musicXML-ocr
description: 乐谱图片 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 直接处理，需要先提取图片：

```python
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 识别

```powershell
# 单张图片识别
& "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：**
```powershell
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 已安装 |

### 使用方法

```powershell
# 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 |