NoteLite 是一款开源的 OMR（Optical Music Recognition，光学乐谱识别）与音乐指导练习工具，能把乐谱 PDF 或图片识别为可编辑的 MusicXML 和 MIDI，并支持用 MIDI 或麦克风反馈来练习。这篇文章基于仓库中 benchmarks/omr/ 目录的实测基准——9 份乐谱、14 页、3165 个音符事件——完整拆解它是怎么给"识别准确率"下定义的，以及一轮修复前后各是多少分。

这套 OMR 准确率实测怎么读：3165 个音符事件的测试集构成

基准分为两类，全部是数字排版的干净谱面（不是相机照片、扫描件或手写稿），这一点决定了结果的适用边界：

① 合成样张（7 份，共 179 个参考音符）

7 份单页 MusicXML 谱例是独立手写的，用 Verovio 6.3.0 排版、resvg 0.5.0 以 2480 像素宽栅格化成 PNG，覆盖 7 个典型难点：

参考音符直接取自手写的事件定义，与 OMR 输出完全独立，不存在"用识别结果对识别结果"的循环验证。

② 外部真实出版谱（2 份，共 2986 个回放音符）

• Petzold《G 大调小步舞曲》（Mutopia，1 页）：出版 MIDI 含 204 个音符，按反复号 1–16 小节、17–32 小节各回放两次，展开为408个回放事件
• Mozart K545 第一乐章（Mutopia，6 页）：1289 个音符，按 1–28、29–73 小节各回放两次，展开为2578个事件

两份外部样本的 PDF 与 LilyPond 原始谱均未做任何修改，反复边界逐条对照了印刷版 PDF 和 LilyPond 源码。输入文件的 SHA-256、来源 URL、许可证（公有领域 / CC BY-SA 3.0）都记录在 external-fixtures/manifest.json 中。

179 + 408 + 2578 =3165个回放音符事件，这就是标题里那个数字的来源。

音符事件 F1：这份乐谱识别基准的判定标准

整份基准只认一个主指标：音符事件 F1，判定规则写在 benchmarks/omr/README.md，匹配函数在 benchmarks/omr/benchmark.py：

• 一对一、最大基数匹配：每个预测音符最多配对一个参考音符
• 音高必须精确：MIDI 音高一个音都差不得
• 起始时间容差 1/16 四分音符拍：120 BPM 下即 31.25 毫秒
• 结束时间容差：取 max(1/16 拍, 参考时长的 20%)
• 不做任何自动时间平移、移调、谱面对齐、前后缀裁剪
• 连音（tie）合并为一个持续事件；反复段落按每次回放各计一次；所有声部/分部合并统计，"识别对了但放错声部"不算错

同时保留 precision / recall / TP / FP / FN 原始计数，另附两个辅助指标：pitch_onset_offset（加上结束时间容差的更严版本）和pitch_inventory_diagnostic（完全忽略时序、只比音高集合的诊断值——官方明确标注它不能当作转录准确率）。

每次运行都调用真正的 NoteLite CLI（-batch -transcribe -export -export-midi），识别只拿到 PNG 或 PDF，永远看不到参考答案；应用 JAR 的 SHA-256、命令行、耗时、控制台日志、识别出的 MusicXML 和生成的 MIDI 全部留档，任何一次结果都可回溯。

完整数据：NoteLite 基准测试 F1 修复前后对比

两个被测版本用 SHA-256 区分：基线 JARe06272fb…，修复版 JARa5592b79…（修复的是 MusicXML→MIDI 导出器，OMR 识别引擎未动）。

合成样张（179 个事件）

单份样张识别耗时约 3.0–4.4 秒。

外部出版谱（2986 个回放事件，按展开后的反复真值评分）

按各组 TP/FP/FN 总量合并计算，3165 个事件修复后命中 2964 个：召回率93.65%，精确率94.45%，综合 F1 约0.941；基线版本则只有约 0.242。

原始明细全部公开在 results/summary.json，含每组每个样张的 TP/FP/FN、耗时（修复版 Mozart 六页 36.2 秒）与pitch_onset_offset更严口径（外部集 0.931）。

根因隔离：为什么"识别准确率"会跌到 18.8%

这是整份基准最有方法论价值的一幕。基线版本在 Mozart 上只有 15.7% 的 F1（预测了 1279 个音符却只对上 302 个），看起来像 OMR 引擎彻底失败了。但对照数据立刻拆穿了这个表象：

• 基线对未展开的出版 MIDI 评分时，《小步舞曲》高达0.998——说明识别结果本身大部分是对的；
• 项目没有就此下结论，而是做了Verovio 对照实验：把 NoteLite 基线版自己导出的 MusicXML，交给独立成熟的 Verovio 6.3.0 重新渲染成 MIDI 再评分。结果《小步舞曲》仍是 0.998，Mozart 却只有0.145——连最成熟的渲染器都救不回来，说明问题根本不在 OMR 图像识别，而在MusicXML→MIDI 导出阶段（反复段落的回放音符丢失/错排）。该诊断思路来自 benchmarks/omr/compare_verovio.py，完整数据见 results/verovio-control/results.json；
• 合成集07_repeats基线 F1 只有 0.667，恰好对应"预测 16 个 / 参考 32 个"——反复段只回放了一次，与根因完全吻合；
• 修复导出器后：合成集 0.938→0.986（反复样张回到满分），外部集 0.188→0.938。

还有一处体现流程严谨的细节：人工审图时发现最初手写的变化音样张漏印了一个还原号，于是修正样张并用原始保留的基线 JAR重跑，最终发布的基线/修复数据均基于修正后的同一张图，初步数字全部剔除。

修复后剩余的错例也逐一定位：01 漏 3 音、02 漏 2 音、Mozart 漏 194 音（7.5%），多为谱面尾部短行、临时变化音一类——官方明说"再干净的排版也可能丢掉最后一条谱行、一次调号变化、一个装饰音"。

如何在自己电脑上复现这份 OMR 基准

环境要求 Java 21 + Tesseract 语言数据，步骤见 benchmarks/omr/README.md：

git clone https://gitcode.com/gh_mirrors/no/NoteLite cd NoteLite ./gradlew :app:installDist python -m pip install -r benchmarks/omr/requirements.txt python benchmarks/omr/benchmark.py generate --fixtures benchmarks/omr/fixtures python benchmarks/omr/benchmark.py run --fixtures benchmarks/omr/fixtures \ --distribution app/build/install/app --output work/my-run --tessdata <tessdata路径>

几个防作弊设计值得注意：输出目录必须为空（拒绝复用旧 MIDI，防止失败的运行悄悄沿用陈旧结果）；识别器生成、参考写入、比对三者互不读取 NoteLite 源码；--only 09_mutopia_mozart可以单跑某个用例（默认单份超时 240 秒）；summarize.py 能对已保存的事件列表重新评分，而不会伪装成另一次应用运行。

这个测试测不了什么：结果边界清单

• 样本是刻意挑选的诊断谱，不是随机代表性样本，因此"93.8% F1"不等于"通用准确率"
• 输入全部是数字排版 PDF/PNG——相机照片、纸质扫描、手写谱不在覆盖范围内
• 不评估速度、表情处理、力度、音色与麦克风实时转录
• 连音合并、声部合并的口径意味着它衡量的是"可回放音符"的还原度，不是乐谱语义的完整度
• 错误的识别结果若直接用于教学/练习会误导演奏者，因此 NoteLite 的正确用法是：识别 → 在编辑器中人工核对修正 → 再进入练习环节

小结

这份基准最值得借鉴的不是分数，而是方法：独立真值、SHA-256 全程留痕、一对一严格匹配、不做任何自动对齐，以及用"独立成熟渲染器重渲染自己导出的中间格式"这一对照实验，把 18.8% 的"识别事故"干净利落地归因到 MIDI 导出器。修复后 3165 个音符事件综合 F1 约 0.941，单份样张 3–4 秒、Mozart 六页 36 秒的吞吐，配合逐条可复现的留档数据，构成了一份可以直接引用的 OMR 准确率实测基线。