名称： voice-note-to-midi
描述： 使用基于机器学习的音高检测与智能后处理，将语音备忘录、哼唱和旋律性音频录音转换为量化的MIDI文件
作者： Clawd
标签： [音频, midi, 音乐, 转录, 机器学习]

🎵 语音备忘录转 MIDI

将您的语音备忘录、哼唱和旋律性录音转换为干净、量化的MIDI文件，可直接导入数字音频工作站（DAW）使用。

功能概述

本工具提供一套完整的音频到MIDI转换流程，包含：

1. 音源分离 - 使用HPSS（谐波-打击乐源分离）技术，从鼓点、噪音和背景声中分离出旋律内容
2. 基于ML的音高检测 - 利用Spotify的Basic Pitch模型，精确提取基频
3. 调性检测 - 使用Krumhansl-Kessler调性轮廓，自动检测录音的调性
4. 智能量化 - 将音符对齐到可配置的时值网格，并可选进行基于调性的音高校正
5. 后处理 - 应用八度修剪、基于重叠的谐波移除以及连音音符合并，以获得干净的输出

处理流程架构

音频输入 (WAV/M4A/MP3)
    ↓
┌─────────────────────────────────────┐
│ 步骤 1: 音源分离 (HPSS)            │
│ - 分离谐波内容                      │
│ - 移除鼓/打击乐                     │
│ - 噪声门控                          │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 步骤 2: 音高检测                    │
│ - Basic Pitch ML 模型 (Spotify)     │
│ - 复音音符检测                      │
│ - 起始/结束时间估计                 │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 步骤 3: 分析                        │
│ - 音级分布分析                      │
│ - 调性检测                          │
│ - 主导音符识别                      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 步骤 4: 量化与清理                  │
│ - 时值网格对齐                      │
│ - 基于调性的音高校正                │
│ - 八度修剪 (移除谐波)               │
│ - 基于重叠的修剪                    │
│ - 音符合并 (连音)                   │
│ - 力度标准化                        │
└─────────────────────────────────────┘
    ↓
MIDI 输出 (标准 MIDI 文件)

安装设置

先决条件

• Python 3.11+ (推荐 Python 3.14+)
• FFmpeg (用于支持多种音频格式)
• pip

安装步骤

快速安装 (推荐):

cd /path/to/voice-note-to-midi
./setup.sh

此自动化脚本将执行以下操作：
- 检查是否安装了 Python 3.11+
- 创建 ~/melody-pipeline 目录
- 设置虚拟环境
- 安装所有依赖项 (basic-pitch, librosa, music21 等)
- 下载并配置 hum2midi 脚本
- 将 melody-pipeline 添加到您的 PATH 环境变量

手动安装:

如果您偏好手动设置：

mkdir -p ~/melody-pipeline
cd ~/melody-pipeline
python3 -m venv venv-bp
source venv-bp/bin/activate
pip install basic-pitch librosa soundfile mido music21
chmod +x ~/melody-pipeline/hum2midi

5. 添加到 PATH (可选):

echo 'export PATH="$HOME/melody-pipeline:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证安装

cd ~/melody-pipeline
./hum2midi --help

使用方法

基础用法

将语音备忘录转换为 MIDI：

./hum2midi my_humming.wav

这将创建 my_humming.mid 文件，并使用十六分音符进行量化。

指定输出文件

./hum2midi input.wav output.mid

命令行选项

使用示例

量化到八分音符

./hum2midi melody.wav --grid 1/8

基于调性的量化 (推荐用于调性音乐)

./hum2midi song.wav --key-aware

要求更长的音符最小时长

./hum2midi humming.wav --min-note 100

跳过分析以加快处理速度

./hum2midi quick.wav --no-analysis

组合选项

./hum2midi recording.wav output.mid --grid 1/8 --key-aware --min-note 80

处理 MIDI 输入

您也可以将现有的 MIDI 文件送入量化流程进行处理：

./hum2midi input.mid output.mid --grid 1/16 --key-aware

这将跳过音频处理步骤，直接进入分析和量化阶段。

示例输出

═══════════════════════════════════════════════════════════════
  hum2midi - 旋律转MIDI流程 (Basic Pitch 版本)
  [基于调性模式已启用]
═══════════════════════════════════════════════════════════════

输入:  my_humming.wav
输出: my_humming.mid

→ 步骤 1: 音源分离 (HPSS)
  正在分离旋律内容...
  已加载: 5.23s @ 44100Hz
  ✓ 旋律音干已提取 → 5.23s

→ 步骤 2: 音频转MIDI (Basic Pitch)
  正在对旋律音干运行 Spotify 的 Basic Pitch ML 模型...
  ✓ 原始 MIDI 已生成 (Basic Pitch)

→ 步骤 3: 音高分析与调性检测
  检测到音符: 总计 42 个，7 个唯一音高
  音符范围: C3 - G4
  音级: C3, E3, G3, A3, C4, D4, G4
  主导音符: G3 (占音符总数的 23.8%)
  检测到的调性: G 大调

→ 步骤 4: 量化与清理
  八度修剪: 移除了 3 个高于 67（中位数+12）的谐波音符
  重叠修剪: 移除了 2 个位于重叠位置的谐波音符
  音符合并: 将 5 个断奏片段合并为连音音符 (间隔<=60 ticks)
  网格:   240 ticks (1/16)
  音符:   38 个音符
  调性:   G 大调
  基于调性: 2 个音符被校正到音阶内
  速度:   120 BPM
  ✓ 量化后的 MIDI 已保存

═══════════════════════════════════════════════════════════════
  ✓ 完成！输出文件: my_humming.mid
═══════════════════════════════════════════════════════════════

📊 分析摘要
─────────────────────────────────────────────────────────────
  检测到的音符: C3, E3, G3, A3, C4, D4, G4
  检测到的调性: G 大调
  量化:         基于调性模式 (音符对齐到音阶)

MIDI 信息: 38 个音符，7 个唯一音高，120 BPM
音高: C3, E3, G3, A3, C4, D4, G4

注意事项与限制

音频质量至关重要

• 清晰、响亮的旋律 能产生最佳效果
• 背景噪音 可能导致错误的音符检测
• 混响和效果 可能会干扰音高检测
• 近距离拾音的人声 效果远优于房间录音

音乐性考量

• 单音源 效果最佳（单旋律线）
• 复音音频（和弦、多种乐器）会产生混乱的结果
• 颤音和弯音 可能会被量化为阶梯式音高
• 快速音符段落 可能会被遗漏或合并

技术限制

• 输出速度固定 为 120 BPM（时间位置被保留，但在您的 DAW 中可能需要调整速度）
• 音符力度 已标准化，但可能需要手动调整
• 极短的音符 (<50ms) 默认可能被过滤掉
• 极端音高范围 可能导致八度检测问题

后处理建议

生成 MIDI 后，您可能需要：

1. 导入到您的 DAW 并调整速度以匹配原始录音
2. 进一步量化 如果需要更严格的时序
3. 调整音符力度 以获得动态变化
4. 应用摇摆/律动模板 如果严格的网格听起来过于机械
5. 编辑个别音符 对于检测错误的音符（在快速乐句中常见）

支持的音频格式

通过 FFmpeg 支持的输入格式：
- WAV, AIFF, FLAC (未压缩，最佳质量)
- MP3, M4A, AAC (压缩，可接受)
- OGG, OPUS (开源格式)
- FFmpeg 支持的大多数其他格式

故障排除

未检测到音符

• 检查输入文件是否静音或损坏
• 尝试增加 --min-note 阈值
• 确认音频包含清晰的旋律内容（不仅仅是噪音）

音符过多 / 输出混乱

• 启用八度修剪和重叠修剪（默认已启用）
• 使用 --key-aware 将音符限制在音阶内
• 检查源音频中是否有背景噪音

检测到错误的调性

• 调性检测在至少有 8-10 个小节的音乐时效果最佳
• 半音阶段落可能会干扰检测器
• 如有需要，请在您的 DAW 中手动检查和调整

音符位于错误的八度

• Basic Pitch 有时会检测到谐波而非基频
• 流程中包含了修剪步骤，但可能仍有遗漏
• 对于简单的八度移位，可使用您 DAW 的移调功能

参考资料

• Basic Pitch - Spotify 的复音音高检测模型
• librosa HPSS - 谐波-打击乐源分离
• Krumhansl-Kessler 调性轮廓 - 调性检测算法

许可证

本工具集成了 Spotify 的 Basic Pitch，其基于 Apache 2.0 许可证授权。流程脚本和文档基于 MIT 许可证提供。