音乐转 MIDI 转换器 (AI Audio to MIDI)

项目、工作流配置与跨会话续跑

更新说明

中文 | English

一个本地优先的 AI 音频转 MIDI / Audio to MIDI 转换器，面向编曲、扒谱、采样拆解、钢琴练习和自动音乐转写 (AMT) 实验。你可以把 MP3、WAV、FLAC、OGG 或 M4A 音频丢进来，在 PyQt6 桌面版、Gradio Web 版或 Google Colab 中生成可编辑的 MIDI 文件。

当前版本同步七种处理模式：完整混音多乐器转写、人声/伴奏 WAV 分离、六声部 WAV 分离，以及 TransKun 默认 V2 / TransKun V2 Aug / Aria-AMT / ByteDance Pedal 四条钢琴专用转写流程。两个分离模式会生成 WAV 分轨；分离完成后，每条音轨都可在同一结果工作台选择 13 条 MIDI 路线之一。多乐器 AMT、stem separation、钢琴转 MIDI 和 BPM/tempo 元数据都在这套工作流中处理。

桌面下载 MIDI 或立体声 WAV 失败时会显示原因并记录完整错误，当前转换结果仍可继续使用；修正路径、文件占用或权限问题后可以重试。日志位于 ~/.music-to-midi/logs/；便携版优先使用程序旁的 runtime/logs/。

在线工具与操作指南

如果想先试听模型效果或直接在浏览器处理文件，可以使用同一作者维护的 TelkNet。工具介绍、指南和演示可直接浏览；提交网站的服务器处理任务需要登录。

• 音频转 MIDI 指南：按完整混音、钢琴或人声选择路线，并检查转写后的音符。
• 六轨分离指南：分离人声、鼓、贝斯、吉他、钢琴和其他音轨，试听后导入 DAW。
• MIDI 文字乱码修复：在浏览器内修复歌词和轨道名称的编码，保留音符与节奏数据。

网站提供的模型和参数以对应工具页为准；本仓库的安装、桌面功能与本地模型配置仍按下文说明使用。

命令行与批处理

CLI 与独立 Web API 共用同一个 InferenceEngine 和核心流水线。最简单的调用只需要输入文件；输出默认放在项目或便携包旁的 MidiOutput/CLI：

# Windows 源码版；先运行一次 install.ps1，转换时检查所选路线的 GPU 与模型
.\cli.ps1 D:\Audio\song.wav

# Windows 便携包
.\MusicToMidiCLI.exe D:\Audio\song.wav

# 多文件或目录批处理（逐个转换）
.\MusicToMidiCLI.exe batch D:\Audio --recursive -o D:\MidiOutput

# Linux / WSL2 源码版
bash cli.sh /data/audio/song.wav

# Linux 便携包
./MusicToMidiCLI batch /data/audio --recursive -o /data/midi

常用示例：

# 指定钢琴模型
MusicToMidiCLI song.wav --mode piano-transkun-v2-aug

# SMART 改用 MuScriptor Medium，并指定输出乐器
MusicToMidiCLI song.wav --backend muscriptor --muscriptor-model medium --instrument acoustic_piano,voice

# 启用量化；省略 --quantize 时保持音符原始时间
MusicToMidiCLI song.wav --quantize 1/32

# 分离只生成 WAV
MusicToMidiCLI mix.flac --mode six-stem-split

# 对选中的单条 stem 转 MIDI；routes 可查看全部 13 条路线
MusicToMidiCLI routes
MusicToMidiCLI track-to-midi vocals.wav --route yourmt3:yptf_moe_multi_nops --tempo-source mix.flac

# 供脚本读取的 JSON Lines 事件流
MusicToMidiCLI batch /data/audio --recursive --json

每个输入使用独立且不覆盖的输出目录，并写入 music-to-midi-job.json；每次批处理另写 batch-run-*.json。默认会用源文件 SHA-256、完整参数和产物 SHA-256 校验已有成功项，全部吻合才跳过；--rerun 强制新建编号目录。出现失败时，默认继续处理其余独立文件但最终返回退出码 1，--fail-fast 可在首个失败后停止，Ctrl+C 返回 130，参数/输入错误返回 2。--dry-run 只列计划，不加载模型也不创建输出。

源码 CLI 启动器直接使用项目隔离环境（Windows NVIDIA 为 venv、Windows Intel 为 venv-xpu、Linux/WSL2 NVIDIA 为 venv），不会复用桌面 GUI 的全模型启动检查。因此 --help、--version、routes 和 --dry-run 可立即执行；转换时会检查所选路线的加速器、模型和产物。缺少隔离环境时会显示安装命令并退出。--json 模式的 stdout 只包含 JSON Lines，诊断与第三方日志写入 stderr。

VOCAL_SPLIT 与 SIX_STEM_SPLIT 先输出 WAV。CLI 不会自动把全部 stem 转成 MIDI；必须由用户对选中的音轨执行 track-to-midi --route ...。完整选项以 MusicToMidiCLI --help、MusicToMidiCLI convert --help 和 MusicToMidiCLI track-to-midi --help 为准。

对 CLI 分离任务生成的 WAV，track-to-midi 默认校验旁边的分离清单、WAV 和原曲 SHA-256，再用原曲检测 BPM；同批来自不同歌曲的 stem 会分别使用各自原曲。原曲丢失、清单损坏或音频被改动时会停止并说明原因；可用 --tempo-source 显式指定新的节拍参考。独立音频没有分离清单时使用自身检测节拍，--dry-run --json 会显示实际选用的参考路径。

递归扫描遇到不可读目录会直接报错。损坏的断点清单会报告并保留，只有通过校验的清单才能跳过转换；汇总文件写入失败会停止运行，并保留已提交的逐项结果。JSON 输出管道被接收端关闭时退出 1，错误写入 stderr。

独立 Web API 与浏览器前端

独立 Web API 与浏览器前端调用同一个 MusicToMidiPipeline，提供与桌面版一致的七种模式。Windows 发布版按用途提供三个目录：

源码环境只需在仓库根目录运行一条命令：

.\venv\Scripts\python.exe -m src.web

这个入口会自动识别服务电脑的主要局域网 IPv4，依次启动 WebBackend 和 WebFrontend，确认两端就绪后自动打开 Edge 应用窗口。终端会显示其他同一局域网电脑可访问的前端地址；按 Ctrl+C 或关闭 Edge 应用窗口会一并停止前后端。多网卡或 VPN 环境可用 --host 192.168.1.50 明确指定服务电脑的实际局域网 IPv4，完整用法见 web/README.md。

打包版的启动顺序如下：

1. WebBackend 包中的 MusicToMidiBackend.exe。
2. WebFrontend 包中的 MusicToMidiFrontend.exe。
3. 同机使用默认配置即可；局域网使用时，分别修改两个 EXE 旁边首次运行生成的 MusicToMidiBackend.json 与 MusicToMidiFrontend.json，再重启两个程序。
4. 在浏览器打开前端地址；后端健康检查为 http://<后端地址>:8765/api/v1/health，API 文档为 http://<后端地址>:8765/docs。

其他电脑只需要浏览器，不需要复制桌面 App 或 WebFrontend 包。完整的配置 JSON、防火墙命令、验证方法、停止方式以及前后端分机部署说明见 web/README.md。

浏览器前端通过 multipart 作业接口提交音频，查询 GET /api/v1/jobs/<job-id> 获取终态，并从响应中的 download_url 下载 MIDI 或分轨 WAV。失败响应包含处理错误，且不提供下载文件。

v1.6.0 已为 Issue #9 提供完整 Docker 自托管包，包括无外置模型的后端/网关镜像、digest 固定的 Compose、环境模板、Windows/Linux 管理脚本、镜像清单与 SHA-256。默认入口是 http://127.0.0.1:7860；模型按 .env 中选择的配置下载到持久卷，常驻推理容器离线运行。安装、配置、日志、备份、升级与故障排查见 Docker 自托管指南。

上面的源码/EXE 双端口方案面向受信任局域网，本身不内置认证、授权或 TLS；将 5173 或 8765 映射到互联网会形成无认证服务。公网单一所有者场景可以使用带自动 HTTPS 和 Argon2id Basic Auth 的高级 Compose；该方案不包含多租户、账号系统或逐任务授权。

界面演示

桌面版、Gradio Web 版和 Google Colab 采用同一套七模式工作流与操作语义。以下截图依次展示主界面、分离结果、逐轨处理和 MuScriptor 渐进式预览。

1. 主界面与完整混音转写

2. 六声部分离完成

3. 六声部波形与逐轨转 MIDI 控件

4. MuScriptor 边转写边预览 MIDI

适合场景

项目面向需要把人声旋律、钢琴录音、完整混音或分轨 stem 转成可编辑 MIDI 的用户，也可用于在本地 GPU 上验证自动音乐转写模型。

当前能力

不同入口的功能范围

入口与依赖同步状态

本仓库把“处理工作流”和“YourMT3+ 官方 checkpoint 模式”分开维护：

• SMART、VOCAL_SPLIT、SIX_STEM_SPLIT、PIANO_TRANSKUN、PIANO_TRANSKUN_V2_AUG、PIANO_ARIA_AMT、PIANO_BYTEDANCE_PEDAL 是本项目的七种处理工作流。
• YMT3+、YPTF+Single (noPS)、YPTF+Multi (PS)、YPTF.MoE+Multi (noPS)、YPTF.MoE+Multi (PS) 是官方 YourMT3 demo 暴露的五种 checkpoint / 架构模式。
• 桌面版、Gradio Space 和 Colab 都暴露同一组七种处理工作流；SMART 可选 YourMT3+、MIROS 或 MuScriptor Large / Medium / Small，两个分离工作流先输出 WAV，再为每条音轨独立提供 13 条 MIDI 路线。

当前同步覆盖如下：

处理模式

输出文件

桌面版默认输出到：

MidiOutput/<音频文件名>/

如果同名目录已存在，会自动使用 <音频文件名>_2、<音频文件名>_3 等后缀。

常见输出：

song.mid
song_accompaniment.mid
song_vocal.mid
song_vocal_accompaniment_merged.mid
song_bass.mid
song_drums.mid
song_guitar.mid
song_piano.mid
song_vocals.mid
song_other.mid
song_all_stems_merged.mid
song_piano_transkun.mid
song_piano_transkun_v2_aug.mid
song_piano_aria.mid
song_piano_bytedance_pedal.mid
song_accompaniment.wav
song_bass.wav
song_drums.wav
song_guitar.wav
song_piano.wav
song_vocals.wav
song_other.wav

实际文件数量取决于所选模式和用户主动执行的逐轨转换。人声分离主流程产生规范的 <歌曲名>_vocals.wav 与 <歌曲名>_accompaniment.wav；六声部流程的成功结果包含六条 WAV。任一分离输出缺失时流程会报告失败；MIDI 按用户开始转换的音轨单独生成。乐谱不会在转写时自动阻塞生成；用户对任一 MIDI 点击“生成并下载乐谱”后，才创建与该 MIDI 对应的 ZIP。

后端说明

YourMT3+

YourMT3+ 是默认多乐器后端。download_sota_models.py 准备完整公开工作流资源：Beat This final0、全部五种官方 YourMT3+ checkpoint、固定 MIROS 源码与两组权重、BS-Rofo-SW-Fixed.ckpt、Leap XE、Leap Instrumental、TransKun V2 Aug、Aria-AMT 和 ByteDance，并严格验证默认 TransKun 2.0.1 包及其内置 V2 资源；YourMT3 推理通过 src/core/yourmt3_transcriber.py 调用仓库内受控的 YourMT3/amt/src 源码。

源码运行依赖以下文件：

YourMT3/amt/src/model/ymt3.py
YourMT3/amt/src/utils/task_manager.py
YourMT3/amt/src/config/config.py

完整项目 checkout 已包含经过兼容补丁并由固定 manifest 校验的 YourMT3/amt/src。该目录缺失时，受支持的恢复来源是当前项目版本中的受控源码；可变的上游 master 只适合独立实验，不满足本项目三端源码一致性和便携构建身份契约。

模型权重下载：

以下源码维护命令以仓库内 venv 为运行环境；未激活时，Windows 的完整解释器路径是 .\venv\Scripts\python.exe / .\venv\Scripts\hf.exe，Linux/WSL2 为 ./venv/bin/python / ./venv/bin/hf。全局 Python 不属于受支持的源码运行环境。

python download_sota_models.py

默认搜索模型位置包括：

~/.cache/music_ai_models/yourmt3_all
runtime/models/yourmt3_all          # 便携版
models/yourmt3_all                  # 打包资源

MuScriptor Large / Medium / Small

运行日志现记录官方 MIDI writer 实际采用的 onset 校正、小节偏移及两者合成的净时间偏移；写出前保持“待计算”，不再误报为禁用校正或零偏移。此修复不改变 MIDI 字节，不增加模型推理或音符分析次数。后台实测与发布前检查见时间轴核验。

项目严格固定上游官方 v0.3.0 提交 d73147e75e5b9b0c0a79ebe154587db4fd603e0c， 并对七个运行时源码文件执行 SHA-256 身份校验，不叠加未合并分支。全项目唯一的 Beat This final0 分析会把完整拍点、BPM、可靠拍号和首个强拍直接传给 v0.3.0 BeatGrid：官方 onset 相位估计在满足样本数与集中度阈值时校正系统性起音偏移，不满足阈值时明确记录 0 校正；项目不再启动第二套节拍检测，也不接受占位 120 BPM。写出的 MIDI 包含真实 tempo、拍号、小节相位和可验证的前置偏移标记；tempo 归一化后还会严格复制到每个含音符轨， 兼容 MuseScore 的 conductor-track 行为。桌面、Space 和 Colab 的 MuScriptor 钢琴卷帘使用同一 Beat This 网格显示拍线、强拍线和交替小节底色。 该偏移标记在手动 BPM 变速时按相同比例变化，最终试听的原音也补入同等静音，因此 MIDI、钢琴卷帘、原音和下载文件使用同一时间轴， 不量化、不过滤、不重跑模型。三档 gated 权重分别固定为 MuScriptor/muscriptor-large revision 8809fdfbed2affa7ade94a7059e746e3880720e7、 MuScriptor/muscriptor-medium revision f32236969308476e01fd3aae67357de5feb05a2d 和 MuScriptor/muscriptor-small revision 8c127f603b807520fa465c838e9bfee8a91ada4e。三者均为 CC BY-NC 4.0，并附额外合法使用条件。

三个仓库的有效授权条件是：同一个 Hugging Face 账户已在浏览器中逐项接受条款，随后由该账户登录 CLI。hf auth login 本身不能替用户接受网页条款，源码安装、Colab 和自行部署 Space 也不能匿名全自动下载这些权重：

hf auth login
python download_muscriptor_model.py --size all

三档由用户选择；所选模型无法运行时，任务会显示错误。Large 质量优先，Medium 是速度/质量折中，Small 参数量最少；三档均严格使用官方 5 秒窗口、prelude forcing 和单次生成路径，所选模型不变。桌面端的运行条件包含所选 checkpoint；Space 与 Colab 会按当前选择准备对应固定 revision。

Windows 结果工作台还需要固定 FluidSynth 2.5.6；安装脚本会准备，也可单独运行：

python download_fluidsynth_runtime.py
python download_musescore_runtime.py

界面和官方公开演示保持同一功能语义：可搜索的标签多选与清除、空选自动检测、 实时转写进度/音符、以 MIDI 为主时钟的可拖动播放进度条、钢琴卷帘、默认全部轨道的量化范围与五档显式量化网格、播放/暂停、跟随播放头、原音↔MIDI 混合、Stereo、 逐乐器静音/多选独奏，以及 MIDI、乐谱 ZIP、合成 WAV、原音左声道/MIDI 右声道立体声下载。 新结果默认全部声部可见、可听；独奏可同时选中多个声部，取消独奏后保留各声部原来的静音设置。 MIDI 下载提供全部声部合并、当前可听声部合并、全部声部分别打包 ZIP 三个选项，均使用当前编辑结果和工程 BPM；ZIP 不受静音/独奏影响。 在编辑器内按空格播放/暂停，Shift+空格或“停止并回到开头”重置播放位置；输入文字或数值时不拦截空格。 桌面钢琴卷帘使用与 TelkNet 默认工具一致的 ChordMini BTC，从原始音频识别和弦。和弦与小节网格共用时间轴，支持点击单独试听，播放跟随、缩放和滚动均随卷帘逐帧同步，并同步 MuScriptor 的开头小节偏移。更改工程 BPM 后仍与音符、小节对齐；编辑 MIDI 不改写原音和弦。首次运行前执行 python download_chordmini_model.py（完整准备命令也包含它），便携包内置固定源码和权重。 和弦按根音配色，当前片段随播放头高亮；短片段使用完整标签和引线，密集标签自动错行，保留真实起止时间。桌面、Space 和 Colab 的 MIDI 音符也支持当前位置高亮及悬停反馈，可查看音高、声部、力度和起止时间；静音声部不显示播放高亮，编辑选区保持独立。 桌面和弦栏旁提供“和弦随曲播放”和独立的 0～200% 音量。首次使用默认关闭随播、音量 100%；关闭随播仍可点击和弦单独试听，0% 则使两种试听都静音。开关与音量会记住上次设置。和弦与歌曲共用音频时钟，支持暂停、跳转、工程 BPM 和倍速；按识别的原始区间发声，不因小节分块重复敲响，N/X 区间保持静音。音量经过响度校准、平滑调节和峰值保护，仅用于试听，不写入 MIDI 或音频导出。便携 App 和可执行 App 共用此实现；Space/Colab 与独立 Web/API、Docker、便携 Web 目前不提供和弦栏。 独立 Web/API、Docker 和便携 Web 的 MIDI 结果提供逐声部 MIDI ZIP 下载。详细交互、导出保留项与交付面范围见结果编辑器说明。 试听音频的来源：逐乐器播放来自最终 MIDI 经官方 MuseScore General SoundFont 与 FluidSynth 合成，不是无效按钮或 UI 模拟。

模型身份、公开分数与评价

MuScriptor 是 Kyutai、Mirelo AI 与 IRCAM 研究人员在 2026 年 7 月公开的完整混音多乐器 AMT 模型。Large 使用 decoder-only Transformer（48 层、隐藏维度 1536；官方模型卡写约 1.3B 参数，代码 README 四舍五入为 1.4B），以 5 秒、16 kHz 单声道音频分片生成 MT3 风格音符事件。训练链路包含约 145 万 MIDI 的合成预训练、17 万首/约 11,000 小时真实音乐微调和 300 首高质量转写的强化学习后训练。

官方模型卡在作者保留的 372 首真实多乐器 D_Test 上报告如下结果（完整训练链路，CFG=2）：

这些分数表明 MuScriptor Large 是很强的公开完整混音候选，但不是“所有 benchmark 的无条件 SOTA”：D_Test 是作者自建留出集，尚无公共下载入口；在论文列出的 8 个公共跨域数据集上，MuScriptor 的 Multi F1 高于 YourMT3+ 其中 6 个、低于其中 2 个。它也不输出 velocity，只提供 36 组乐器分类，并受 CC BY-NC 4.0 非商用许可约束。

发布时间也应分开理解：Hugging Face API 记录模型仓库创建于 2026-06-30；论文与 Mirelo 官方文章发表于 2026-07-09；当前公开权重 revision 更新于 2026-07-10，而本项目固定的官方 MuScriptor v0.3.0 源码发布于 2026-08-05。仓库与源码发布日期不等于权重被重新训练；三个公开模型 revision 仍按各自 SHA 精确固定。

完整训练消融、8 个公共数据集逐项分数、模型规模对比、乐器条件收益、Mirelo Studio 私有增强版边界与后续模型观察清单见 MuScriptor 模型研究、分数与项目定位。

MIROS

MIROS 是桌面版、Space 与 Colab 中 SMART、VOCAL_SPLIT、SIX_STEM_SPLIT 三个模式的可选固定版本多乐器后端，对齐项目锁定的 MusicFM / AI4Musician Challenge SOTA 路线。运行资产包括经过身份校验的本地上游仓库与权重；包装器调用固定入口生成临时 MIDI，再转换为项目统一音符结构。

支持路径：

ai4m-miros/
external/ai4m-miros/
MIROS/
external/MIROS/

包装器会检查：

main.py
transcribe.py
model/musicfm/data/pretrained_msd.pt
logs/Multi_longer_seq_length_frozen_enc_silu/le2bzt53/checkpoints/last.ckpt

MIROS 还需要其上游运行依赖。requirements.txt 保证本项目运行，不保证完整安装 MIROS 上游环境。

下载脚本会检出 amt-os/ai4m-miros 的固定源码 commit 并应用受控兼容补丁；pretrained_msd.pt 使用官方 Hugging Face minzwon/MusicFM 权重，last.ckpt 按上游 main.py 中的 Google Drive 官方文件 ID 获取。GitHub Actions 发布打包不依赖实时 Google Drive 配额，而是从本仓库既有 v1.0.16 Linux 便携包中流式提取已打包验证过的 external/ai4m-miros 目录；若便携包资产缺失、提取失败或 checkpoint 容器不完整，发布流程会停止并显示失败原因。

TransKun 默认 V2

TransKun 默认路线是钢琴专用转写后端，适合纯钢琴或以钢琴为主的音频。项目通过 src/core/transkun_transcriber.py 调用 transkun PyPI 包随附的 V2 预训练资源：

python -m pip install "transkun==2.0.1"

可用性检查会确认 transkun.transcribe、pretrained/2.0.pt 和 pretrained/2.0.conf 是否存在。资源缺失对应的修复命令如下：

python -m pip install --force-reinstall "transkun==2.0.1"

TransKun V2 Aug

PIANO_TRANSKUN_V2_AUG 是与默认路线并列的独立模式，使用上游官方 checkpointTransformerAug.zip 中的 checkpointMSimplerAug/checkpoint.pt 与 model.conf。Aug 表示训练时使用数据增强；它不会在默认 TransKun 失败时自动接管，反之亦然。

下载与校验命令：

python download_transkun_v2_aug_model.py

默认搜索模型位置包括：

~/.cache/music_ai_models/transkun_v2_aug/checkpointMSimplerAug
models/transkun_v2_aug/checkpointMSimplerAug     # 打包资源

Aria-AMT

Aria 音频预处理遵循官方长短音频分支：短音频先合并声道再用 torchaudio 重采样；长音频使用已有 FFmpeg 按原声道重采样为 float32，再合并声道。跨窗口拼接沿用官方恢复流程：非法序列由下一个既有重叠窗口重新生成；连续失败或结尾失败留下未恢复区间时停止输出，并报告具体秒数。模型、权重、精度、解码及 MIDI writer 保持官方实现，不修改 token，也不增加推理重试。MIDI 依赖固定为官方 ariautils 提交 7c815755c6889a784b6a1b3343e9e8daa3e7d128，包含上游同起点与零时值音符修正，运行时同时校验安装来源。稀疏钢琴 BPM 估计汇总短乐句的真实拍间隔，长空白不计入证据。复现对照、性能测量及跨平台验收边界见钢琴转写故障分析。

Aria-AMT 是另一条钢琴专用后端。项目通过 src/core/aria_amt_transcriber.py 统一调用官方单文件推理和 MIDI writer；Linux 源码版由 src.core.aria_amt_worker 独立进程执行，模型错误会直接返回项目队列，不再嵌套上游批处理进程。Docker 和便携包会提前准备官方 AudioTransform 读取的三个目录，支持运行时安装目录只读。默认 checkpoint 为：

piano-medium-double-1.0.safetensors

依赖安装命令：

python -m pip install --no-deps --force-reinstall "aria-amt @ https://github.com/EleutherAI/aria-amt/archive/a1ab73fc901d1759ec3bc173c146b3c6a3040261.zip"

模型下载命令：

python download_aria_amt_model.py

默认搜索模型位置包括：

~/.cache/music_ai_models/aria_amt
models/aria_amt                  # 打包资源

ByteDance Pedal

ByteDance Pedal 是钢琴专用的带踏板转写后端，适合独奏钢琴或清晰的钢琴 stem。它来自 ByteDance 的 High-Resolution Piano Transcription with Pedals 系统，本项目通过 piano-transcription-inference 包装，并保留上游 MIDI 中的延音踏板 CC64。

依赖安装命令：

python -m pip install "piano-transcription-inference==0.0.6" "torchlibrosa>=0.1.0,<0.2" "matplotlib>=3.7.0,<4"

模型下载命令：

python download_bytedance_piano_model.py

默认搜索模型位置包括：

~/.cache/music_ai_models/bytedance_piano
models/bytedance_piano           # 打包资源

钢琴后端选择建议

四个钢琴后端都是“钢琴专精模型”，不参与完整混音的多乐器识别。选择时可以按目标来分：

这四者的结果不能和 YourMT3+ / MIROS 的多乐器结果直接横比：钢琴后端只解决 88 键钢琴及其演奏细节，多乐器后端负责完整混音中的乐器识别和 GM 多乐器 MIDI 输出。

模型与公开对比

本节恢复自历史 README 中的模型对比内容，并按当前版本的实际能力重新标注：当前入口同步开放 SMART、VOCAL_SPLIT、SIX_STEM_SPLIT、PIANO_TRANSKUN、PIANO_TRANSKUN_V2_AUG、PIANO_ARIA_AMT 与 PIANO_BYTEDANCE_PEDAL 七种模式。下列表格把“公开 benchmark”和“项目内入口状态”分开写，避免把研究指标误写成产品能力。

当前已集成后端总览

YourMT3+ / MuScriptor / MIROS 属于多乐器后端，TransKun / Aria-AMT / ByteDance Pedal 属于钢琴专精后端，Leap XE / Leap Instrumental / BS-RoFormer SW Fixed 属于音源分离后端；三类模型的公开指标不能混成同一张排行榜。

当前默认转写模型：YourMT3+

本项目默认使用 YPTF.MoE+Multi (noPS)。官方 Hugging Face Space 的 app.py 默认 model_name 就是 YPTF.MoE+Multi (noPS)；YPTF.MoE+Multi (PS) 仍保留为可选 pitch-shift checkpoint。

性能基准（Slakh2100 数据集）

下表分别列出默认 noPS checkpoint 的 Space 评测结果和论文最终模型的成绩，两者对应的模型配置不同。

YourMT3+ 可用模型变体

官方 Hugging Face / Colab demo 的模型选择项是 checkpoint / 架构选择，不是本项目的处理工作流。当前项目中的 YourMT3+ 选择器与官方列表对齐；区别是本项目会把该模型嵌入 SMART、VOCAL_SPLIT 和 SIX_STEM_SPLIT 等工作流中，并统一输出 GM 多乐器 MIDI。

与官方 demo 的主要对齐点：

• 五个官方模式名称、checkpoint 目录映射和 UI 顺序一致。
• YPTF.MoE+Multi (noPS) 对齐官方 Hugging Face Space 默认展示模型。
• 五种 checkpoint 都使用官方 Space 对应的参数表和官方 update_config 生成 tokenizer/model/audio 配置。
• 旧 T5 checkpoint 缺少 ff_layer_type 元数据时，本项目按标准 T5 前馈层 t5_gmlp 处理。

与官方 demo 的差异也需要明确：

• 官方 demo 默认只运行单一 YourMT3 checkpoint；本项目还提供音源分离、钢琴专用模型、tempo 元数据补齐和 stem MIDI 合并，但不会对官方 writer 的音符做二次清理。
• 官方 GPU Space 通常使用 16-bit 推理；本项目默认使用 full precision，以降低不同 Windows / CUDA 环境中的不稳定因素。
• 产品使用与官方 Space 相同的无重叠分段和 inference_file(bsz=8)，batch 大小固定为 8。

当前可选后端：MIROS

处理语义：

• 所有入口默认使用固定高质量处理策略。
• MIROS 当前为固定 checkpoint 推理，可用于与 YourMT3+ 做同任务 A/B。

当前人声分离模型：Leap XE vocals + Leap Instrumental accompaniment

VOCAL_SPLIT 使用两个分离模型：BS-RoFormer Leap XE 90-band 对原混音生成 vocals，标准 BS-RoFormer Leap Instrumental 62-band 也对原混音独立生成 accompaniment。两路规范 WAV 进入音轨工作台后，可分别选择五个 YourMT3+ checkpoint、MIROS、MuScriptor Large / Medium / Small 或四个钢琴后端，共 13 条路线。

YourMT3+ 和 MIROS 保留官方 writer 的音符输出，并补充速度信息。两个分离模式先输出 WAV；在音轨工作台选择模型并开始转换后，才生成对应 MIDI。

两个分离模型各自对原混音推理。任一模型失败时，分离任务会停止并显示原因。

人声分离模型对比

表中“未写入数值”表示所列来源未提供与该 checkpoint 对应的明确评测分数。

结论（按口径）：

• 人声分离分数应在相同数据集和评测协议下比较。
• API/服务模型若缺少公开 checkpoint，不能直接替换本地模型。
• 论文特定协议的分数与 checkpoint 文件名中的训练分数不能直接横比。

不同榜单、数据集和评测协议（Multisong、MUSDB、MVSEP、cSDR/uSDR）的分数不可直接横比。

分离与钢琴转写流程

桌面版、Space 和 Colab 提供以下分离与钢琴转写流程。公开数据通常只覆盖“分离”或“钢琴 AMT”单项任务，不等于本项目端到端音频转 MIDI 的统一评分。

已接入与未来可关注的转写模型

下列对比按 2026-08-08 的公开资料更新。MuScriptor D_Test Multi F1、Slakh2100 Multi (Onset-Offset) F1、MAESTRO onset F1、官方挑战名次、以及主观听感/下游任务增益并不是同一协议，不能当成同一张排行榜直接横比。

多乐器模型（公开可核实）

钢琴专精模型对比（公开可核实）

钢琴同类模型质量对比

YourMT3+ / MuScriptor / MIROS 属于多乐器后端，不能与上表的钢琴专精 F1 横向混排；ByteDance Pedal 的 踏板 onset F1 也不能直接等同于 TransKun 的 onset+offset+velocity F1。

论文阶段 / 协议不一致的研究方向

补充说明：

• Basic Pitch 依然是很有价值的轻量方案，但它不发布与上表同口径的 Slakh/MAESTRO 综合榜单。
• Omnizart 仍是有参考价值的多任务工具链，但其 GitHub latest release 仍为 0.5.0（2021-12-09），与当前多乐器/钢琴专精 SOTA 的公开比较协议并不一致。

截至 2026-08-08，多乐器 AMT 的公开实现主要沿三条路线发展：MT3 / YourMT3+ / MR-MT3 的 token-based 架构、MIROS 的 MusicFM 预训练编码器，以及 MuScriptor 使用大规模真实数据和 RL 后训练的 decoder-only 模型。后续比较应同时报告密集复音、相似音色泄漏、稀有乐器、真实 jazz/pop 泛化、权重、许可、速度和显存，单个协议下的分数不足以概括模型能力。钢琴 AMT 也需分别标注 TransKun pip 权重、V2 Aug checkpoint、论文 checkpoint 与 pedal-aware 系统，避免把不同协议合并成一个榜单。

默认处理策略

桌面版、Space、Colab 和独立 Web 前端使用固定转写质量。YourMT3+ 产品路线使用官方无重叠分段、固定 bsz=8、逐解码通道 detokenize/merge、mix_notes 和官方 MIDI writer；MIROS 保留官方 CLI writer 输出。MuScriptor 固定使用官方 v0.3.0 源码、权重、5 秒窗口和 MIDI writer，并提供两种分段衔接方式：默认的“标准”保留上游原始分段状态；“跨段延音衔接”连接跨分段的持续音符。这个开关不改变速度方案，两种方式默认不量化、过滤或重建音符。需要量化时，在结果编辑器中选择范围和网格，再点击“量化”。

失败时的行为

任务失败时显示原因，并保留诊断信息供排查。

以下情况会得到明确的失败结果和根因：

• 模型、checkpoint、上游源码或必需 Python 包缺失。
• FFmpeg / 音频解码失败。
• YourMT3+、MIROS、MuScriptor、TransKun 默认 V2 / V2 Aug、Aria-AMT、ByteDance Pedal 或分离模型推理失败。
• 分离器没有生成完整目标文件。
• 模型下载遇到证书、网络或完整性问题。

各场景的用户可见行为：

如需尝试其他模型，请在模型选择器中切换后重新开始转换。

环境要求

各平台使用各自固定的兼容运行时；跨平台覆盖 NumPy/Torch 组合不属于支持范围：

Windows 源码版应放在本机磁盘的纯英文、无空格目录，例如：

C:\MusicToMidi
D:\Projects\music-to-midi

含中文、空格或括号的路径可能导致 PyTorch DLL 加载失败。映射盘和 UNC/SMB 网络路径尚未通过源码虚拟环境身份验收，可能让 venv 记录路径与启动路径不一致；本机 NTFS 的纯英文无空格目录是当前已支持的源码运行位置。

快速开始

MuScriptor gated 授权

MuScriptor Small / Medium / Large 都是 Hugging Face gated 模型，匿名用户无法下载。源码安装的授权条件是：同一个 Hugging Face 账户已在浏览器中分别接受 Small、Medium、Large 的条款，并在账号获批后从项目隔离环境登录：

# Windows；无 venv 时的最小授权环境仅包含官方 HF CLI
py -3.11 -m venv venv
.\venv\Scripts\python.exe -m pip install "huggingface_hub>=0.20,<2" "hf_xet==1.5.2"
.\venv\Scripts\hf.exe auth login

# Linux / WSL2
python3.11 -m venv venv
./venv/bin/python -m pip install "huggingface_hub>=0.20,<2" "hf_xet==1.5.2"
./venv/bin/hf auth login

登录使用具有三个 gated 仓库读取权限的个人 token。仓库、README、命令行参数和日志都不是受支持的 token 存放位置；无人值守环境的凭据入口是受保护的 HF_TOKEN secret。总下载脚本会在下载其它大型模型前依次做三个轻量权限预检，任一仓库未接受条款或未登录都会立即停止，不会改用其它模型。完整便携 release 已随包携带通过身份校验的权重，启动时不再从 Hub 下载；这不改变 CC BY-NC 4.0 与附加条款的适用范围。

Windows

推荐：

powershell -ExecutionPolicy Bypass -File .\run.ps1

或双击：

run.bat

run.ps1 会检查虚拟环境、核心依赖、Beat This final0、五种 YourMT3+ checkpoint、MuScriptor Small / Medium / Large、BS-RoFormer SW Fixed、Leap XE、Leap Instrumental、TransKun V2 Aug、Aria-AMT、ByteDance Pedal、MIROS、SoundFont 与 FluidSynth；资源缺失或身份校验失败时会调用 install.ps1。

Intel GPU 使用独立的原生 XPU 环境，不与 CUDA 环境共用 wheel 或 DLL：

powershell -ExecutionPolicy Bypass -File .\install_xpu.ps1
powershell -ExecutionPolicy Bypass -File .\run_xpu.ps1

安装和每次启动都会做真实 torch.xpu 矩阵、FFT 与 STFT 运算，捕获并拒绝 XPU→CPU 算子回落；随后初始化 OpenVINO GPU，并在禁用 CPU EP 回退后用 OpenVINOExecutionProvider 的 GPU.0 实际执行 MatMul ONNX 图。ORT 会自动列出内置 CPU provider，但 session.disable_cpu_ep_fallback=1 会让任何需分配给 CPU 的节点直接导致会话失败。任一门禁失败都会停止，不会改用 IPEX、DirectML、CUDA 或 CPU。

Leap Instrumental 固定使用 audio-separator 0.44.1 的原生 FP32 路线，与受控对比采用同一权重和配置：dim_t=1101、每片 563200 个采样、步进 8 秒。短音频补齐一个模型窗口后裁回原长度；不改变窗口或降精度。显存不足时任务停止，并显示 OOM 错误。新增伴奏权重的上游未声明许可证，便携包发布仍受第三方声明中的待确认记录约束。

Leap XE 在 XPU 上保留官方完整约 20 秒音频窗口、全部 key/value、checkpoint 与后处理，仅把 attention 的 query 轴固定分成 128 行逐块求值后拼接。每个 query 仍注意完整上下文，因此这是推理期数值等价的显存有界实现，不是缩短音频窗口、降低模型或 CPU 回退；训练态误用会直接报错。该路径用于避开仅覆盖部分 Intel 架构的 XPU Flash Attention 内核，此前版本已在 Arc 140T 16 GB 上完成真实两轨分离；该历史结果不包含本次替换的 Leap Instrumental，新伴奏路线尚未完成 XPU 实机验收。

MuScriptor Large 的 5.1 GiB checkpoint 在 XPU 上固定使用 safetensors==0.8.0 的官方 pread reader，并按文件偏移顺序一次只装载一个张量。XPU 路径会先打开惰性的 pread 文件句柄，再建立约 5.50 GiB 的统一内存模型，避免模型占用系统提交空间后才打开 checkpoint 所触发的 Windows os error 1455。该实现不会把完整 checkpoint 映射为 PyTorch storage，也不改变官方权重、精度与 writer；读取失败会直接停止，不会改回 mmap、扩大页面文件或自动重试。

Intel XPU 的本地 Web 后端会为每个 GPU 作业启动一个全新的推理进程，作业结束后由操作系统回收该进程的完整地址空间；常驻 HTTP 进程不跨作业保留 YourMT3、MIROS、MuScriptor 或分离模型。这样可避免统一内存模型在长会话中累积占用 Windows 系统提交额度。停止操作会终止并回收当前处理进程；处理进程非零退出，或缺少结果清单、结果文件时，任务会报告失败。

Linux / WSL2

chmod +x run.sh
./run.sh

run.sh 会检查虚拟环境、核心依赖、Beat This final0、受控 YourMT3+ 源码与五种 checkpoint、MuScriptor Small / Medium / Large、BS-RoFormer SW Fixed、Leap XE、Leap Instrumental、TransKun V2 Aug、Aria-AMT、ByteDance Pedal、MIROS、SoundFont 与 FluidSynth；资源缺失或身份校验失败时会调用 install.sh。

源码直接运行

受支持的源码运行环境是仓库内隔离且与加速器匹配的虚拟环境：NVIDIA CUDA 使用 venv，Windows Intel XPU 使用 venv-xpu。run.ps1 与 run_xpu.ps1 会在导入 GUI 和模型依赖前分别选择并严格校验解释器路径、include-system-site-packages=false、MuScriptor 包位置、版本和七个源码 SHA-256；全局 python -m src.main 会被拒绝。

# Windows 桌面 App
.\venv\Scripts\python.exe -m src.main

# Windows Web 前后端；自动识别局域网 IPv4 并打开前端
.\venv\Scripts\python.exe -m src.web

# Linux / WSL2 桌面 App
./venv/bin/python -m src.main

# Linux / WSL2 Web 前后端；浏览器手动打开终端显示的地址
./venv/bin/python -m src.web --no-window

手动安装

1. 创建虚拟环境

Windows:

py -3.11 -m venv venv
.\venv\Scripts\activate
python -m pip install --upgrade pip wheel "setuptools==80.10.2"

Linux:

python3.11 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip wheel "setuptools==80.10.2"

2. 安装 PyTorch

CUDA 12.8（完整七模式受支持且由启动器严格校验的运行时）:

pip install torch==2.7.0 torchaudio==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu128

Windows Intel XPU 的标准安装入口是 install_xpu.ps1。手动准备对应独立的 venv-xpu 和 requirements-xpu.txt 固定版本；在 venv 中覆盖 CUDA wheel 会破坏两套环境的隔离契约。

Intel XPU 采用“最新完整兼容组合”而不是单独追最高 torch 版本：截至当前，PyTorch XPU 已发布 2.13，但 torchaudio XPU 的最新匹配版本是 2.11，因此项目固定 torch/torchaudio==2.11.0+xpu 与 torchvision==0.26.0+xpu。这套官方硬件矩阵已经列出 Arc B-Series 与 Panther Lake / Core Ultra Series 3。既有 XPU 包中的 ONNX Runtime OpenVINO 1.24.1 与 OpenVINO 2025.4.1 仍按打包依赖管理；新 Leap Instrumental 走 PyTorch FP32，本次只在 NVIDIA CUDA 实测，尚未完成新伴奏路线的 Intel XPU 实机验收。未来只有在三件套与全部七模式重新验收通过后才整体升级，不混装不匹配版本。

Intel XPU 没有可直接等同 NVIDIA sm_XX 的项目级兼容版本号。该栈通过 oneAPI/Level Zero 发现设备，常规 JIT 路径由 Intel Graphics Compiler 按实际硬件生成代码；真正的支持边界以固定 PyTorch 版本的官方硬件矩阵、操作系统/驱动要求和本项目启动时的真实算子门禁共同决定，不能把“任意 Intel GPU”视为自动兼容。

torchaudio 2.11 的 load/save 已改为依赖 TorchCodec；TorchCodec 在 Windows 上又要求 full-shared FFmpeg DLL。项目不把缺失 DLL 隐藏成运行时回退：所有公开输入先由随包 FFmpeg 显式转换为 WAV，转写器再用固定的 libsndfile PCM 读取器生成 channels-first float32 张量，重采样和模型推理仍由 torchaudio/PyTorch 在已验证的 XPU 设备上执行。

cu118 / CUDA 11 不属于当前一键启动器和完整七模式验收契约；启动器检测到该环境时会停止并提示更新。

AMD/ROCm 尚未完成完整七模式实机验收，当前安装脚本仍会停止并说明兼容性问题。本次将伴奏分离改为 PyTorch FP32，不代表其余模型和完整工作流已获得 AMD 支持。

release.yml 只生成 CUDA 12.8 GPU 便携版，不生成 CPU 版。当前闭集清单包含 31 项第三方组件：26 项 VERIFIED、5 项附维护者具名责任与撤销联系记录的 OWNER_ACCEPTED、0 项 BLOCKED；工作流仍会在每次发布前重新校验清单、模型身份、SBOM、FFmpeg 构建信息和成品自检，任何一项不满足即停止。push / PR 的 build.yml 仅验证源码、测试与打包契约，不生成便携成品。本地源码开发如需 CPU-only PyTorch，应自行承担模型速度和依赖兼容性差异。

3. 安装项目依赖

pip install -r requirements.txt
python -m pip install --no-deps "audio-separator==0.44.1"
python -m pip install --no-deps --force-reinstall "aria-amt @ https://github.com/EleutherAI/aria-amt/archive/a1ab73fc901d1759ec3bc173c146b3c6a3040261.zip"
python -m pip install --no-deps --force-reinstall "muscriptor @ https://github.com/muscriptor/muscriptor/archive/d73147e75e5b9b0c0a79ebe154587db4fd603e0c.zip"
python -m src.utils.source_runtime

requirements.txt 有意不让 audio-separator 的 NumPy 2 元数据覆盖桌面 NumPy 1.26，也不让 Aria-AMT 的旧 torchaudio 约束覆盖 CUDA 12.8 运行时，因此两项采用固定版本的 --no-deps 独立安装。MuScriptor 同样以 --no-deps 固定源码身份，其 v0.3.0 非 Torch 依赖（包括 FastAPI 0.136.3、Starlette 1.5.0 与 SoundFile 0.14.0）已在项目依赖中显式满足；install.ps1 / install.sh 提供完整伴随依赖。

4. 准备 YourMT3+ 源码与模型

python download_sota_models.py

当前仓库已经包含受控且经过兼容补丁的 YourMT3/amt/src；可变上游 master 不满足这里的源码身份校验。download_sota_models.py 会准备 Beat This final0、全部五种官方 YourMT3+ checkpoint、固定 MIROS 源码与两组权重、BS-Rofo-SW-Fixed.ckpt、Leap XE、Leap Instrumental、TransKun V2 Aug、Aria-AMT 与 ByteDance checkpoint，并严格校验默认 TransKun 2.0.1 包版本和内置 V2 资源；缺失或身份不符会直接失败。

5. 准备分离与钢琴模型

python download_vocal_model.py
python download_multistem_model.py
python download_accompaniment_model.py
python download_transkun_v2_aug_model.py
python download_aria_amt_model.py
python download_bytedance_piano_model.py
python download_miros_model.py

模型默认缓存到：

~/.cache/music_ai_models/yourmt3_all
~/.music-to-midi/models/beat_this
~/.music-to-midi/models/audio-separator
~/.cache/music_ai_models/transkun_v2_aug
~/.cache/music_ai_models/aria_amt
~/.cache/music_ai_models/bytedance_piano
~/.cache/music_ai_models/fluidsynth/2.5.6
~/.cache/music_ai_models/musescore/4.7.4
${HF_HOME:-~/.cache/huggingface}/hub  # MuScriptor 三档与 MuseScore SoundFont
external/ai4m-miros

Windows 中的 ~ 是 %USERPROFILE%。源码虚拟环境固定为仓库内 venv，桌面默认输出为仓库内 MidiOutput\<音频文件名>，日志在 %USERPROFILE%\.music-to-midi\logs。默认 TransKun V2 资源位于 venv 中的 transkun==2.0.1 包内；便携版则只读取发布目录内的 models、runtime 与 tools 资源，不依赖上述源码缓存。

默认 TransKun V2 的模型资源随 transkun==2.0.1 安装；PIANO_TRANSKUN 资源或身份异常对应的修复命令是 python -m pip install --force-reinstall "transkun==2.0.1"。PIANO_TRANSKUN_V2_AUG 使用独立缓存，由 python download_transkun_v2_aug_model.py 准备。

6. 启动

# Windows
.\venv\Scripts\python.exe -m src.main

# Linux / WSL2
./venv/bin/python -m src.main

Google Colab

Colab 入口：

colab_notebook.ipynb

使用步骤：

1. 打开笔记本。
2. 选择 GPU 运行时。
3. 若要使用 MuScriptor，先按上文逐项接受三个 gated 仓库条款，把 token 保存为 Colab 私有 secret HF_TOKEN，并在第 3 个代码单元勾选 ENABLE_MUSCRIPTOR；该单元会在启动前验证三档访问权限。
4. 依次运行其余单元格。
5. 最后一个单元格会启动 Gradio，并输出公开访问链接。

Colab 版本会保留预装 PyTorch，避免重装 torch 导致 CUDA 运行库冲突。

Gradio Space

Space 入口：

space/app.py

本地启动：

cd space
python app.py

Space 版随部署包携带项目已验证的 YourMT3/amt/src 兼容源码，与桌面版和 Colab 使用同一棵源码树；不会在运行时改用 Hugging Face Space 的可变源码。运行转换时会按所选模式检查/准备 YourMT3+ 官方 checkpoint 或 MIROS、BS-RoFormer SW Fixed、Leap XE、Leap Instrumental、TransKun V2 Aug、Aria-AMT 或 ByteDance Pedal 资源；缺失或身份校验失败会显式暴露。

ZeroGPU 入口用于短片段试用。长歌建议使用 Colab、桌面版或专用 GPU。Hugging Face ZeroGPU 文档 当前公开配额为匿名用户每日 2 分钟、登录免费账户每日 5 分钟 GPU。当前保守的最小请求经 large GPU 平台倍率折算后已高于匿名额度，因此转换入口要求登录；Space 会按模式、后端和模型估算，再按固定的 spaces==0.51.1 平台倍率上界折算，超过登录免费账户 300 GPU 秒窗口的请求会在下载模型前明确拒绝。该估算只是准入上限，不代表用户一定仍有足够的当日配额或队列容量；Colab、桌面版或专用 GPU 更适合长歌。

当前公式下的最大输入时长是准入阈值，不是实测耗时承诺。默认 YPTF.MoE+Multi (noPS) 与 MIROS 的精确阈值如下；换用其它 YourMT3 checkpoint 时会按其独立系数重新计算：

Space 的失败请求会立即删除专属输出目录；成功结果会保留给 Gradio 下载，默认在 24 小时后进入过期清理，并在后续请求删除过期结果或在 Space 实例正常退出时清理。Colab 同样在失败时立即清理，并把成功结果保留到当前运行时结束；Gradio 缓存按 24 小时进入清理。

便携版打包

当前 THIRD_PARTY_NOTICES.md 的 31 项闭集清单为 26 项 VERIFIED、5 项 OWNER_ACCEPTED、0 项 BLOCKED。OWNER_ACCEPTED 表示上游未声明许可时由维护者具名承担再分发决定，并不等同于获得上游授权；Leap Instrumental 已有独立的维护者分发接受记录，官方 release 仍会在构建前严格校验全部组件。

Windows CUDA 完整三包构建（桌面 App、Web 后端、Web 前端）：

powershell -ExecutionPolicy Bypass -File .\build_web_executables.ps1

Intel XPU 本地三包的构建环境是已验收的独立 venv-xpu：

powershell -ExecutionPolicy Bypass -File .\build_portable_xpu.ps1

CUDA 输出为 dist\MusicToMidi-App、dist\MusicToMidi-WebBackend、dist\MusicToMidi-WebFrontend；XPU 输出为 dist\MusicToMidi-XPU-App、dist\MusicToMidi-XPU-WebBackend、dist\MusicToMidi-WebFrontend。Web 前端不含推理运行时，因此 CUDA/XPU 共用同一套前端文件；每个输出目录中的 _internal 与该目录对应。

完整模型与运行时会让 XPU 便携目录超过 20 GB。构建盘空间不足时，可把临时目录和成品目录指定到同一块有足够空间的 NTFS 卷；删减模型或留下半成品会使成品校验失败：

powershell -ExecutionPolicy Bypass -File .\build_portable_xpu.ps1 `
  -BuildRoot C:\MusicToMidi-XPU-build `
  -DistRoot C:\MusicToMidi-XPU-dist

XPU wrapper 默认只对同卷的 staged 资源建立 NTFS 硬链接，跨卷资源仍逐文件复制；两种路径都继续执行 staged 与 packaged SHA-256/manifest 校验。硬链接创建失败会终止构建并显示文件错误。有效的 BuildRoot 与 DistRoot 是互不嵌套的普通目录；盘根和项目根会被参数校验拒绝。

自定义 Python 或 FFmpeg 路径：

powershell -ExecutionPolicy Bypass -File .\build_web_executables.ps1 `
  -PythonExe .\venv\Scripts\python.exe `
  -FfmpegDir C:\ffmpeg\bin

打包脚本要求并严格校验以下全部资源；缺少任一项，或大小、SHA256、源码 manifest、运行时包身份不符时，会在 PyInstaller 前立即失败：

YourMT3/amt/src
YourMT3 模型缓存 -> models/yourmt3_all
audio-separator 模型缓存 -> models/audio-separator
transkun==2.0.1 包及其内置默认 V2 资源
TransKun V2 Aug 模型缓存 -> models/transkun_v2_aug
Aria-AMT 模型缓存 -> models/aria_amt
ByteDance Piano 模型缓存 -> models/bytedance_piano
固定版本且已打兼容补丁的 MIROS 源码与两组权重
ffmpeg.exe / ffprobe.exe

便携版资源来源优先级：

MUSIC_TO_MIDI_BUNDLE_YOURMT3_DIR 或 ~/.cache/music_ai_models/yourmt3_all 或 checkpoints/yourmt3_all
MUSIC_TO_MIDI_BUNDLE_AUDIO_SEPARATOR_DIR 或 ~/.music-to-midi/models/audio-separator 或 checkpoints/audio-separator
MUSIC_TO_MIDI_BUNDLE_TRANSKUN_V2_AUG_DIR 或 ~/.cache/music_ai_models/transkun_v2_aug 或 checkpoints/transkun_v2_aug
MUSIC_TO_MIDI_BUNDLE_ARIA_AMT_DIR 或 ~/.cache/music_ai_models/aria_amt 或 checkpoints/aria_amt
MUSIC_TO_MIDI_BUNDLE_BYTEDANCE_PIANO_DIR 或 ~/.cache/music_ai_models/bytedance_piano 或 checkpoints/bytedance_piano
MUSIC_TO_MIDI_BUNDLE_MIROS_DIR 或 external/ai4m-miros / ai4m-miros / .tmp/ai4m-miros
MUSIC_TO_MIDI_BUNDLE_FFMPEG_DIR 或 tools/ffmpeg / ffmpeg

构建结果包含以下三个完整目录：

dist/MusicToMidi-App/
dist/MusicToMidi-WebBackend/
dist/MusicToMidi-WebFrontend/

桌面用户使用完整 App 目录；Web 用户使用完整 WebBackend 与 WebFrontend 目录。单个 EXE 不包含对应角色的全部运行文件。

项目结构

src/
  core/
    pipeline.py              # 主处理流水线
    yourmt3_transcriber.py   # YourMT3+ 后端
    miros_transcriber.py     # MIROS 本地包装器
    transkun_transcriber.py  # TransKun 默认 V2 钢琴专用后端
    transkun_v2_aug_transcriber.py # TransKun V2 Aug 钢琴专用后端
    aria_amt_transcriber.py  # Aria-AMT 钢琴专用后端
    bytedance_piano_transcriber.py # ByteDance Pedal 钢琴专用后端
    vocal_separator.py       # 人声/伴奏分离
    multi_stem_separator.py  # 六声部分离
    midi_generator.py        # MIDI 生成与后处理
    beat_detector.py         # BPM/节拍检测
  gui/
    main_window.py           # PyQt6 主窗口
    widgets/track_panel.py   # 模式、后端、模型选择
    workers/processing_worker.py
  models/
    data_models.py           # Config、ProcessingResult、NoteEvent 等
    gm_instruments.py        # GM 128 乐器映射
  utils/
    runtime_paths.py         # 运行时资源路径
    yourmt3_downloader.py    # YourMT3+ 模型路径与下载辅助

space/app.py                 # Gradio Web 界面
colab_notebook.ipynb         # Colab 运行入口
download_sota_models.py      # Beat This + 全部公开工作流模型下载 + 默认 TransKun 严格校验
download_vocal_model.py      # Leap XE vocals 模型下载
download_accompaniment_model.py # Leap Instrumental accompaniment 下载入口
download_multistem_model.py  # BS-RoFormer SW Fixed 六声部分离模型下载
download_transkun_v2_aug_model.py # TransKun V2 Aug 下载与校验
download_aria_amt_model.py   # Aria-AMT 模型下载
download_bytedance_piano_model.py # ByteDance Pedal 模型下载
download_vocal_harmony_model.py # Leap Instrumental 历史兼容入口
MusicToMidi.spec             # PyInstaller 配置

开发命令

以下命令同样在仓库内 venv 激活后执行。

pytest
pytest tests/test_yourmt3_integration.py -v
black src/
isort src/
flake8 src/
mypy src/
pyinstaller MusicToMidi.spec

常用自检：

python -m src.main --self-test
python -c "from src.utils.gpu_utils import print_gpu_diagnosis; print_gpu_diagnosis()"
python -c "from src.core.yourmt3_transcriber import YourMT3Transcriber; print(YourMT3Transcriber.is_available())"

常见问题

PyTorch DLL 加载失败

优先检查：

• 项目路径是否含中文、空格或括号。
• 是否已安装 Visual C++ Redistributable 2022 x64。
• PyTorch、torchaudio、torchvision 版本是否匹配。

Windows 可重新运行：

powershell -ExecutionPolicy Bypass -File .\install.ps1

FFmpeg 不可用

Windows 可使用安装脚本自动安装，或手动安装后加入 PATH。Linux:

sudo apt-get update
sudo apt-get install -y ffmpeg

YourMT3+ 不可用

源码目录检查：

YourMT3/amt/src

模型检查：

python -c "from src.utils.yourmt3_downloader import get_model_path; print(get_model_path())"

缺失时：

python download_sota_models.py

如果受控的 YourMT3/amt/src 缺失，恢复来源是当前项目版本中的对应目录；可变上游 master 无法通过三端源码一致性与便携 manifest 校验。

如果下载模型时报 SSL 证书错误，默认会停止下载。受信任 CA 可通过系统/代理配置或以下环境变量提供：

export SSL_CERT_FILE=/path/to/ca.pem
export REQUESTS_CA_BUNDLE=/path/to/ca.pem

只有在你明确接受证书校验风险时，才设置：

export ALLOW_INSECURE_HF_DOWNLOAD=1

Windows PowerShell:

$env:ALLOW_INSECURE_HF_DOWNLOAD = "1"

YourMT3+ 官方路线固定调用 inference_file(bsz=8)。显存不足时处理停止并显示 CUDA 错误，batch 大小固定为 8。

人声分离不可用

依赖和模型检查：

Windows / Linux NVIDIA CUDA 环境：

python -m pip install --no-deps "audio-separator==0.44.1" "onnxruntime-gpu==1.23.2"
python download_vocal_model.py
python download_accompaniment_model.py

macOS 或明确的 CPU 环境把 onnxruntime-gpu==1.23.2 换成 onnxruntime==1.23.2。

如果当前 NVIDIA GPU、PyTorch/CUDA 或 audio-separator 后端不兼容，流程会直接失败并提示根因；不会自动改用 CPU 分离。需要 CPU 路径时，应由后续 UI/配置提供显式选项并在结果中标注。

六声部分离不可用

该路线依赖 audio-separator==0.44.1 和 BS-RoFormer SW Fixed 资源：

python download_multistem_model.py

如果六声部分离缺少任一 stem，流程会停止并提示缺失项。

钢琴专用转写不可用

默认 TransKun 模式需要 transkun 包和其随包预训练资源：

python -m pip install --force-reinstall "transkun==2.0.1"

TransKun V2 Aug 模式使用独立、固定校验的官方 checkpoint：

python download_transkun_v2_aug_model.py

Aria-AMT 模式需要 aria-amt 包和 checkpoint：

python -m pip install --no-deps --force-reinstall "aria-amt @ https://github.com/EleutherAI/aria-amt/archive/a1ab73fc901d1759ec3bc173c146b3c6a3040261.zip"
python download_aria_amt_model.py

MIROS 不可用

本地仓库位置与文件完整性检查：

ai4m-miros/main.py
ai4m-miros/transcribe.py

若提示缺少 Python 模块，缺失依赖以 MIROS 上游仓库的运行清单为准。

BPM 检测失败

当前版本不会用默认 120 BPM 继续生成 MIDI。若 Beat This final0 模型缺失/身份不符，或检测结果不足、乱序、含 NaN、局部速度不可信，流程会停止并报告具体错误；不会改用 librosa、第二检测器或旧 BPM。

配置校验失败

未知的处理模式、转写后端或多乐器模型会直接报错，不会自动改成默认值。有效配置值如下：

processing_mode: smart / vocal_split / six_stem_split / piano_transkun / piano_transkun_v2_aug / piano_aria_amt / piano_bytedance_pedal
transcription_backend: aria_amt / yourmt3 / miros / muscriptor
multi_instrument_model: yourmt3 / miros / muscriptor

旧配置中的 processing_mode=piano 会兼容映射为 smart。

许可证

本项目使用 MIT License。第三方模型、数据和上游仓库遵循各自许可证与使用条款；代码改编与完整声明见 THIRD_PARTY_NOTICES.md。