Windows下Tesseract自定义训练：从零实现音符识别

1. 为什么要在Windows上折腾Tesseract做音符识别

很多人第一次听到"用Tesseract识别音符"都会愣一下——Tesseract不是OCR文字识别引擎吗，怎么跑去认音符了？这个思路其实并不离谱。乐谱本质上就是一种"印刷符号的二维排布"，五线谱上的符头、符干、符尾、升降号、拍号，在图像层面和字母数字没有本质区别，都是黑白像素构成的固定形状。Tesseract的核心能力是"给定一张二值化图像，输出它认为最可能的字符序列"，只要我们把音符符号训练成它认识的"字符"，它就能干这个活。

问题在于，Tesseract自带的训练数据是针对拉丁字母、数字和常见标点优化的，它压根没见过音符长什么样。你直接拿一张乐谱图片丢进去，它要么输出一堆乱码，要么把符头认成字母"o"、把升号认成"#"。所以必须走自定义训练这条路：自己准备音符样本、自己标注、自己生成训练数据、自己训练出一个专门认音符的模型。

这个项目适合谁？我认为有三类人值得动手试试。第一类是做音乐教育类工具的开发，比如想把纸质乐谱批量转成可编辑格式；第二类是做乐理辅助软件的，需要从截图里提取音符信息；第三类就是单纯想搞明白Tesseract训练流程的技术爱好者——音符识别只是一个载体，真正学到的是"如何让一个通用OCR引擎认识新符号"这套方法论，换成化学结构式、电路符号、棋谱，流程几乎一模一样。

Windows平台做这件事有个天然优势：Tesseract的官方Windows构建、训练工具链、以及各种辅助脚本都有现成的exe，不需要折腾编译环境。但坑也不少，最大的坑是训练工具版本混乱——网上流传的教程有的用旧版box编辑器，有的用LSTM训练流程，命令完全不兼容。我下面会以目前主流的LSTM训练路线为主，把每一步的意图和踩坑点讲清楚。

2. 训练前的环境搭建与工具选型逻辑

2.1 到底需要装哪些东西

先把工具清单列出来，每一项我都说明为什么需要它，避免你装了一堆不知道干嘛的软件。

这里要特别强调：普通Tesseract安装包和训练工具包是两回事。很多人装了Tesseract发现没有text2image命令，就是因为装的是运行时版本。你需要找带training tools的构建，或者单独下载训练工具集。装完之后在命令行敲tesseract --version和text2image --help，两个都能正常输出才算环境OK。

2.2 目录结构要提前规划好

训练过程会产生大量中间文件，如果随手乱放，后面合成模型时路径能把你逼疯。我建议一开始就建好这样的目录树：

note_ocr/ ├── samples/ # 原始音符样本图片 ├── ground_truth/ # 标注好的训练文本 ├── boxfiles/ # 生成的box文件 ├── training/ # 训练中间产物 ├── output/ # 最终模型 └── scripts/ # 各种脚本

提示：路径里千万不要出现中文和空格。Tesseract的训练工具对非ASCII路径支持很差，一个中文文件夹名就能让lstmtraining报出莫名其妙的错误，这个坑我踩过不止一次。

2.3 音符字符集的设计思路

这是整个项目最容易被忽视、却最影响成败的一步。Tesseract训练的本质是"字符分类"，你得先定义清楚"有哪些字符"。音符的字符集设计要考虑几个维度：

• 符头类型：全音符、二分音符、四分音符、八分音符……它们的符头形状不同（空心/实心），但符干符尾是附加的。一种做法是把"符头+符干+符尾"整体当成一个字符，另一种是拆开识别再组合。
• 变音记号：升号、降号、还原号，这些是独立符号，适合单独作为字符。
• 谱号与拍号：高音谱号、低音谱号、4/4、3/4等，形状固定，适合单独训练。
• 休止符：全休止、二分休止等，形状差异大，必须纳入字符集。

我的建议是先做减法：第一版只训练四分音符、二分音符、全音符、升号、降号这五类，跑通全流程后再逐步加符号。一上来就想把整个乐谱符号体系全塞进去，标注工作量会大到让你放弃。

字符集确定后，给每个符号分配一个唯一的映射字符。Tesseract的字符集是基于Unicode的，你可以用一些不常用的符号来代表音符，比如用♪代表四分音符、♫代表八分音符。但要注意，训练时的字符映射必须和识别时的输出解释保持一致，否则识别出来你也不知道是啥。

3. 音符样本的制作与标注实操

3.1 样本从哪来：三种获取途径对比

训练数据是OCR训练的命根子。音符样本的获取有三条路，各有优劣：

途径一：从现成乐谱图片切割。找一批排版规范的乐谱图片，用图像处理把单个音符切出来。优点是样本真实、风格多样；缺点是切割对齐很麻烦，音符之间的连线和符干容易粘连，切出来的样本经常带"尾巴"。

途径二：用字体渲染生成。找一款音乐符号字体（比如常见的SMuFL标准字体），用Python把每个符号渲染成图片。优点是干净、可控、要多少有多少；缺点是风格单一，和真实乐谱的印刷效果有差距。

途径三：手工绘制。用绘图软件一个个画。优点是完全可以按需定制；缺点是效率极低，几百个样本能画到你怀疑人生。

我的实际做法是途径二为主、途径一为辅：先用字体渲染生成大量干净样本把流程跑通，再用真实乐谱切割的样本做补充，提升模型对真实场景的适应力。下面给一段用Pillow渲染音符样本的示例代码：

from PIL import Image, ImageDraw, ImageFont import os # 假设你已经有一款音符字体 font_path = "path/to/music_font.ttf" font_size = 48 font = ImageFont.truetype(font_path, font_size) # 音符字符到文件名的映射 symbols = { "quarter_note": "\u2669", # 四分音符 "eighth_note": "\u266A", # 八分音符 "sharp": "\u266F", # 升号 "flat": "\u266D", # 降号 } os.makedirs("samples", exist_ok=True) for name, char in symbols.items(): # 创建白底黑字图片，尺寸留足边距 img = Image.new("L", (80, 80), color=255) draw = ImageDraw.Draw(img) # 居中绘制 bbox = draw.textbbox((0, 0), char, font=font) w = bbox[2] - bbox[0] h = bbox[3] - bbox[1] draw.text(((80 - w) / 2 - bbox[0], (80 - h) / 2 - bbox[1]), char, font=font, fill=0) img.save(f"samples/{name}_001.png")

这段代码的关键点是白底黑字——Tesseract训练默认期望前景是黑色、背景是白色，如果你生成的是黑底白字，后面还得做反色处理。另外边距要留够，音符贴边会导致box文件坐标越界。

3.2 样本数量与多样性的平衡

需要多少样本？这是被问得最多的问题。我的经验是：每个字符至少准备20到30个不同变体，变体来源包括不同字号、不同字体、轻微旋转、轻微模糊、不同粗细。太少模型学不会，太多训练时间爆炸且边际收益递减。

多样性比数量更重要。如果你准备了500个一模一样的四分音符，模型只会记住那一个形状，换个字体就废了。所以渲染时要随机化这些参数：

• 字号在40到60之间随机
• 旋转角度在-3到+3度之间随机
• 加入轻微高斯噪声模拟扫描噪点
• 随机调整笔画粗细（用形态学膨胀/腐蚀）

3.3 用jTessBoxEditor做标注的完整流程

样本有了，接下来要生成box文件并标注。box文件记录的是"每个字符在图片中的位置和它是什么字符"，格式是：

字符 左 下 右 上 页码

生成box文件的标准做法是把所有样本合并成一张多页tif，然后跑Tesseract生成初始box：

# 把所有png合并成一个tif（用ImageMagick或Python） # 然后用Tesseract生成box tesseract samples.tif samples batch.nochop makebox

生成的box文件里，字符识别结果大概率是错的（Tesseract不认识音符），位置也可能不准。这时候就轮到jTessBoxEditor出场了：

1. 打开jTessBoxEditor，加载tif和对应的box文件
2. 逐个检查每个box的位置，拖动调整边界
3. 修改box里的字符内容，改成你定义的映射字符
4. 保存

注意：jTessBoxEditor对Java版本有要求，太新的JDK可能跑不起来，建议用JDK 8或11。另外它打开大tif会比较慢，样本别一次性合并太多，分批处理更稳。

标注这一步是整个流程里最耗时的，也是最不能偷懒的。box位置偏几个像素，训练出来的模型精度就掉一截。我的做法是先自动生成、再人工抽查：自动生成的box如果位置大致对，就只改字符内容；位置明显偏的才手动拖。

4. 从box文件到可训练数据的转换

4.1 生成训练文本的字符映射

box文件标注好之后，需要生成一个"字符集文件"（通常叫unicharset）和对应的训练文本。这一步的核心是告诉Tesseract"我要训练哪些字符"。

# 从box文件生成unicharset unicharset_extractor samples.box # 生成字体属性文件（LSTM训练需要） echo "MyNoteFont 0 0 0 0 0" > font_properties

unicharset_extractor会扫描所有box文件，把出现过的字符收集起来生成字符集。这里有个坑：如果某个字符只在box里出现但你没在训练文本里用到，或者反过来，都会导致后续训练报错。所以生成完unicharset后，打开看一眼，确认字符列表和你的设计一致。

4.2 LSTM训练数据的生成命令详解

Tesseract 5.x主推LSTM训练，需要把box和图片转成LSTM能吃的格式。核心命令是lstmtraining配合--train_listfile，但在此之前要先准备好几个清单文件：

# 生成训练清单：每行是"图片路径 对应的box路径" # 假设图片和box都在同一目录 ls samples/*.tif | sed 's/\.tif$//' > training_files.txt # 生成LSTM训练数据 lstmtraining \ --continue_from "" \ --model_output output/note_model \ --train_listfile training_files.txt \ --traineddata tessdata/eng/eng.traineddata \ --debug_interval 0

这里--traineddata指向一个基础模型，通常用英文的eng.traineddata作为起点。为什么用英文模型而不是从零开始？因为从零训练需要海量数据，而我们只有几百个样本。在已有模型基础上做微调（fine-tune），是样本量有限时的标准做法，英文模型已经学会了"如何识别黑色形状"这个通用能力，我们只需要让它把注意力转移到音符上。

4.3 训练轮数与收敛判断

LSTM训练不是轮数越多越好。训练过程中会输出一个"字符错误率"（BCER），这个值降到一定程度就不再下降，继续训练只会过拟合。我的经验是：

• 样本量200左右时，训练500到1000轮通常够用
• 观察BCER，如果连续200轮没有明显下降，就可以停了
• 训练日志里如果出现"Best model"标记，说明当前是最优模型

训练命令里可以加--max_iterations控制轮数，也可以中途Ctrl+C停止，lstmtraining会自动保存当前最优模型。

5. 模型合成与识别效果验证

5.1 把checkpoint合成成可用模型

训练过程中产生的是checkpoint文件（一堆.checkpoint后缀的文件），不能直接用于识别，需要合成成.traineddata：

lstmtraining \ --stop_training \ --continue_from output/note_model_checkpoint \ --traineddata tessdata/eng/eng.traineddata \ --model_output output/note.traineddata

合成出来的note.traineddata就是最终成果。把它放到Tesseract的tessdata目录下，识别时用-l note指定语言即可：

tesseract test_score.png result -l note

5.2 识别结果为什么和预期不一样

第一次跑识别，你大概率会遇到两种情况：要么输出一堆你定义的映射字符但顺序混乱，要么干脆输出空白。别慌，这很正常，原因通常有这几个：

原因一：识别时的页面分割模式不对。Tesseract默认按"整页文档"处理，会尝试找段落、行、词。乐谱不是文档，应该用--psm 6（假设是一块统一的文本）或--psm 10（单个字符）来识别。

原因二：图像预处理没做。乐谱图片如果是彩色的、有背景纹理的，直接喂给Tesseract效果很差。要先转灰度、二值化、去噪。用OpenCV几行代码就能搞定：

import cv2 img = cv2.imread("score.png", cv2.IMREAD_GRAYSCALE) # 自适应二值化，应对不均匀光照 binary = cv2.adaptiveThreshold(img, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 15, 8) cv2.imwrite("score_binary.png", binary)

原因三：字符映射没对上。训练时你用♪代表四分音符，识别出来也是♪，但如果你在代码里按"quarter"去匹配，当然找不到。要保证训练、识别、后处理三处的映射表完全一致。

5.3 用混淆矩阵定位问题字符

如果识别结果时好时坏，别靠肉眼一个个看，做个简单的混淆统计。把测试样本的"真实字符"和"识别字符"列成表格，一眼就能看出哪些符号容易被搞混：

从这张表能看出，八分音符和四分音符容易混——因为它们符头形状相同，区别只在符尾。这时候要么增加八分音符的样本多样性，要么在预处理阶段先做符干检测把两者分开。

6. 提升精度的几个实战技巧

6.1 数据增强比调参更有效

模型精度上不去，很多人第一反应是调学习率、调网络结构。但在样本量几百这个量级，数据增强的收益远大于调参。具体可以做的增强：

• 弹性形变：模拟纸张轻微扭曲，用OpenCV的warpAffine做小幅随机仿射变换
• 笔画粗细变化：用cv2.dilate和cv2.erode随机调整
• 局部遮挡：随机在样本上画几个小白块，模拟扫描时的污点
• 对比度扰动：模拟不同扫描仪的曝光差异

这些增强用Python批量做，能把有效样本量翻好几倍，而且不需要重新标注——因为变换后的字符还是同一个字符，box位置按同样变换矩阵调整即可。

6.2 分阶段训练的策略

一次性训练所有符号，容易出现"某些符号学得好、某些学得差"的不均衡。更好的做法是分阶段训练：

第一阶段只训练符头类符号（全音符、二分、四分），让模型先掌握符头形状；第二阶段加入符干符尾相关的符号；第三阶段加入变音记号和谱号。每个阶段都在上一阶段的模型基础上继续训练，这样模型是"循序渐进"地学习，而不是一锅乱炖。

6.3 后处理规则能救回不少错误

OCR不可能100%准确，但音符识别有个好处：乐理规则可以当后处理约束。比如：

• 一个小节内的拍数必须符合拍号，如果识别出的音符时值加起来不对，说明有误识
• 升号和降号不会同时出现在同一个音上
• 符干方向有规律（通常朝上或朝下取决于音符在五线谱的位置）

把这些规则写成后处理逻辑，能纠正一部分识别错误。这比单纯追求模型精度要划算得多。

7. 这套流程还能迁移到哪些场景

把音符换成别的符号，整套流程几乎不用改。我后来用同样的方法做过几个变体，验证了这套方法论的可迁移性：

化学结构式识别：把苯环、化学键、元素符号当成"字符"训练，难点在于结构式有连接关系，纯OCR只能识别符号，连接关系还得靠额外的图分析。

电路符号识别：电阻、电容、电感符号形状固定，很适合OCR。但电路图里符号之间的连线是识别难点，需要先做线段检测把连线去掉，再识别符号。

棋谱识别：围棋、象棋的棋子识别，本质也是符号分类。棋盘格子的定位可以用霍夫变换先做，然后每个格子单独识别。

手写数字/字母识别：这是OCR的经典场景，但手写体的多样性远大于印刷体，样本量要求高一个数量级。

迁移时唯一需要重新设计的是字符集和后处理规则，训练流程本身是通用的。这也是我觉得这个项目最有价值的地方——你学到的不是"怎么认音符"，而是"怎么让OCR引擎认识任意新符号"。

8. 我在实际操作中踩过的几个坑

最后分享几个具体的坑，都是文档里不会写、但实际做的时候一定会遇到的。

坑一：tif文件的DPI问题。Tesseract训练对图片DPI敏感，如果tif的DPI信息缺失或异常，生成的box坐标会错乱。合并tif时一定要显式设置DPI，通常用300。用ImageMagick的话加-density 300参数。

坑二：box文件的字符编码。如果你用Unicode音符字符（比如♪），box文件必须存成UTF-8，而且不能有BOM头。Windows记事本默认可能存成带BOM的UTF-8，这会让unicharset_extractor读出一堆乱码字符。用VS Code或Notepad++确认编码格式。

坑三：训练中断后无法续训。lstmtraining中断后会留下checkpoint，但续训时如果--continue_from指向的文件不对，会从头开始。续训要指向xxx_checkpoint文件，而不是xxx.traineddata。

坑四：识别时语言包路径。自定义的note.traineddata必须放在Tesseract能找到的tessdata目录，或者用--tessdata-dir显式指定。放在当前目录下直接跑-l note是找不到的，这个错误信息很隐晦，经常让人以为是模型没训练好。

坑五：样本图片的背景不能是透明。PNG的透明背景在转tif时会变成黑色，导致整个样本反色。生成样本时要么用白底，要么转tif前先做背景填充。

这套流程从环境搭建到跑出可用模型，顺利的话两三天，不顺利的话一周都正常。关键是要有耐心做标注和调样本，模型精度这东西，七分靠数据、三分靠训练，把数据质量抓上去，后面的事就水到渠成了。