Audiveris 用户配置目录解析：CONFIG_FOLDER、Tessdata 与 TRAIN_FOLDER 完全指南

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

Audiveris 光学音乐识别（OMR）引擎将用户级配置与只读程序资源严格分离：所有可以由使用者自行修改的参数、日志设置、插件定义与追加的 GUI 动作，都存放在一个随操作系统而异的CONFIG_FOLDER中；OCR 所需的 Tesseract 语言数据、以及用于覆盖默认分类模型的自定义训练材料，则分别位于tessdata与train子目录。本文基于 docs/_pages/reference/folders/essential.md 展开，结合 WellKnowns.java 等源码实现，完整梳理这些"essential folders"在 Windows / Linux / macOS / Flatpak 下的确切路径、每个配置文件的用途与写法，以及它们如何在运行时被 Audiveris 探测与加载。读完本文，你将能够精准定位、安全修改自己的 Audiveris 配置，并正确部署 OCR 语言包与自定义训练模型。

目录总览：三个核心目录的定位

从源码可以确认，这些目录位于程序的读写区（read-write area），与只读的RES_URI（程序内置资源）截然分开——这正是设计上允许高级用户自由增改的前提。

Config folder：四个核心配置文件

Audiveris 在CONFIG_FOLDER中按固定文件名查找以下配置文件：

原文强调：这些文件"可以由你创建或修改，前提是你是一名高级用户，并且清楚自己在做什么"。下面逐一展开每个文件的机制与实操要点。

run.properties：用户常量覆盖层

run.properties是 Audiveris 常量的用户级覆盖文件。在源码 ConstantManager.java 中可以看到其加载逻辑：

• 用户属性文件名硬编码为"run.properties"（USER_FILE_NAME）；
• 加载路径为WellKnowns.CONFIG_FOLDER.resolve(USER_FILE_NAME)，即它必须位于CONFIG_FOLDER根目录；
• 只写入 USER 属性文件，源码中的 SOURCE 默认值不会被改动；如果用户把某常量改回与源码默认值相同的值，该条目会从 USER 属性文件中剔除，保证文件里只保留用户真正的"增量修改"。

此外常量还支持CLI 命令行级覆盖（优先级高于用户文件）：在addConstant中会先检查Main.getCli().getConstants()，即-option <qualified.name=value>这类命令行参数会优先于run.properties生效。

logback.xml：日志行为配置

仓库在 app/res/logback.xml 中提供了内置的日志配置（随只读资源加载），同时还有 app/res/logback-elements.xml 作为可复用的配置片段。若用户在CONFIG_FOLDER放置同名logback.xml，即可覆盖内置日志级别、输出目标与格式。初始化时机在 WellKnowns.java：静态块中通过LogUtil.initialize(CONFIG_FOLDER, RES_URI)完成日志系统初始化，并随即创建LOG_FOLDER与TEMP_FOLDER（分别为CONFIG_FOLDER之外的log子目录及其temp子目录）。

plugins.xml：外部程序插件定义

plugins.xml的作用是把 Audiveris 产出的 MusicXML/Score XML 一键交接给外部程序（如 MuseScore、Finale、EasyABC、PriMus）。运行时，若在CONFIG_FOLDER中发现plugins.xml，Audiveris 会根据文件内容动态生成Plugins下拉菜单与插件工具栏按钮（参见 plugins 指南）。

仓库在 app/config-examples/plugins.xml 提供了完整示例，其结构要点如下：

• plugin元素的id属性（必填）：插件唯一名称；
• tip属性（可选）：用作鼠标悬停提示的描述；
• arg子元素（必填）：每个参数一个元素，至少有一个arg必须等于{}，表示运行时在此插入导出文件的路径。

典型配置（Windows 环境示例）：

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

虽然示例中的路径面向 Windows，但文件格式本身跨平台通用：把arg换成 Linux 下的可执行文件路径（如/usr/bin/musescore）即可。

user-actions.xml：追加 GUI 动作

user-actions.xml与程序内置的 app/res/system-actions.xml 扮演相似角色：后者定义用户界面中提供的各种动作及其在菜单中的分组，始终随程序加载；而前者若出现在用户CONFIG_FOLDER中，则定义额外的动作并插入到既有下拉菜单。仓库示例 app/config-examples/user-actions.xml 展示了动作的写法：

<?xml version="1.0" encoding="UTF-8"?> <actions> <action domain="DEBUG" section="50" class="org.audiveris.omr.ui.GuiActions" method="clearLog" button="javax.swing.JButton"/> <action domain="DEBUG" section="70" class="org.audiveris.omr.sheet.ui.BookActions" method="dumpEventServices"/> </actions>

每个action通过domain（菜单域）、section（在菜单中的序号）、class（承载动作的类）、method（要调用的方法）来定位并挂接；示例中的 DEBUG 域动作会出现在调试菜单相应位置。从 app/config-examples/README.md 可以确认：config-examples目录中的示例文件并非程序直接使用，用户需要把示例文件复制（同名、内容可定制）到自己的config目录后，才会在运行时被 Audiveris 探测到。

CONFIG_FOLDER 的精确位置：按操作系统解析

CONFIG_FOLDER的具体位置由 WellKnowns.getFolder(FolderKind.CONFIG) 依据当前平台计算，原文给出的完整对照如下：

源码中的计算逻辑与表格完全对应，并揭示了几个值得注意的实现细节：

• 路径前缀：TOOL_PREFIX = "/" + COMPANY_ID + "/" + TOOL_ID，即AudiverisLtd/audiveris（见 WellKnowns.java），各平台路径都是在此基础上拼出；
• Linux 双路径：优先尝试XDG_CONFIG_HOME环境变量（xdgProperty(CONFIG) = "XDG_CONFIG_HOME"）；未设置时回退到$HOME/.config；
• Flatpak 特例：当检测到FLATPAK_ID环境变量时，Linux 分支直接使用 XDG 变量本身（不加TOOL_PREFIX），因为 Flatpak 的XDG_CONFIG_HOME已被沙箱重定向到$HOME/.var/app/org.audiveris.audiveris/，故最终完整路径为$HOME/.var/app/org.audiveris.audiveris/config；
• Windows 特例：配置在%APPDATA%\AudiverisLtd\audiveris\config（audiverisPath.resolve("config")），而用户数据（DATA_FOLDER）则放在"我的文档"下的Audiveris目录，二者并不相同；
• 环境变量缺失保护：若所需环境变量（APPDATA、HOME等）未设置，getFolder会打印*** INIT_ERROR并返回null，避免静默使用错误路径。

需要说明的是：若你在 Linux 上为XDG_CONFIG_HOME设置了自定义路径，那么CONFIG_FOLDER就是$XDG_CONFIG_HOME/AudiverisLtd/audiveris（非 Flatpak 时始终追加TOOL_PREFIX）；Flatpak 沙箱内的 XDG 值已被框架改写，因此路径形态固定为表格中的形式。

Tessdata 文件夹：Tesseract 语言数据

自 Audiveris 5.4 版本起，Tesseract OCR 软件所需的语言文件托管在CONFIG_FOLDER的tessdata子目录中。交互式用户只需使用界面中的Languages下拉菜单即可自动填充该目录。

源码 TesseractOCR.java 给出了findOcrFolder()的完整探测顺序，这比文档描述更精确：

1. 优先使用TESSDATA_PREFIX环境变量：若该变量被设置且指向一个存在的目录，则直接采用（Paths.get(tessPrefix)）；
2. 其次使用 Audiveris 用户配置下的tessdata：即WellKnowns.CONFIG_FOLDER.resolve("tessdata")；若目录不存在，则尝试自动创建（Files.createDirectories）；
3. 两者都不可用时，记录ocrNotFoundMsg警告并返回null。

仓库内置的英文语言包位于 app/tessdata/eng.traineddata，属于只读资源；用户可自行向配置目录下的tessdata添加其他语言的*.traineddata文件（也可通过 Languages 菜单在线获取）。运行时getSupportedLanguages()会扫描该 OCR 目录下的语言文件，生成可用的语言集合。

Train 文件夹：自定义训练材料与模型

TRAIN_FOLDER用于存放用户自定义的训练材料与训练好的模型，以覆盖 Audiveris 默认的模型。它被定义为CONFIG_FOLDER的直接train子目录（WellKnowns.java），其包含的文件如下：

源码印证了这些文件的读取约定：

• 仓库内置的默认模型资源为 app/res/basic-classifier.zip，属于只读资源；用户把同名文件放入train目录即可覆盖默认模型；
• SampleRepository.java 中定义了samples.zip（SAMPLES_FILE_NAME）作为全局仓库文件名，其全局实例从WellKnowns.TRAIN_FOLDER.resolve("samples.zip")加载（见 SampleRepository.java）；同时，每个乐谱（Book）还可以有局部的BOOK_NAME-samples.zip仓库；
• images.zip（IMAGES_FILE_NAME，见 SampleRepository.java）存放训练样本对应的背景图像。

由此可推断：训练工作流的落地方式是——把训练产生的模型与样本归档为这三个 zip 文件，放入TRAIN_FOLDER，Audiveris 启动/初始化分类器与样本仓库时就会优先使用这些用户版本。更深入的自定义训练流程可参阅 训练指南 与 分类器相关说明。

实操速查：从示例到生效

综合上文，在任意平台上完成一次"自定义配置"的标准路径如下：

1. 定位CONFIG_FOLDER：按上表找到对应操作系统的配置目录（Linux 下可先执行echo $XDG_CONFIG_HOME确认是否设置，未设置则用$HOME/.config）；
2. 复制示例文件：把 app/config-examples/ 下需要的示例（如plugins.xml、user-actions.xml）复制到CONFIG_FOLDER，按需修改内容（插件路径、动作列表等）；
3. （可选）覆盖日志与常量：在CONFIG_FOLDER放置自定义logback.xml与run.properties；
4. （可选）部署 OCR 语言：通过界面 Languages 菜单填充CONFIG_FOLDER/tessdata，或手动放置*.traineddata；
5. （可选）覆盖训练模型：在CONFIG_FOLDER/train中放置basic-classifier.zip、samples.zip、images.zip；
6. 重启 Audiveris：这些文件均在启动阶段被探测与加载，修改后需重启生效。

注意：config-examples目录中的文件仅是模板，程序并不会直接读取它们（config-examples/README.md）；务必复制到用户配置目录后再编辑。若不确定某配置项的影响，请先备份原文件，因为文档与示例均明确提示：这些是高级用户才应触碰的设置。

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