适用场景
手里只有一段手机录的哼唱、清唱或者单声部乐器录音,想在编曲软件里把它变成可以改音高、改节奏、换音色的 MIDI 轨道,但不想买商业转谱服务、也不想上传音频到别人的服务器。这套方案用轻量开源模型在本机完成识别,再把结果接进 DAW,适合独立音乐人、编曲初学者和需要批量处理素材的运维同学。整套流程跑在普通笔记本的 CPU 上,不需要独立显卡。
环境与前置条件
- 操作系统:macOS、Ubuntu/Debian 等主流 Linux 发行版;Windows 建议用 WSL2 或 conda 环境,避免原生依赖问题。
- Python:3.9–3.11 之间的版本比较稳妥,具体支持范围以官方文档当前版本为准。强烈建议用虚拟环境,不要装进系统 Python。
- 音频工具:需要
ffmpeg(读写 m4a/mp3)与libsndfile(读写 wav)。 - 硬件:内存 8 GB 起步,处理几分钟的单声道音频够用;16 GB 处理十几分钟的素材更从容。磁盘预留 2–3 GB 给依赖和模型权重。不需要 GPU。
- 输入素材:单声道、44.1 kHz 或 48 kHz 的 wav 最省事。哼唱时尽量贴近麦克风,环境噪音小,音高稳定,转出来的音符会干净很多。
分步骤部署
步骤 1:创建并激活虚拟环境
这一步是把依赖隔离在项目目录里,避免污染系统 Python。
```bash
mkdir -p ~/audio2midi && cd ~/audio2midi
python3 -m venv .venv
source .venv/bin/activate # Windows 用 .venv\Scripts\activate
python -m pip install -U pip setuptools wheel
python -V
```
成功标志:命令行提示符前出现 (.venv),python -V 输出的版本落在支持范围内。
步骤 2:安装系统级音频依赖
```bash
macOS
brew install ffmpeg
Ubuntu / Debian
sudo apt update && sudo apt install -y ffmpeg libsndfile1
```
成功标志:执行 ffmpeg -version 能打印出版本信息,不报 command not found。
步骤 3:安装 Audio-to-MIDI 模型包
这里以 Spotify 开源的 Basic Pitch 为例,它模型体积小、纯 CPU 推理、同时给出 MIDI 与音符事件 CSV,适合作为轻量基线。安装命令与包名以官方仓库当前版本为准。
```bash
pip install basic-pitch
```
成功标志:pip show basic-pitch 有输出,且下面这条导入不报错:
```bash
python -c "from basic_pitch.inference import predict_and_save; print('ok')"
```
首次推理时程序会自动下载模型权重到用户缓存目录,之后离线可用。若机器不能联网,需要按官方说明手动把权重放到缓存路径。
步骤 4:整理输入音频
模型对低频噪声和长静音段比较敏感,先做一次规整:转单声道、统一采样率、切掉首尾静音、轻度高通滤波去掉呼吸和房间隆隆声。
```bash
ffmpeg -i input.m4a -ac 1 -ar 44100 \
-af "highpass=f=70,dynaudnorm" \
hum.wav
```
成功标志:ffprobe hum.wav 显示 1 个声道、44100 Hz;用播放器听一遍,人声清楚、没有明显底噪。
如果整段素材很长,先切成 1–2 分钟的小段再分别处理,能显著降低内存峰值:
```bash
ffmpeg -i hum.wav -f segment -segment_time 120 -c copy part_%03d.wav
```
步骤 5:运行推理,生成第一个 MIDI
命令行方式最直接:
```bash
mkdir -p output
basic-pitch output/ hum.wav
```
默认会输出 MIDI 文件,文件名形如 hum_basic_pitch.mid(以实际输出为准)。想同时导出一份用 MIDI 渲染的音频,方便和原唱对比,加上渲染开关:
```bash
basic-pitch output/ hum.wav \
--onset-threshold 0.4 \
--frame-threshold 0.3 \
--minimum-note-length 80 \
--minimum-frequency 65 \
--maximum-frequency 1000 \
--sonify-midi
```
也可以用 Python API,方便后面批处理:
```python
from basic_pitch.inference import predict_and_save
from basic_pitch import ICASSP_2022_MODEL_PATH
predict_and_save(
audio_path_list=["hum.wav"],
output_directory="output",
save_midi=True,
sonify_midi=True,
save_model_outputs=False,
save_note_events=True,
model_or_model_path=ICASSP_2022_MODEL_PATH,
onset_threshold=0.4,
frame_threshold=0.3,
minimum_note_length=80,
minimum_frequency=65,
maximum_frequency=1000,
)
```
参数名以 basic-pitch --help 和官方文档当前版本为准,不同版本可能略有差异。
成功标志:output/ 目录下出现 .mid 文件,ls -l 看到的文件大小不为 0。
步骤 6:调阈值——决定"转得准"还是"转得干净"
同一段哼唱,参数不同结果差别很大。可以按下面的思路调:
| 参数 | 作用 | 调大的效果 | 建议起点 |
|---|---|---|---|
onset_threshold | 音符起始的判定门槛 | 音符变少、更保守 | 0.3–0.6 |
frame_threshold | 音符持续的判定门槛 | 碎音减少、尾音被截断 | 0.3–0.5 |
minimum_note_length | 最短音符长度(毫秒) | 过滤掉毛刺 | 80–150 |
minimum_frequency | 最低检测音高(Hz) | 屏蔽低频噪声 | 男声 65–80,女声 130–160 |
maximum_frequency | 最高检测音高(Hz) | 屏蔽齿音与气声 | 800–1200 |
调参顺序建议:先固定频率范围(贴合自己的音域),再调 frame_threshold 去掉碎音,最后用 onset_threshold 修节奏起头。每次只改一个参数,配合 --sonify-midi 生成的音频和原唱 A/B 对比,比盯着钢琴卷帘猜要快。
步骤 7:量化与清理——让 MIDI 对上节拍网格
模型输出的时间是连续的,直接拖进 DAW 会"差一点点"。用 pretty_midi 做一次网格量化,并合并同一时刻的重复音:
```python
quantize.py
import pretty_midi
GRID = 0.25 # 1/16 音符;4/4 拍、四分音符为一拍时为 0.25 秒
MIN_LEN = 0.08
def quantize(src, dst, grid=GRID, min_len=MIN_LEN):
pm = pretty_midi.PrettyMIDI(src)
for inst in pm.instruments:
fixed = []
for n in inst.notes:
s = round(n.start / grid) * grid
e = round(n.end / grid) * grid
if e - s < min_len:
e = s + grid
n.start, n.end = s, e
fixed.append(n)
fixed.sort(key=lambda n: n.start)
dedup = []
for n in fixed:
if dedup and abs(n.start - dedup[-1].start) < 1e-6 \
and n.pitch == dedup[-1].pitch:
continue
dedup.append(n)
inst.notes = dedup
pm.write(dst)
print(f"{dst}: {sum(len(i.notes) for i in pm.instruments)} notes")
if __name__ == "__main__":
quantize("output/hum_basic_pitch.mid", "output/hum_quantized.mid")
```
```bash
pip install pretty_midi
python quantize.py
```
成功标志:打印出音符数量,生成的 hum_quantized.mid 时间戳都是 0.25 的整数倍。
注意:模型写出的 MIDI 内部速度通常是 120 BPM(以读回结果为准)。DAW 工程的 BPM 必须设成同一个值,否则网格对不上,量化等于白做。
步骤 8:接进 DAW
方式一:导入文件(推荐,稳定)
打开 Reaper / Ableton Live / Logic / Cubase / FL Studio 任意一个,新建工程,把 BPM 设成与 MIDI 一致的值,把 hum_quantized.mid 拖到新轨道上,加载钢琴或合成器音源即可试听和二次编辑。如果音符还有轻微错位,用 DAW 自带的量化功能(网格设 1/16)再对齐一次,并检查是否有重叠音符需要"合并/连奏"。
方式二:虚拟 MIDI 端口(适合把结果实时送进 DAW 试音色)
先建立虚拟端口:
- macOS:打开"音频 MIDI 设置"→ 窗口 → MIDI 演播室 → 双击 IAC Driver → 勾选"设备在线"。
- Windows:安装 loopMIDI,新建一个端口并保持运行。
- Linux:
sudo modprobe snd-virmidi加载虚拟 MIDI 模块。
然后用 mido 把音符发出去:
```python
send_notes.py
import time, mido
print(mido.get_output_names()) # 先看端口名
out = mido.open_output("IAC Driver Bus 1") # Windows 填 loopMIDI 的端口名
for pitch, dur in [(60, 0.5), (62, 0.5), (64, 1.0)]:
out.send(mido.Message("note_on", note=pitch, velocity=100))
time.sleep(dur)
out.send(mido.Message("note_off", note=pitch, velocity=0))
time.sleep(0.02)
```
```bash
pip install mido python-rtmidi
python send_notes.py
```
在 DAW 里给轨道选择这个虚拟端口作为 MIDI 输入,并打开输入监听,就能听到声音。这条路线适合"试音色",不适合低延迟实时演奏;把音频缓冲区设成 256 或 512 samples 可以缓解卡顿。
验证部署是否成功
1. 文件层面
```bash
ls -lh output/
```
预期:能看到 .mid 文件,大小在几 KB 到几十 KB 量级,非 0。
2. 数据层面
```bash
python -c "
import pretty_midi
pm = pretty_midi.PrettyMIDI('output/hum_quantized.mid')
print('tempo:', pm.get_tempo_changes())
print('notes:', sum(len(i.notes) for i in pm.instruments))
print('end_time:', round(pm.get_end_time(), 2))
"
```
预期:notes 数量与哼唱的实际音符数接近(一般不会差出一个数量级);end_time 与原音频时长接近;tempo 记下来,去 DAW 里填同一个值。
3. 听觉层面
先听 --sonify-midi 生成的音频,再和原哼唱对比:旋律走向是否一致、有没有多出来的碎音、有没有整体高八度或低八度。整体偏移通常是频率范围设错了,碎音多则回到步骤 6 收紧阈值。
4. 端到端
DAW 里播放导入的 MIDI,用节拍器对一遍,确认音符落在网格上、时值合理。这一步通过,整条链路就算跑通了。
常见报错与解决
报错 1:ffmpeg: command not found 或 FileNotFoundError: [Errno 2] ... 'ffmpeg'
- 原因:读取 m4a/mp3 依赖 ffmpeg,但系统里没装或不在 PATH 上。
- 解决:按步骤 2 安装;实在装不上就先用
ffmpeg之外的机器转成 wav 再处理。
```bash
sudo apt install -y ffmpeg # Ubuntu
brew install ffmpeg # macOS
ffmpeg -version
```
报错 2:ModuleNotFoundError: No module named 'basic_pitch' 或 basic-pitch: command not found
- 原因:包装到了别的 Python 环境,或者虚拟环境没激活。
- 解决:
```bash
source .venv/bin/activate
pip install -U basic-pitch
python -c "from basic_pitch.inference import predict_and_save; print('ok')"
```
如果导入正常但命令行入口找不到,直接用步骤 5 的 Python API 脚本跑,效果一样。
报错 3:安装或导入深度学习依赖时报 ImportError: dlopen ...、libc++abi 之类错误
- 原因:Python 版本或 CPU 架构不匹配(Apple Silicon 上常见于用了 Rosetta 转译的 Python)。
- 解决:换成原生 arm64 的 Python 重新建虚拟环境;或用 conda 固定一个官方支持范围内的 Python 版本,重装依赖。具体支持矩阵以官方文档当前版本为准。
```bash
conda create -n audio2midi python=3.10 -y
conda activate audio2midi
pip install basic-pitch
```
报错 4:推理中途进程被杀,日志里出现 Killed 或 MemoryError
- 原因:一次性喂了十几分钟的音频,内存峰值超了。
- 解决:先用步骤 4 的
-f segment切段,再对每段单独推理,最后在 DAW 里拼接。
```bash
for f in part_*.wav; do basic-pitch output/ "$f"; done
```
报错 5:MIDI 里全是几十毫秒的碎音,听着像噪声
- 原因:帧阈值太松,模型把气声、滑音的过渡段也判成了音符。
- 解决:提高
frame_threshold,加大minimum_note_length,并收紧频率范围。
```bash
basic-pitch output/ hum.wav \
--frame-threshold 0.5 \
--minimum-note-length 120 \
--minimum-frequency 80 \
--maximum-frequency 900
```
报错 6:DAW 里找不到虚拟 MIDI 端口
- 原因:IAC 没勾"设备在线"、loopMIDI 没启动,或者 DAW 是在端口创建之前打开的。
- 解决:确认端口在线后重启 DAW;用
python -c "import mido; print(mido.get_output_names())"核对端口名,脚本里的名字必须完全一致。
后续维护
备份
- 模型权重缓存目录(首次运行自动下载的位置,通常在用户缓存目录下,以实际输出为准)单独留一份,换机器时直接拷贝,免去重新下载。
- 环境快照:
pip freeze > requirements.txt,配合.venv目录一起归档,半年后还能一键复原。 - 素材分三层存放:
raw/原始录音、midi/输出结果、final/定稿,不要混在一个目录里。
升级
升级前先 pip freeze > requirements.before.txt 存快照,升级后用同一段样例音频跑一次,对比音符数量与 --sonify-midi 的听感。阈值默认值和参数名可能随版本变化,升级后重新确认一遍命令。
日志与监控
- 每批处理都记录一行日志:文件名、音频时长、使用的阈值组合、输出音符数、耗时、峰值内存。攒够几十条之后,用哪组参数适合自己就一目了然了。
- 用
--save-note-events输出音符事件 CSV,比 MIDI 更容易做脚本比对,适合做回归测试。 - 批量跑的时候给进程降优先级,避免占满机器:
nice -n 10 bash run_all.sh。
日常使用建议
先用短片段(20–30 秒)把阈值调到满意,再套用到整首歌;每次只改一个参数,改完立刻听 --sonify-midi 的结果。商用前请确认模型与依赖的许可证条款,以官方仓库说明为准。
