MuScriptor
更新于 2026-10-27 17:56:03
一句话定位
MuScriptor 是 Kyutai 和 Mirelo 联合开源的多乐器音乐转录模型：丢给它一段录音，它吐出 MIDI，进一步还能排成乐谱（MusicXML / PDF / 吉他六线谱）。项目自称是目前最准的开源转录模型，代码 MIT，模型权重在 HuggingFace 上按 CC BY-NC 4.0（禁止商用） 发布。
它不是「分离人声/伴奏」那类工具，而是把整段音频里每个乐器在什么时间弹了什么音还原成符号，属于音乐信息检索里最难的那一档任务。
它能做什么
| 输入 | 输出 |
|---|---|
| 任意录音（乐队、钢琴、吉他、鼓组…） | 量化后的 MIDI（含拍号、小节线、tempo map） |
| 同上 | MusicXML 乐谱 |
| 同上 | 每件乐器单独的 PDF 分谱 + 有品乐器的六线谱 PDF |
| 同上 | 浏览器里的实时 piano roll（Web UI） |
三个模型规格：
| 变体 | 参数量 | 层数 | 维度 | 适用 |
|---|---|---|---|---|
small |
103M | 14 | 768 | 纯 CPU 机器的务实选择 |
medium（默认） |
307M | 24 | 1024 | 速度/精度平衡点 |
large |
1.4B | 48 | 1536 | 最准，基本要有 GPU |
架构是 纯 transformer decoder，论文在 arXiv 2607.08168。三个尺寸都能用 small / medium / large 关键字直接指定，权重首次使用时自动下载并缓存。
上手：三条命令的距离
前置条件：必须先在 HuggingFace 上接受模型许可（在 MuScriptor 组织下 small/medium/large 任一模型页点同意，会自动通过），然后本地登录：
uvx hf auth login
# 或者
export HF_TOKEN=hf_...
跑起来：
# 图形界面（等同官方在线版，只是换了外观）
uvx muscriptor serve
# 命令行转录
uvx muscriptor transcribe path/to/audio.wav
平台差异要注意，这是新手最容易卡住的地方：
| 平台 | 命令 |
|---|---|
| Linux / Apple Silicon macOS | uvx muscriptor serve |
| Windows（要用 GPU） | uvx --torch-backend=cu128 muscriptor serve |
| Intel Mac | uvx --python 3.12 muscriptor serve |
原因很实在：Windows 上 PyTorch 默认后端是 CPU，走 GPU 必须显式指定 CUDA 版本；而 PyTorch 在 torch 2.2.2 之后不再发 x86_64 macOS wheel，那个版本只支持到 Python 3.12，所以 Intel Mac 必须钉住 Python 版本（用 pip/uv 装的话选 3.10–3.12）。Apple Silicon 会自动用 Metal（MPS）。
节奏与量化：决定结果能不能用的关键
模型会自动检测拍点、拍号和小节线并写进 MIDI。如果演奏没有节拍器，它会写一张跟随演奏速度变化的 tempo map，让小节线贴着音乐走；想反过来要一个平均速度，用 --fixed-tempo。
检测不对的时候可以人工纠正，顺便把音符整理到网格上，方便导入打谱软件或 DAW：
muscriptor transcribe audio.wav --bpm 96 --beats-per-bar 3 --first-downbeat 1.2 \
--quantize --grid 4 --fill-gaps 0.25 --trim-leading-bars
参数含义值得记一下：
--quantize：把音符吸附到节拍网格；--grid 4是十六分音符，3是八分三连音，默认自动挑最贴合的那个；--quantize-strength 0.5只吸一半，保留一点人性化摇摆。--fill-gaps：休止符不超过这个拍数时，把前一个音延音过去——不然 Guitar Pro 之类会把每个空隙都写成休止符，谱面很脏。--trim-leading-bars：砍掉第一个音之前的空小节。--beat-scale 2（或0.5）：检测到的速度是正常值的一半（或两倍）时用它纠正。
Web UI 里也有同一个面板（Tempo & bars）和 MIDI 下载对话框，不必背参数。
出乐谱：额外依赖 MuseScore 4
muscriptor transcribe audio.wav --format sheets --output score/
输出目录长这样：
score/
├── score.mid 量化后的 MIDI
├── score.musicxml 排版后的乐谱
├── full_score.pdf 所有乐器合在一张总谱
├── 01_electric_guitar.pdf 每件乐器一个分谱…
├── 01_electric_guitar_tab.pdf …有品乐器再加一份六线谱
├── 02_electric_bass.pdf
├── 02_electric_bass_tab.pdf
└── 03_drum_kit.pdf
排版这一步是调用本机 MuseScore 4 及以上版本完成的，必须单独安装（musescore.org/en/download），装在非常规路径就设 $MUSCRIPTOR_MUSESCORE。没装的话，除 PDF 下载以外的功能都正常。
另一个现实约束：节拍清晰时效果最好，因为量化需要稳定的拍点。自由速度（rubato）的演奏会明显变差——谱子会跟着速度曲线走，但音符值会很碎。
用 Python 调
已发布到 PyPI（当前 0.4.0，开发状态标注 Beta）：
uv add muscriptor
# 或
pip install muscriptor
代码里可以 load_model() 直接选 small / medium / large，权重自动下载缓存。想接自己的批处理流水线（比如把一堆 demo 录音转成 MIDI 素材库），这是最舒服的方式。
适合谁用
- 扒谱的人：先让模型出一版 MIDI/MusicXML，再在 MuseScore 里改，比从零听写快得多；
- 编曲 / 制作：把灵感录音、现场手机录的片段转成 MIDI，直接拖进 DAW 换音色；
- 乐队排练：一份录音拆出吉他、贝斯、鼓的分谱和六线谱；
- 教学：把示范演奏变成可看的谱面；
- 研究者 / 开发者：MIT 代码可自由改，做自己的转录应用或前端。
坑与注意
- 权重不是商用许可：代码 MIT，但模型权重是 CC BY-NC 4.0，禁止商业使用。想做成付费产品，要么去谈授权，要么只把代码当参考自己重训——别看到仓库挂 MIT 就以为整个项目能商用。
- 必须接受 HF 许可：不登录、没点同意，权重下载会失败，报错信息不一定直观。
- MuseScore 是外部依赖：只想要 MIDI 的话完全不需要它；要 PDF 就绕不过。
- 显存与速度：
large1.4B 参数量，CPU 上会很慢，实际建议 GPU；small在 CPU 上可用但精度会掉。 - 项目很新：仓库 2026-07 才创建，PyPI 版本 0.4.0、标注 Beta，接口和 CLI 参数后续可能变，脚本里最好锁版本。
二开建议
- 前端：
web/是独立前端工程，需要 pnpm + Node；pnpm install && pnpm run build构建一次即可，改前端就pnpm dev起热更新（5173 端口），后端用uv run muscriptor serve --port 8222配合。 - 跑本地仓库：
uv sync装依赖，之后用uv run（注意不是uvx）跑serve/transcribe。 - 改推理流程：transcribe 的节奏检测、量化、导出是相对独立的阶段，想加自己的导出格式（比如直接生成 Guitar Pro 的 gp 文件）从导出阶段下手最省事。
- 想做服务化：
serve本身就是后端 + 静态前端的组合，包一层反向代理和队列就能给团队用；注意权重许可仍然限制商用。
和专业 OMR 的分工
MuScriptor 的入口是音频。如果你手上是纸质谱或扫描 PDF，需要的是图像方向的 OMR，那是另一条路线：同批收录的 Audiveris（Audiveris/audiveris），Java 写的开源 OMR 引擎，输出 MusicXML。
录音 / 现场演奏 ──MuScriptor──▶ MIDI / MusicXML / PDF
纸质谱 / 扫描 PDF ──Audiveris────▶ MusicXML
一个从声音回到符号，一个从图像回到符号，最终都汇到 MusicXML 这个共同格式上。
一句话总结
MuScriptor 把「录音转 MIDI 再排版成谱」这条链路做成了三条命令的事，多乐器、带鼓谱和六线谱、还给 Web UI 和 Python API，工程完成度在开源转录模型里相当突出；真正要留意的是权重 CC BY-NC 的商用限制，以及「节拍清晰才好用」这个物理约束。