• 桌面应用
• 计算机视觉
• 图像处理
• OCR

本文基于 Audiveris 文档仓库的 How-to 章节（docs/_pages/guides/README.md）编写，覆盖该指南的四大板块——主功能（OMR 流水线、书籍参数、OCR 语言、偏好设置等）、用户编辑（UI 基础、工具与实例）、特定功能与高级功能（CLI、常量、插件、扫描建议）。读完后你将能够：完整理解 Audiveris 20 步 OMR 流水线的执行与干预方式，掌握批量命令行（CLI）全参数用法，并通过Book parameters、Constants、Plugins等机制完成从扫描输入到 MusicXML 导出的全流程。

How-to 章节的组织方式

Audiveris 的 How-to 章节以"渐进式任务导向"方式组织，按用户与软件交互的深度划分为四个部分：

其中Samples与Training两节专门面向需要修改字形分类器（glyph classifier）底层神经网络行为的用户。各板块内部按nav_order顺序展开，形成从"认识流水线"到"手动纠错"再到"深度定制"的完整学习路径。

主功能一：全局工作流与 OMR 流水线

全局书籍工作流

Audiveris V5 的 OMR 引擎可以独立处理书籍（Book）中的任意一页（Sheet），页与页之间互不干扰；只有最后的"汇总"（把各页结果合并为完整乐谱）是书籍级操作，且相对非常快。典型流程（以输入文件foo.pdf为例）：

1. 打开foo.pdf时，Audiveris 创建一个 Book 实例；
2. 检测输入文件包含多少张图片，为每张图片分配一个"页桩"（sheet stub）；
3. 处理某一页时，从输入文件加载对应图片，并运行 OMR 流水线；
4. 任何时刻保存项目时，所有书籍与页的 OMR 信息都会写入foo.omr项目文件。

提示：Audiveris V5 可以容纳数百页的书籍。为节省内存（尤其是长时间交互会话），可以让 Audiveris 把除当前页之外的所有页透明地换出（swap）到磁盘，通过Book → Swap out sheet after processing菜单项开启；CLI 中对应的选项是-swap。

页级流水线：20 个步骤

每一页的处理由 OMR 引擎中约 20 个步骤（step）组成，每个步骤都是作用于页 OMR 数据的"mini-batch"，是引擎能够执行的最小处理增量。这些步骤在源码中由枚举 OmrStep 完整定义，每个枚举值绑定一句描述与一个步骤实现类（如LoadStep、ScaleStep等），与文档给出的顺序、名称一一对应：

每页的步骤细节在文档的 explanation/steps 各专页中有独立说明（binary、scale、grid、headers、stems、beams、heads 等），第一次阅读时无需逐一深入，但建议记住这些信息存在，便于理解每一步的原理。

驱动流水线

在选中的页上，我们可以决定把流水线推进到某个目标步骤：在Step下拉菜单中选择目标步骤即可（下拉菜单Sheet → Transcribe等价于选择Step → PAGE）。注意流水线不能直接回退，但有两种间接做法：

• 选择已执行过的目标步骤：会先要求确认，然后把页数据重置到初始状态（优先灰度图，否则用二值图），再重新执行到目标步骤的所有必要步骤；
• 放弃并重新加载书籍：从之前保存的状态重新载入。

主功能二：Book parameters（书籍参数）

Book → Parameters下拉菜单打开参数对话框，用于审查和修改高层处理参数。对话框按作用域（scope）组织成若干选项卡：Default（所有书籍的全局默认值）、Book（当前书籍）、Sheet（具体页）。同一组参数在每个作用域都有定义，且默认沿层级继承：

1. Default：全局默认值，除非在 Default 层被覆盖，否则读取源码中的出厂值；
2. Book：可为本书覆盖任意默认值，并传递到本书所有页；
3. Sheet：可为具体页覆盖任意值。

覆盖操作方式是：选中作用域选项卡 → 勾选左侧复选框（行由灰变黑）→ 修改取值；取消勾选即恢复继承值。生命周期：所有修改只在按OK或Apply时提交；修改的 Default 值在应用多次运行之间持久保存（直到再次修改或重置），而 Book/Sheet 层的修改持久化在书籍的.omr项目文件中。

参数分组包括：

• General：
  • Music font：在Bravura、Leland、Primus、Finale Jazz、Jazz Perc之间选择音乐字体。该选择对符头识别尤为关键，因为符头识别基于字体模板匹配技术（详见 Music Font 一节）；
  • Input quality：按输入图像预期质量在synthetic、standard、poor之间调整 OCR 引擎行为。
• OCR languages：指定 OCR 文本的强势语言，可多选（见下文"OCR 语言"一节）。
• Binarization（仅在启用SPECIFIC_ITEMS高级主题后显示）：选择global或adaptive滤波器及相应数值。调整global阈值很简单，但不建议修改adaptive参数——默认 adaptive 滤波器在所有情况下表现良好，global仅保留给特定场景。
• Scaling specifications：
  • Interline（像素数）：仅当声明了单行谱（1-line staves）时出现——此时引擎无从测量行距，必须人工给定；
  • Barline height（four/twoThenFour/two/oneThenTwo）：单行谱小节线的典型高度（以行距计），如twoThenFour表示谱表左侧第一根小节线为 2 行距、其后为 4 行距；
  • Beam thickness（像素数）：始终存在，在页中连线太少、引擎无法可靠测量时特别有用。
• Staves：声明谱表构成——是否含 1 行打击乐谱表、4 行贝斯 Tab、5 行标准谱表、5 行无音高打击乐谱表、6 行吉他 Tab。
• Items：逐项开关控制引擎处理或忽略的对象（小符头、小连线、十字符头、颤音、指法数字、把位罗马数字、拨弦标记 p/i/m/a、部分全休止符、多全音符头、和弦名、歌词（含谱表上方歌词）、表情记号、谱表上/下方的力度记号等）。注意：某些少见特性的支持可能带来副作用（小符头是典型例子），建议仅在确实需要时开启。开关只能禁用 OMR 自动识别，大多数情况下该特性仍保留给用户手动操作。
• Processing：保留加载的灰度图、使用系统缩进、将增时点同时链接到共享符头、接受未连接的抱线分部（5.10 起，放宽内部小节线连接要求）、支持隐式连音组（implicit tuplets）。

主功能三：OCR 语言

Audiveris 把文本识别委托给 Tesseract OCR 库。Tesseract 理论上支持上百种语言，但一种语言要真正被支持，须满足两点：

1. 该语言的专用数据文件（含训练材料、词典等，即*.traineddata）已安装在本地；
2. 该语言被指定为默认、书籍级或页级语言。

例如处理一份英语（代码eng）乐谱，须先安装eng.traineddata，再对输入乐谱指定eng。

无预装语言：自 5.4 起各平台新版安装程序均不预装语言（5.4 之前仅旧的 Windows 无 JRE 安装包预装英语）。启动时 Audiveris 会检查已安装语言列表，若为空则弹出警告对话框：可以立即安装语言，也可以推迟——期间仍处理输入乐谱，只是TEXTS步骤会被忽略。

安装语言：首选方式是通过Tools → Languages菜单交互式安装（需要联网）。对话框逐行列出 GitHub Tesseract 站点上 100+ 语言：语言代码在左（通常 3 字母）、完整名称在右、中间复选框表示本地是否已安装；灰色代码行可忽略。勾选某行即下载对应数据文件到本地目录，完成后复选框自动更新。

本地tessdata目录：启动时 Audiveris 按以下优先级初始化 Tesseract 的tessdata目录：

1. 若环境变量TESSDATA_PREFIX已定义且指向有效目录，则使用它（设置该变量不是必须的，只是便于复用已有配置）；
2. 否则，在操作系统相关的 Audiveris 用户配置目录下查找（或按需创建）名为tessdata的目录。该目录必须可写才能真正安装语言。

Help → About对话框会显示 OCR 引擎版本与本地 tessdata 目录的关键信息。

运行时语言指定：语言规格是加号分隔的语言代码列表，如fra+eng+ita：

• 交互方式：通过Book parameters菜单在全局、书籍、单页三个层级指定；
• 默认（全局）规格由应用常量org.audiveris.omr.text.Language.defaultSpecification决定，初值为eng。可通过Tools → Constants交互修改，或批处理中用命令行常量覆盖，例如：

audiveris -batch -constant org.audiveris.omr.text.Language.defaultSpecification=ita+eng foo.omr

注意：给一本书或一页指定过多语言会拖慢识别速度并可能增加误识别，应尽可能精确。常见的手动下载语言包的坑包括：混淆 Tesseract 程序与库、误下 LSTM 模型而非 Audiveris 需要的 legacy 模型、语言文件版本（4.x）、TESSDATA_PREFIX环境变量指向错误。

主功能四：Preferences（偏好设置）

Tools → Preferences打开偏好对话框，处理若干用户偏好，层级高于直接修改应用常量：

• 标准处理选项：
  • SWAPPED_SHEETS：页处理完成后是否写盘并从内存移除，处理多页书籍时可在不显著影响总时长的情况下压低内存占用。默认开启；
  • PARALLEL_SYSTEMS：是否并行处理页内所有系统，仅对 20 步中有意义的 13 步生效，整体转录耗时大约节省 25%；缺点是结果不严格可复现（各系统竞争分配和命名 Inter 等实体）。默认关闭；
  • MULTIPLE_DELETE：是否允许用户在不确认的情况下批量删除多个 Inter。默认关闭。
• Early steps：定义打开输入文件后自动触发到哪个步骤。
• Default plugin：在已声明插件中交互式选择新的默认插件（默认取第一个声明的插件，见 Plugins 一节）。
• Output folder：
  • Input sibling：勾选后所有输出存入与输入文件相同的文件夹（除非命令行指定了-output）；
  • Browse：定义默认输出文件夹；
  • Separate folders：勾选后某输入文件的所有输出存入以其文件名（去扩展名）创建的独立文件夹。
• Global font ratio：滑块调整全应用视图的字体放大比例，下次重启生效。
• Locale：选择界面语言，当前可用en（默认）与fr（尚未完全实现），重启后生效。
• 高级选项（影响界面、需重启应用生效）：CUSTOM_SHAPE_SET（5.11 新增，用户自定义形状集）、SAMPLES（样本库与分类器训练）、ANNOTATIONS（符号标注生产）、PLOTS（scale/stem/staff/header 投影图的显示）、SPECIFIC_VIEWS（专用页标签，如 staff free、谱线字形）、SPECIFIC_ITEMS（视图中特定对象显示，如 attachments、字形轴）、DEBUG（大量调试功能，包括浏览书籍内部层级）。

主功能五：Sheet scale（页尺度与连线粗细）

GRID、BEAMS、STEMS等步骤的行为高度依赖SCALE步骤（谱线粗细、行距、小行距、连线粗细、小连线粗细）与STEM_SEEDS步骤（符干粗细）估计出的尺度数据的准确性。尺度数据由垂直游程长度（vertical run lengths）直方图推断：

• 组合直方图关注黑色游程与其后白色游程的组合长度，用于测量谱行距（interline）；
• 黑色直方图关注垂直黑色游程长度：主峰对应典型谱线粗细（例如 3 像素）；若页中包含大量连线，可观察到第二峰，对应典型连线粗细（例如 12 像素）。

问题场景：当页中只有极少数连线时，它们对全局黑色直方图的贡献可能太低，无法形成可靠峰。此时引擎可能选错连线峰、甚至检测不到峰而只能"猜测"连线粗细（例如取谱行距的 1/2）。粗细估计不准，连线就很难被正确检测与处理。

事后手动修正：在SCALE之后、BEAMS之前，可用Sheet → Scaling菜单修改引擎算出的连线粗细。初始所有行呈灰色（右侧显示已有数据值）；勾选某行左侧复选框（行变黑）后即可修改数值；取消勾选恢复初始值；按OK提交并关闭。缺点是：每次该页处理从零重启时修正会丢失、且可能要对书中每页逐一修正。

预先指定（推荐）：在Book parameters对话框中为整本书（Book 选项卡）或单页（Sheet 选项卡）预先给出连线粗细（像素数）。取值0表示"无指定"，可用于书籍级和页级。优点是：整书与单页均可设置；规格保存在.omr项目文件中，任何重载或从头重跑都不丢失。缺点是它只是"规格"，须由后续（或重跑的）SCALE步骤真正应用。

批处理模式下，对全新输入可在命令行携带该规格，例如：

audiveris -batch -transcribe \ -constant org.audiveris.omr.sheet.Scale.defaultBeamSpecification=10 \ my-score.pdf

注意：与交互模式不同，批处理规格不会存入书籍项目文件；且该规格作用于当前命令行处理的所有书籍。这也是为什么Book parameters对话框的Default选项卡里没有连线粗细规格——否则这条硬编码像素值将从此对以后处理的所有书籍生效。

主功能六：Book portions（书籍组合、拆分与合并）

单张图片乐谱只是"一本书、一页"的特例。面对数十甚至数百张乐谱图像，更灵活的处理方式包括：

• 扫描出多张独立图片、分属同一乐章——需要某种方式把它们汇合，最终导出为一份 MusicXML；
• 单一巨大输入文件——希望分块、按自己节奏处理，并可选择导出全部或仅其中一部分；
• 一本长书已转录纠错大半，却发现某页图像需要预处理甚至重新扫描——希望插入或替换若干页，同时保持其他页（尤其已转录的页）完好。

为此 Audiveris 已脱离最初的"一个输入文件—一本书"模式（详见 Book portions 章节）。核心是Split and merge功能，被称为 Audiveris 的"瑞士军刀"：

• 概念：PlayList 是依次处理的摘录（excerpt）序列；每个 Excerpt 表示某 Container 中页的选择；Container 是文件，即书籍文件（.omr）或图像输入文件。PlayList 可通过交互式Split and merge对话框定义，也可用纯文本编辑器手写（支持保存/重新载入），最终用于交互式或批处理构建复合书籍（compound book）；
• 典型用例：四手联弹乐谱（奇数页 Secondo、偶数页 Primo，可拆成两本复合书分别导出）、扫描分页图像按序合并为"图像复合书"、多本 1 页书合并为"书籍复合书"，或在同一 PlayList 中混用书籍与图像引用形成"混合复合"。所有情形下，引擎会在构建结果乐谱前更新所需页并处理跨页依赖（连音线、拍号、小节 ID）。
• 命令行入口：-playlist <file.xml>。批处理模式下，加载的播放列表直接用于构建复合书籍；交互模式下则仅用于填充Split and merge对话框供审查/编辑后再构建。

用户编辑（User editing）

OMR 转录过程中，由于图像质量差、乐谱过于密集等原因，总有元素无法被正确识别。Audiveris 持续改进 OMR 引擎，但对许多实例而言完全零错误的转录仍难以企及，因此全局更高效的做法是用一个顺手的图形编辑器配合 OMR 引擎，让最终用户轻松修正大多数 OMR 错误。5.1 版本只提供了限定于固定尺寸符号拖放的初级编辑器，5.2 版本则加入了一个可修改几乎任何类型符号的综合编辑器。

Audiveris 编辑器不试图与 MuseScore、Finale、Sibelius 这类音乐编辑器竞争——那些是面向作曲家、编曲者与出版商的高层工具，用于创作、编排、移调。Audiveris 聚焦 OMR 过程本身：把既有乐谱图像转写为其符号表示，并尽量贴近原始版面（包括图像的倾斜与扭曲）。

学习编辑器的最佳路径：先读Foundations（可编辑的 OMR 数据、如何选取与检查），然后直接练习Examples（在代表性输入乐谱上的完整编辑会话），再按需回到Tools查阅具体工具。

与 OMR 引擎的交互模型

引擎按 20 步流水工作，用户只能在步骤末尾介入（页的 Data 标签首次出现时，引擎已完成LOAD与BINARY）。任何用户手动操作之后，OMR 数据会按受影响步骤即时更新，页视图随之刷新，并实时标注引擎检测到的"异常"：

• 黑色符头附近没有兼容符干（或符干没有关联符头）会显示为红色——这在逐个手动创建/编辑对象时可能暂时出现；
• 整个小节背景可能变粉色，提示节奏问题。

任务序列与撤销/重做

任何实体修改都被记录为一个（可能含多个联合任务的）任务序列（task sequence），再施加到目标实体上。任务序列可以很大：例如选中十几个 Inter 一次性整组删除；删除一个 inter 合奏体（ensemble）会级联删除其全部成员（句子中的词、和弦中的符头等）；删除合奏体最后一个成员也会移除空合奏体。

任务序列不可分割，但可以任意do / undo / redo，无次数限制。只有把引擎从一个步骤推进（或伪回退）到另一步骤才会清空用户任务历史。

• Undo：取消上一个任务序列（无论是 do 还是 redo）及其全部后果。工具栏 Undo 按钮，或Ctrl+Z（macOS 为Command+Z）；
• Redo：重新执行上一个被撤销的任务序列。工具栏 Redo 按钮，或Ctrl+Shift+Z（macOS 为Command+Shift+Z）。

何时介入最有效

大多数用户纠错可以在页转录完成时（流水线终点PAGE步骤）进行；但某些纠错在更早时机更有效。按时间顺序，值得停留的干预点：

• SCALE：若提示连线粗细值只是"extrapolated"（外推），说明连线数据未达到推断可靠粗细所需的法定数量（quorum）——此时应自己测量实际连线粗细（用 Pixel Board）并按 Sheet scale 一节修正；
• GRID：谱线、谱表、系统在此识别，是手动修改线条与谱表（Staff editing）最方便的时点；
• REDUCTION：所有候选符头与候选符干、连线在此组合并归约为"可靠音符"（尚不含符旗与休止符，那些在后面的SYMBOLS处理）。这是流水线的关键时刻——这些"可靠"音符不会在此后步骤中被推翻，其底层像素也不会再提交给SYMBOLS步骤的字形分类器。所以若其中有误检，在REDUCTION末尾立即修正远比后面补救高效；
• TEXTS：提取所有文本项并分配角色（标题、分部名、歌词等）。该步骤输出高度依赖外部程序 Tesseract OCR，引擎难以判定某项究竟是不是文本、还是也可能是一个音乐符号。在TEXTS末尾手动删除文本误检，能让这些像素重新被SYMBOLS步骤利用；
• PAGE：引擎在页上的终点，观察与修正最终结果。

特定功能（Specific features）

该章节面向最终用户，汇集值得单独描述的特性，一般为新特性、按时间倒序排列。当前包含：

• bar_repeat.md：小节反复记号；
• drums.md：打击乐（鼓）支持；
• fingering_plucking.md：指法数字与拨弦标记；
• fonts.md：音乐字体（Bravura、Leland、Primus、Finale Jazz、Jazz Perc 等模板匹配原理）；
• logical_parts.md：逻辑分部编辑；
• metronome.md：速度标记（Metronome）；
• multi_rest.md：多小节休止符；
• octave_shift.md：八度移位记号；
• snippets.md：乐句片段；
• tablature.md：拨弦乐器谱表（Tablature，4 行贝斯 / 6 行吉他）；
• tremolo.md：颤音。

这些功能大多可与Book parameters → Items中的相应开关联动：开关控制 OMR 自动识别，而手动添加能力通常仍然保留。

高级功能一：命令行接口（CLI）

语法

任何以@开头的参数被视为文本文件名，其内容就地展开（每行一个参数）。带-help参数时显示的 CLI 语法如下：

Syntax: audiveris [OPTIONS] [--] [INPUT_FILES] @file: Content of file to be extended in line Options: -batch : Run with no graphic user interface -constant key=value : Define an application constant -export : Export MusicXML -force : Force step/transcribe re-processing -help : Display general help then stop -output <output-folder> : Define base output folder -playlist <file.xml> : Build a compound book from playlist -print : Print out book -save : In batch, save book on every successful step -sheets int[] : Select sheet numbers and ranges (1 4-5) -step <step> : Define a specific target step -swap : Swap out every sheet after its processing -transcribe : Transcribe whole book -upgrade : Upgrade whole book file -version : Display version then stop -run <qualified-class-name> : (advanced) Run provided class on valid sheets -sample : (advanced) Sample all book symbols -annotate : (advanced) Annotate all book symbols Input file extensions: .omr : book file (input/output) [any other] : image file (input) Sheet steps are in order: LOAD, BINARY, SCALE, GRID, HEADERS, STEM_SEEDS, BEAMS, LEDGERS, HEADS, STEMS, REDUCTION, CUE_BEAMS, TEXTS, MEASURES, CHORDS, CURVES, SYMBOLS, LINKS, RHYTHMS, PAGE

这些选项在源码 CLI.java 中以 args4j 的@Option注解声明（-batch、-constant、-export、-force、-output、-playlist、-print、-save、-sheets、-step、-swap、-transcribe、-upgrade、-version、-run、-sample、-annotate均可在源码中逐一对应），--由StopOptionHandler处理。

标准参数详解

• -batch：不带图形用户界面启动；
• -constant KEY=VALUE：指定一个应用常量的值。KEY 为常量的完全限定名，VALUE 为要赋的值。这是 GUI 菜单Tools → Constants的 CLI 等价物（旧名-option仍被支持）；
• -export：把每本书的音乐导出为 MusicXML 文件；
• -force：即使目标步骤已达到也强制重新处理。仅在指定了目标步骤（-step）或存在-transcribe时生效；
• -help：打印参数摘要后退出；
• -output DIRNAME：定义输出文件（.omr、.mxl等）应存放的确切文件夹。不指定时按标准文件夹策略选择默认输出目录；
• -playlist FILE.XML：把给定.xml文件作为播放列表加载。批处理模式下直接用于构建复合书籍；交互模式下仅填充并显示Split and merge对话框，用户审查/编辑后可在期望位置启动复合书构建；
• -print：把每本书的音乐导出为 PDF 文件；
• -save：只要某页步骤成功处理，就立即把该书的 OMR 数据保存到.omr项目文件。仅在-batch模式下有效；
• -sheets N M X-Y：指定要处理的页 ID（从 1 起）。空格分隔的数字序列，X-Y表示 X 到 Y 的闭区间——注意X-Y是一个参数，-两侧不能有空格。若未指定任何页 ID，则所有（有效）页都受影响。注意页 ID 会作用于命令行上引用的所有书籍，因此通常建议一次只针对一本书使用页 ID；
• -step STEPNAME：指定页目标步骤。未显式给出页号时，对全部有效页生效。若某页已达到该步骤则不再处理；带-force时，该页会重置到BINARY并重新处理到目标步骤；
• -swap：每页处理完成后换出到磁盘，特别适合处理页很多的书籍；
• -transcribe：转录每本书；
• -upgrade：作用于旧版.omr书籍文件，按需升级书籍/页的内部数据；
• -version：打印程序版本并退出，输出形如：

Audiveris - Version: 5.10.0 - Commit: 7cd25598ed15dcf1fd041ab60c1e7543f55588d4 - OS: Windows 10 10.0 - Architecture: amd64 - Java VM: Java HotSpot(TM) 64-Bit Server VM (build 25+37-LTS-3491, mixed mode, sharing) - OCR Engine: Tesseract OCR, version 5.5.1

• --：分隔符。其后所有参数（即使以-开头）一律视为输入文件路径；
• FILENAME：输入文件路径。扩展名为.omr时是 Audiveris 项目文件（兼作输入/输出）；其他扩展名一律视为图像输入。

高级参数

• -run CLASS_NAME：在每一有效页上运行指定 Java 类。CLASS_NAME 必须是继承抽象类org.audiveris.omr.step.RunClass并重写其process()方法的完全限定类名：

public abstract class RunClass { protected Book book; protected SortedSet<Integer> sheetIds; public RunClass (Book book, SortedSet<Integer> sheetIds) { this.book = book; this.sheetIds = sheetIds; } /** The processing to be done. */ public abstract void process (); }

• -sample：用由书籍Inter实例派生的样本填充每本书的样本库。书籍级仓库之后可合并入 Audiveris 全局样本库，为字形分类器（Glyph classifier）训练做准备（详见 Training）；
• -annotate：为每本书生成一个 Zip 归档，内含由Inter实例派生的图像与符号标注，用于构建训练潜在全局分类器的数据集。

高级功能二：扫描纸质乐谱的建议

Audiveris 不支持直接扫描（Java 项目尚缺少跨平台访问扫描设备的开源方案），需要借助外部扫描工具——各主流扫描仪厂商与三大操作系统均有免费可用的扫描软件。为音乐识别而扫描时应注意：

• 优先灰度图，而非黑白或彩色图：可避免扫描软件对符号的意外扭曲；Audiveris 会用自己的自适应算法自行二值化；
• 分辨率：低于 200 DPI 可能丢失关键细节，高于 500 DPI 则白白浪费 CPU 与内存且对识别无益。经验法则是300 DPI适合 A4 / US Letter 标准纸张；符号很小的乐谱提高到 400 DPI。更好的准则是：让扫描结果中两条谱线的垂直距离约为 20 像素；
• 纸张摆放要仔细，避免旋转、扭曲、阴影与深色竖条。Audiveris 通常会检测旋转/扭曲，但为保持图像质量完好，从不做图形校正——扭曲的谱线被原样保留，并作为符号处理的局部参照；
• 关闭扫描软件中的任何后处理："Line Art"、"Text"、"Dithering"、"Halftone" 等特殊设置常导致图像扭曲。低质量图像的增强应改用专用图像处理软件（见 Improved Input）。

高级功能三：应用常量（Constants）

Audiveris 代码中（原则上）不存在硬编码常量：所有算法背后是"应用常量"（当前已超过 800 个）。这是处理几乎全部应用调谐数据的底层而强大的机制。这些数据以常量形式呈现给最终用户，且可在运行时修改：

• CLI 的-constant KEY=VALUE参数；
• GUI 的Tools → Constants下拉菜单。

Constants 视图左侧是类树，右侧是包含类的常量详情表（可显示与修改）；顶部Search区可按类名、常量名、常量描述做不区分大小写的搜索。例如想放宽变音记号（如升号）与其右侧符头之间的水平距离约束，搜索accid可找到org.audiveris.omr.sig.relation.AlterHeadRelation类的xOutGapMax（供 OMR 引擎用）与xOutGapMaxManual（供手动指派用）——后者阈值更大，因为"用户坐在驾驶座上时可以放宽"。这些值以"行距分数"编码（如 2.0、3.0）以保持尺度无关；若有选中页，Pixels列会用该行距换算出对应像素数（如 42、63）。双击取值字段直接输入新值，立即生效。

常量生命周期（覆盖优先级从低到高）：

1. FACTORY：源码中定义的出厂默认值；
2. USER：修改后的值（若有），持久化在用户配置目录下的run.properties文件；
3. CLI：命令行-constant key=value指定的值（若有）。交互模式下 CLI 值会持久化到 USER 文件，批处理模式不持久化；
4. UI：通过Tools → Constants界面指定的值（若有），持久化到 USER 文件。

要放弃某常量的修改回到出厂值，取消该常量Modif列的勾选即可；要全部常量恢复出厂值，用 Constants 窗口顶部的Reset按钮。

高级功能四：Plugins（外部程序集成）

几乎任何音乐记谱程序都能导入 Audiveris 导出的 MusicXML。标准手工流程是：转录书籍（如需要）→ 导出 MusicXML → 启动外部程序 → 在外部程序中导入 MusicXML → 导航到导出文件位置。这一序列可通过插件自动化。

使用：配置好插件后，在下拉Plugins菜单中选择目标程序即可调用；默认插件可直接按工具栏插件图标触发。两种方式下，Audiveris 都会确保书籍已转录、MusicXML 导出文件存在且与用户最近的手动修改保持同步，最后以导出文件路径作为导入参数启动外部程序。

配置：在 Audiveris 配置目录中创建一个名为plugins.xml的 XML 文件。启动时若找到该文件，则按文件内容生成Plugins菜单与工具栏按钮。每个plugin元素：属性id（必需，唯一名）、tip（可选，提示文字）、若干arg子元素（每个一个参数，其中至少一个arg必须为{}，运行时在此插入导出文件路径）。仓库内提供了示例配置 plugins.xml。文档给出的示例片段：

<?xml version="1.0" encoding="UTF-8"?> <plugins> <!-- MuseScore --> <plugin id="MuseScore" tip="Invoke MuseScore on score XML"> <arg>C:\Program Files\MuseScore 3\bin\MuseScore3.exe</arg> <arg>{}</arg> </plugin> <!-- Finale --> <plugin id="Finale" tip="Export to Finale"> <arg>C:\Program Files (x86)\Finale 2014\Finale.exe</arg> ... </plugin> </plugins>

高级功能五：Samples 与 Training

Samples与Training面向需要修改字形分类器底层神经网络行为的用户。典型闭环是：用 CLI 的-sample把书籍符号样本汇入样本库（书籍级仓库可合并入全局仓库），或在 样本库机制下交互式采样/标注，再执行分类器训练（-annotate可批量产出符号标注数据集）。这些功能的入口开关位于 Preferences 的SAMPLES与ANNOTATIONS高级主题中。

结语：沿着 How-to 章节的渐进路径

Audiveris 的 How-to 体系遵循一条清晰的渐进线：先理解 20 步 OMR 流水线（pipeline）及其干预点，再用Book parameters（book_parameters）、Sheet scaling（sheet_scale）、OCR 语言（languages）与偏好设置（preferences）调优引擎行为；随后通过用户编辑三板块——Foundations（选择与检查）、Tools（添加/编辑/删除 Inter 与 Relation 及专用工具）、Examples（完整编辑会话）——修正具体输出；最后借助 CLI（cli）、常量（constants）、插件（plugins）与书籍组合（split_merge）完成批处理、深度定制与外部程序集成。每一步的机制都能在 app/src/main/java 下的对应源码（如 OmrStep、CLI）中得到印证，读者可据此继续深入。

• 桌面应用
• 计算机视觉
• 图像处理
• OCR