🎵 语音备忘录转 MIDI

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

功能说明

本技能提供一套完整的音频到 MIDI 转换流程，包含以下核心环节：

1. 音源分离 —— 使用 HPSS（谐波-打击乐音源分离）技术，从鼓声、噪声和背景音中精准提取旋律成分
2. 基于机器学习的音高检测 —— 调用 Spotify 的 Basic Pitch 模型，实现高精度基频提取
3. 调性检测 —— 基于 Krumhansl-Kessler 调性轮廓自动识别录音的音乐调性
4. 智能量化 —— 将音符对齐至可配置的时间网格，并支持可选的调性感知音高校正
5. 后处理优化 —— 执行八度修剪、基于重叠的和声去除、连奏音符合并等操作，确保输出简洁规范

处理流程架构

音频输入（WAV/M4A/MP3）
    ↓
┌─────────────────────────────────────┐
│ 步骤 1：音源分离（HPSS）            │
│ - 提取谐波成分                      │
│ - 移除鼓组与打击乐                  │
│ - 噪声门限处理                      │
└─────────────────────────────────────┘
    ↓
┌─────────────────────────────────────┐
│ 步骤 2：音高检测                    │
│ - Basic Pitch 机器学习模型（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 - 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. 应用 Swing/Groove 模板，避免网格过于机械生硬
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 许可证发布。