voice-note-to-midi

🎵 语音备忘录转 MIDI

将语音备忘录、哼唱和旋律录音转换为干净、量化后的 MIDI 文件，可直接用于你的 DAW。

功能介绍

此技能提供完整的音频转 MIDI 流程，包括：

1. 音轨分离 - 使用 HPSS（谐波-打击乐源分离）从鼓声、噪声和背景音中分离出旋律内容
2. 机器学习驱动的音高检测 - 利用 Spotify 的 Basic Pitch 模型准确提取基频
3. 调性检测 - 使用 Krumhansl-Kessler 调性轮廓自动检测录音的调性
4. 智能量化 - 将音符对齐到可配置的时间网格，并可选择启用调性校正
5. 后期处理 - 通过八度音筛除、基于重叠的泛音移除和连奏音符合并，生成干净的输出

流程架构

Audio Input (WAV/M4A/MP3)
    ↓
┌─────────────────────────────────────┐
│ Step 1: Stem Separation (HPSS)     │
│ - Isolate harmonic content          │
│ - Remove drums/percussion           │
│ - Noise gating                      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 2: Pitch Detection             │
│ - Basic Pitch ML model (Spotify)    │
│ - Polyphonic note detection         │
│ - Onset/offset estimation           │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 3: Analysis                    │
│ - Pitch class distribution          │
│ - Key detection                     │
│ - Dominant note identification      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ Step 4: Quantization & Cleanup      │
│ - Timing grid snap                  │
│ - Key-aware pitch correction        │
│ - Octave pruning (harmonic removal) │
│ - Overlap-based pruning             │
│ - Note merging (legato)             │
│ - Velocity normalization            │
└─────────────────────────────────────┘
    ↓
MIDI Output (Standard MIDI File)

设置

前提条件

• 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

这将创建使用 16 分音符量化的 my_humming.mid。

指定输出文件

./hum2midi input.wav output.mid

命令行选项

选项	说明	默认值
--grid <value>	量化网格：1/4、1/8、1/16、1/32	1/16
--min-note <ms>	最短音符时长（毫秒）	50
--no-quantize	跳过量化（输出原始 Basic Pitch MIDI）	禁用
--key-aware	启用调性校正	禁用
--no-analysis	跳过音高分析和调性检测	禁用

用法示例

量化为八分音符

./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 - Melody-to-MIDI Pipeline (Basic Pitch Edition)
  [Key-Aware Mode Enabled]
═══════════════════════════════════════════════════════════════

Input:  my_humming.wav
Output: my_humming.mid

→ Step 1: Stem Separation (HPSS)
  Isolating melodic content...
  Loaded: 5.23s @ 44100Hz
  ✓ Melody stem extracted → 5.23s

→ Step 2: Audio-to-MIDI Conversion (Basic Pitch)
  Running Spotify's Basic Pitch ML model on melody stem...
  ✓ Raw MIDI generated (Basic Pitch)

→ Step 3: Pitch Analysis & Key Detection
  Notes detected: 42 total, 7 unique
  Note range: C3 - G4
  Pitch classes: C3, E3, G3, A3, C4, D4, G4
  Dominant note: G3 (23.8% of notes)
  Detected key: G major

→ Step 4: Quantization & Cleanup
  Octave pruning: removed 3 harmonic notes above 67 (median+12)
  Overlap pruning: removed 2 harmonic notes at overlapping positions
  Note merging: merged 5 staccato chunks into legato notes (gap<=60 ticks)
  Grid:   240 ticks (1/16)
  Notes:  38 notes
  Key:    G major
  Key-aware: 2 notes corrected to scale
  Tempo:  120 BPM
  ✓ Quantized MIDI saved

═══════════════════════════════════════════════════════════════
  ✓ Done! Output: my_humming.mid
═══════════════════════════════════════════════════════════════

📊 ANALYSIS SUMMARY
─────────────────────────────────────────────────────────────
  Detected Notes: C3, E3, G3, A3, C4, D4, G4
  Detected Key:   G major
  Quantization:   Key-aware mode (notes snapped to scale)

MIDI Info: 38 notes, 7 unique pitches, 120 BPM
Pitches: 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 Key Profiles - 调性检测算法

许可证

此技能集成了 Spotify 的 Basic Pitch，其采用 Apache 2.0 许可证。流水线脚本和文档采用 MIT 许可证。