edirom/meigarage

MEIGarage 技术文档

镜像概述和主要用途

MEIGarage 是一个 Web 服务和 RESTful 服务，专注于 MEI（音乐编码格式），提供多种格式的转换、转换和验证功能。该服务基于成熟的 https://github.com/TEIC/oxgarage 代码库构建，可视为音乐编码数据的“工作坊”。

运行中的 MEIGarage 实例可访问：meigarage.edirom.de。关于代码结构和演示材料，可参考 https://github.com/Edirom/MEIGarage/blob/main/doc/code-structure.md 和 https://anneferger.github.io/MEITEIGarage/%E3%80%82

核心功能和特性

• MEI 格式处理：支持 MEI 格式的转换（如 MEI 3.0 转 MEI 4.0）、验证及格式转换
• 多格式支持：基于 OxGarage 成熟架构，支持多种相关格式处理
• RESTful API：提供标准化 API 接口，便于集成到其他系统
• Open API 文档：内置 API 规范，可通过运行实例或源码访问
• 可定制化：支持挂载本地样式表和源文件，自定义转换规则

使用场景和适用范围

• 音乐编码领域：音乐学者、开发者处理 MEI 格式文档的转换与验证
• 集成场景：作为后端服务集成到音乐编辑工具、数字人文平台
• 教学与研究：MEI 格式学习和研究中的格式转换测试环境
• 自动化工作流：通过 API 实现 MEI 文档批量转换、版本升级等自动化任务

详细使用方法和配置说明

4.1 API 使用方法

Open API 文档

API 规范可通过以下途径获取：

• 源码路径：https://github.com/Edirom/MEIGarage/blob/main/src/main/webapp/openapi.json
• 运行实例：https://meigarage.edirom.de/ege-webservice/

API 调用示例

使用 curl 将 MEI 3.0 文档转换为 MEI 4.0 文档：

bash
curl -o 4.0.0.mei -F upload=@input-3.0.0.mei https://meigarage.edirom.de/ege-webservice/Conversions/mei30%3Atext%3Axml/mei40%3Atext%3Axml/

4.2 Docker 部署方案

前提条件

已安装 Docker 环境。

拉取镜像

可从 GitHub Docker Registry 或 DockerHub 获取镜像：

bash
# 从 GitHub Docker Registry 拉取
docker pull ghcr.io/edirom/meigarage:latest

# 或从 DockerHub 拉取
docker pull edirom/meigarage:latest

开发版本镜像：

bash
docker pull edirom/meigarage:dev

运行容器

基础运行命令（默认配置）：

bash
docker run --rm \
  -p 8080:8080 \
  --name meigarage \
  edirom/meigarage:latest

服务启动后，通过浏览器访问 http://localhost:8080/ege-webservice 进入 Web 服务界面。

高级配置

环境变量

• WEBSERVICE_URL：指定服务访问 URL，用于生成正确的 API 链接
  示例：-e WEBSERVICE_URL=http://localhost:8080/ege-webservice/

卷挂载（自定义样式表和源文件）

可挂载本地目录覆盖默认的样式表和源文件，映射关系如下表：

挂载示例：

bash
docker run --rm \
  -p 8080:8080 \
  -e WEBSERVICE_URL=http://localhost:8080/ege-webservice/ \
  -v /本地路径/tei/stylesheet:/usr/share/xml/tei/stylesheet \
  -v /本地路径/tei/odd:/usr/share/xml/tei/odd \
  -v /本地路径/mei/encoding-tools:/usr/share/xml/mei/music-stylesheets/encoding-tools \
  -v /本地路径/mei/musicxml:/usr/share/xml/mei/music-stylesheets/w3c-musicxml \
  -v /本地路径/mei/meiler:/usr/share/xml/mei/music-stylesheets/meiler \
  -v /本地路径/mei/music-encoding:/usr/share/xml/mei/music-encoding \
  -v /本地路径/mei/data-configuration:/usr/share/xml/mei/music-stylesheets/data-configuration \
  --name meigarage edirom/meigarage:latest

暴露端口

• 8080：HTTP 服务端口（默认使用）
• 8081：HTTPS 服务端口（用于 SSL 终止负载均衡器后端）

4.3 非 Docker 安装（简要说明）

1. 获取 WAR 包：从 https://github.com/Edirom/MEIGarage/releases 下载或本地构建
2. 部署到 Tomcat：将 WAR 包放入 Tomcat 的 webapps 目录
3. 配置文件：
   • 复制 oxgarage.properties 到 /etc/oxgarage.properties
   • 创建 /var/cache/oxgarage 目录并复制 log4j.xml，设置权限（如 chown -R tomcat:tomcat /var/cache/oxgarage）
4. 安装依赖：在 /usr/share/xml/tei 目录下部署 TEI 和 MEI 的样式表及源文件（遵循 Debian 文件层级标准）
5. 验证：访问 http://localhost:8080/ege-webclient/ 测试转换功能

Docker 镜像构建（高级）

如需自定义镜像版本，可通过 docker build 传入构建参数指定依赖版本：

bash
docker build \
  --build-arg VERSION_STYLESHEET=7.52.0 \    # TEI 样式表版本
  --build-arg VERSION_ODD=4.3.0 \            # TEI 源文件版本
  --build-arg VERSION_ENCODING_TOOLS=3.0.0 \ # MEI 编码工具版本
  --build-arg VERSION_W3C_MUSICXML=4.0 \     # MusicXML 版本
  --build-arg VERSION_MEILER=2.0.0 \         # MEILER 版本
  .

参考信息

徽章信息

• 构建状态：https://github.com/Edirom/MEIGarage/actions/workflows/maven_docker.yml/badge.svg](https://github.com/Edirom/MEIGarage/actions/workflows/maven_docker.yml)
• 许可证：
• Docker 拉取量：
• DOI：![DOI]([***]

致谢

NFDI4Culture 支持

MEIGarage 开发得到 NFDI4Culture（物质与非物质文化遗产研究数据联盟）支持。该联盟致力于为文化遗产研究数据建立需求导向的基础设施，涵盖建筑、艺术、音乐、戏剧等多个领域。更多信息：nfdi4culture.de。