voice-note-to-midi

🎵 ボイスメモから MIDI へ

ボイスメモ、ハミング、メロディの録音を、DAWですぐに使える、クリーンでクオンタイズ済みの MIDI ファイルに変換します。

できること

このスキルは、次の処理を行うオーディオから MIDI への変換パイプラインを提供します。

1. ステム分離 - HPSS（ハーモニック・パーカッシブ音源分離）を使い、ドラム、ノイズ、背景音からメロディ成分を分離します
2. ML によるピッチ検出 - 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	ピッチ分析とキー検出をスキップします	無効

使用例

8 分音符にクオンタイズする

./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 - キー検出アルゴリズム

ライセンス

このスキルには、Apache 2.0 ライセンスの Spotify の Basic Pitch が組み込まれています。パイプラインスクリプトとドキュメントは MIT ライセンスで提供されています。