skills/musicXML-ocr/references/homr_usage.md

homr 使用指南

安装状态

✅ 当前环境已预装 homr 和 verovio。

首次运行会自动下载检测模型（约 500MB），请耐心等待。

基本用法

命令行

# 基本识别
homr path/to/image.png --output result.musicxml

# 批量处理目录
homr path/to/folder/

# 指定输出文件名
homr image.png -o my_song.musicxml

Python API

from homr.main import process_image, ProcessingConfig, XmlGeneratorArguments

# 注意：homr 对中文路径支持有问题，建议先用 ASCII 路径
image_path = r"path/to/sheet_music.png"

config = ProcessingConfig(False, False, False, False, -1)
xml_args = XmlGeneratorArguments(False, None, None)

result = process_image(image_path, config, xml_args)
print("识别完成！")
# 输出文件自动生成：同目录下 .musicxml 文件

参数说明

参数	类型	说明
model_type	str	模型类型：ctc（默认）或 transformer
language	str	语言：english、german 等
staffline_height	float	五线间距（像素），默认自动检测

输出格式

输出的 MusicXML 包含：

• <part> - 乐器/声部
• <measure> - 小节
• <note> - 音符
• <attributes> - 调号、拍号
• <direction> - 力度、表情记号

错误处理

from homr.main import Homr

try:
    model = Homr()
    result = model.predict("image.png")
except Exception as e:
    print(f"识别失败: {e}")

已知限制

1. 手写体识别效果较差
2. 复杂和声识别可能不准确
3. 装饰音识别有限
4. 首次运行需下载模型（约 500MB）
5. 中文路径问题：homr 对中文路径支持有问题，建议使用英文/数字路径

已知 Bug 修复

如果遇到 numpy 兼容性错误，修改 autocrop.py：

# 原来的：
hist = cv2.calcHist([img], [0], None, [256], [0, 256])
dominant_color_gray_scale = max(enumerate(hist), ...)[0]

# 修复为：
hist = cv2.calcHist([img], [0], None, [256], [0, 256]).flatten()
dominant_color_gray_scale = max(enumerate(hist), ...)[0]