MIR の全体像
MIR は Music Information Retrieval（音楽情報検索）の略で、音を音楽的な答えに変える音声解析の領域です。たとえば、テンポ、ビート位置、キー、コード、ピッチ、音色、構造を扱います。
このページは全体の見取り図です。ドキュメント全体に出てくる用語をまとめ、それらがどう積み上がっているかを示すので、どの機能をどこで呼べばよいかが分かります。
ここで挙げる用語をまとめるのには理由があります。これらは互いに無関係な機能名ではありません。ほぼすべての MIR タスクが同じ時間-周波数の土台の上に成り立っています。その共通の土台を一度理解すれば、個々の機能は無関係な長いリストには見えなくなります。
初めてなら、リファレンスではなく見取り図として読む
このページは各要素がどう関係するかを説明します。呼び出しシグネチャは JavaScript API や Python API を、どう計算されるかは DSP 実装解説 を参照してください。
共通のパイプライン
MIR 機能の多くは、少数の中間表現から導かれます。これらを利用者が手で組む必要はほとんどなく、libsonare が内部で計算します。それでも流れを知っておくと、なぜ多くの機能が nFft や hopLength のようなパラメータを共有するのかが分かります。
中間表現の共有が効くのは、曲全体を一度に解析する場合だけです。analyze（MusicAnalyzer）は STFT とその派生表現を一度だけ計算し、BPM・キー・コード・セクションの各結果で使い回します。
単機能のヘルパーは中間表現を共有しない
detectBpm、detectKey、detectChords、セクション系のヘルパーは、いずれも生のサンプルから処理をやり直し、音声をキーにしたキャッシュもありません。同じ曲について複数の答えが欲しい場合は、単機能ヘルパーを並べるのではなく、曲全体の解析を 1 回呼んでください。STFT とクロマは 1 回だけ計算されます。
どの問いに、どの機能か
| 答えたいこと | 使うもの | 土台 | 呼び出し（JavaScript / Python） | CLI |
|---|---|---|---|---|
| どのくらい速い? ビートはどこ? | BPM / ビートトラッキング | オンセット強度 | detectBpm、detectBeats / detect_bpm、detect_beats | bpm、beats |
| 何のキー? | キー検出 | クロマ | detectKey / detect_key | key |
| 何のコードが鳴っている? | コード認識 | クロマ | detectChords / detect_chords | chords |
| サビはどこから始まる? | セクション解析 | MFCC（音色）＋クロマ（ハーモニー）＋エネルギー | analyzeSections / analyze_sections | sections |
| メロディの音は? | ピッチ / メロディ追跡 | ピッチ追跡（後述の「分離とピッチ」を参照） | pitchPyin、pitchYin / pitch_pyin、pitch_yin | pitch |
| どんな音色に聞こえる? | MFCC | メルスペクトログラム | mfcc / mfcc | なし |
| ドラムを他から分離できる? | HPSS | スペクトログラムの構造 | hpss / hpss | hpss |
| 時間ごとの生の周波数成分は? | STFT / スペクトログラム | 波形 | stft / stft | なし |
| 録音空間はどんな響きか? | ルーム音響解析 | インパルス応答（IR）の減衰、またはブラインド自由減衰推定 | analyzeImpulseResponse、detectAcoustic / analyze_impulse_response、detect_acoustic | acoustic |
どの呼び出しも、サンプルとファイル本来のサンプルレートを受け取ります。レートが重要な理由はオーディオ基礎を参照してください。
import { init, detectBpm, detectKey, analyze } from '@libraz/libsonare';
await init();
const bpm = detectBpm(samples, sampleRate); // 1 つの問い、1 回の処理
const key = detectKey(samples, sampleRate);
const result = analyze(samples, sampleRate); // 曲全体を 1 回の処理で
// result.bpm、result.key、result.chords、result.sectionsimport libsonare as sonare
audio = sonare.Audio.from_file("song.wav")
bpm = audio.detect_bpm() # 1 つの問い、1 回の処理
key = audio.detect_key()
result = sonare.analyze(audio.data, audio.sample_rate) # 曲全体を 1 回の処理でsonare bpm song.wav
sonare key song.wav
sonare analyze song.wav # 曲全体を 1 回の処理でタイミング: BPM、ビート、オンセット、セクション
タイミング系の機能は、段階的に積み上がっています。
| 機能 | 答える問い |
|---|---|
| オンセット検出 | ノート、ドラム、子音などがどこで始まるか。オンセット強度の包絡線に立つスパイクです。 |
| BPM | オンセットがどれくらい周期的か。 |
| ビートトラッキング | タイムライン上の拍がどこにあるか。 |
| セクション解析 | イントロ、A メロ、サビ、ブレイクのような長めのスパンがどこで始まり終わるか。上の 3 行と違い、この機能はオンセット包絡線を読みません。境界は音色（MFCC）とハーモニー（クロマ）から出ます。 |
オンセットがリズム系の起点
BPM、ビート、テンポグラムはすべて同じオンセット強度の包絡線から始まります。BPM 推定の背後にある時間 × テンポの図が欲しい場合は、リアルタイムとストリーミング のテンポグラム系を参照してください。
ハーモニー: キー、コード、クロマ
クロマは周波数成分を 12 のピッチクラス（C・C♯・…・B）に畳み込み、同じ音のすべてのオクターブをまとめます。これがハーモニーの自然な土台になります。キー検出は全体のクロマ分布から調性中心を推定し、コード認識はフレームごとにその瞬間のハーモニーを推定します。
クロマはオクターブと音色の細部を捨ててハーモニーの明瞭さを得る
オクターブをまとめるからこそ、クロマはキー／コード解析に向いています。同じ理由で、オクターブやスペクトル形状が重要なメロディや音色の解析には向きません。表現は問いに合わせて選んでください。
スペクトル: FFT、STFT、スペクトログラム
FFT（高速フーリエ変換）は DFT（離散フーリエ変換）の高速実装で、サンプルブロックを周波数成分に変換します。
STFT（短時間フーリエ変換）はそれを短く重なり合うウィンドウで繰り返し、周波数成分を時間方向にも追えるようにします。
スペクトログラムはその可視化です。横軸が時間、縦軸が周波数、明るさが強度を表します。
どこでも繰り返し出てくるパラメータが 2 つあります。
nFftはウィンドウサイズです。大きいほど周波数分解能は細かくなりますが、時間はぼやけます。hopLengthはウィンドウ間のステップです。小さいほどフレームが増え、動きが滑らかになります。
周波数分解能と時間分解能のトレードオフは、libsonare 固有の癖ではなく本質的なものです。
知覚特徴量: メル、MFCC、CQT、VQT
これらの知覚特徴量は、それぞれ違う問いに答えます。
| 特徴量 | 強調するもの |
|---|---|
| メルスペクトログラム | 周波数分解能を人間の聴覚に合わせて配分します。低域は細かく、高域は粗く扱います。 |
| MFCC（メル周波数ケプストラム係数） | コンパクトな「音色の指紋」です。メルスペクトログラムを取り、その大きさを対数で圧縮し、各フレームを少数の数値にまとめます。これらの数値は、正確なピッチではなく全体的なスペクトル形状を捉えます。 |
| CQT / VQT（定 Q 変換 / 可変 Q 変換） | 音楽的に等間隔なビンです。ビンは幾何級数的に並び、1 オクターブあたりの本数は binsPerOctave で決まります。既定は 12（半音ごと）ですが、クロマやチューニングの用途では 24 や 36 もよく使われます。Hz 等間隔より、ピッチ関係そのものが重要な場面で活きます。 |
これらの変換は、プレビューやデバッグのために逆向きにも実行できます。逆変換特徴量 を参照してください。
分離とピッチ: HPSS とピッチ推定
HPSS は Harmonic/Percussive Source Separation、つまり倍音成分と打撃成分の分離です。スペクトログラム上の形の違いを使って、持続的なピッチ素材と過渡的な打撃を分けます。
| 成分 | スペクトログラム上の形 |
|---|---|
| 倍音成分 | 主に水平の線 |
| 打撃成分 | 主に垂直の線 |
先に分離しておくと、ドラムとピッチ楽器が互いの解析を乱しにくくなり、下流タスクの精度が上がることが多いです。
ピッチ推定は F0 を追跡します。F0 は波形の周期性を決める周波数で、調和的な音では部分音（個々の周波数成分。オーディオ基礎 を参照）の間隔も決めます。F0 の成分がスペクトルに現れない場合もあるため、観測されたスペクトルの最低ピークや最も強いピークとは限りません。明るい金管の音や小型スピーカーで鳴るベースでは上の倍音が優勢になることがありますが、F0 の成分がなくても音高を知覚できることがあります。鐘やシンバルのような非調和音には、明確な F0 がないこともあります。そのため推定器は、最も強いスペクトルピークではなく波形の周期性を使います。メロディ、ボーカル、単音楽器、チューニング確認、採譜系のワークフローで使えます。
隣接領域: ルーム音響
ルーム音響解析は MIR に隣接する領域です。音符、リズム、楽曲構成ではなく、録音に含まれる空間の性質を記述します。
クリーンなインパルス応答が手元にある場合は、直接 IR 解析を使います。この経路では RT60（残響が 60 dB 減衰するまでの時間）、EDT、C50、C80、D50、バンド別減衰を測定します。
通常録音しかない場合は、ブラインド音響推定を使います。この経路は残響の手がかりを信頼度つきで返します。録音の中に自由減衰の証拠が乏しい、あるいはまったくないこともあるためです。詳しくは ルーム音響解析 を参照してください。
実装メモ
libsonare はブラウザ（WASM）、JavaScript、Python、ネイティブバインディング、CLI、C++ API のいずれからも MIR 関連機能を呼び出せます。
多くの機能は STFT、クロマ、スペクトルエネルギー曲線といった中間表現を共有します。ただしこの共有は MusicAnalyzer の内部に閉じています。曲全体の analyze は各中間表現を一度だけ計算し、BPM、キー、コード、セクションの結果で使い回します。単機能のエントリポイントは呼び出しをまたぐキャッシュを持たないため、それぞれが必要なものをサンプルから作り直します。
ブラウザデモは対話的な利用を前提にしています。ただし、それぞれが見せている役割は少し違います。
| デモ | 主な役割 |
|---|---|
| 楽曲解析スタジオ | ファイル全体の MIR。BPM と局所テンポの曲線、キー、ローマ数字の機能付きのコード、セクション、A4 のチューニング推定をまとめて解析します。 |
| リアルタイム系の表示 | StreamAnalyzer 経由で、BPM／キー／コードを時間とともに更新しながら推定します。 |
| マスタリングスタジオ | ラウドネス計測、リファレンス比較、レポート出力など、計測寄りの API を扱います。 |
同じライブラリの上に役割の違うデモを載せることで、解析と仕上げの両方で何を再利用できるかを示しています。
関連: イントロダクション、オーディオ基礎、JavaScript API、ルーム音響解析、DSP 実装解説、librosa 互換性