イントロダクション
初めて libsonare を使う場合は、このページで基本用語を確認してください。そのあと 学習順ガイド で、自分の目的に合う最短ルートを選びます。
ここでの説明は意図的に簡潔にしてあります。各用語をさらに深く知りたくなったら、用語集 と MIR の全体像 を参照してください。
このページで身につくこと
このページを読むと、次のことを説明・判断できるようになります。
- libsonare が何であり、どの種類の音楽／音声ツールを支えるかを説明できる。
- 波形からスペクトログラム、特徴量、高レベル楽曲解析へ進む MIR パイプラインの基本を理解できる。
- 解析、編集、ミキシング、マスタリング、リアルタイムストリーミング、室内音響、内蔵インストゥルメント、ヘッドレス DAW ランタイム、逆変換特徴量を区別できる。
- DSP の前提知識がなくても、次に 学習順ガイド から読むページを選べる。
libsonare とは？
libsonare は、ブラウザネイティブおよびネイティブ環境の音楽ツール向けの外部依存なしオーディオエンジンです。既存の音声を解析する処理（テンポ、キー、コード）から、新しい音声を作り出す処理（ミキシング、マスタリング、MIDI をシーケンスして完成トラックに仕上げる）まで、一連の流れ全体をカバーします。
libsonare が扱う領域は大きく分けると次の通りです。
| 領域 | libsonare でできること |
|---|---|
| 音楽情報検索（MIR） | テンポ、キー、コード、ビート、ダウンビート、拍子、構成、メロディ、音色、ダイナミクスを抽出する |
| 室内音響 | 部屋の残響・明瞭度の測定や推定、RIR 合成、ルームモーフィングを行う |
| マスタリング | 配信向けのマスタリング処理、ラウドネス、トゥルーピークを扱う |
| ミキシング | リアルタイムセーフなミキサー、ルーティング、バス、センド、メーターを構築する |
| 編集とクリエイティブ FX | ピッチ、タイミング、声質、リバーブ、モジュレーション系エフェクトを扱う |
| 内蔵インストゥルメントと MIDI | GM フォールバックバンクを備えたマルチエンジンシンセや SoundFont 2 プレイヤーで MIDI をレンダリングする（組み込み楽器、SoundFont 2 プレイヤー、MIDI 入力） |
| ヘッドレス DAW ランタイム | オーディオ／MIDI トラックでプロジェクトを編集し、MIDI をシーケンスし、バウンスやリアルタイム再生を行う（プロジェクト編集、プロジェクトバウンス、リアルタイムとストリーミング） |
ラウドネス、LUFS、トゥルーピークとは？
LUFS（Loudness Units Full Scale）は配信・放送で標準的に使われる体感ラウドネスの指標で、同じ LUFS の 2 曲は同じくらいの大きさに聞こえます。トゥルーピークは、サンプルとサンプルの間で発生して通常のピークメーターでは見落とされるピークまで含めた最大レベルを測ります。再生時の歪みを避けるために重要です。
libsonare は C++17 で書かれており高速に動作するほか、WebAssembly にコンパイルできるため、サーバーを介さずブラウザ上で直接同じプロセッサを実行できます。
WebAssembly とは？
WebAssembly（WASM）は、ウェブブラウザ上でネイティブに近い速度で実行されるバイナリ命令形式です。
C++ などの言語で書かれたコードをコンパイルし、サーバーやインストールなしにブラウザ上で実行できます。
libsonare はこれを活用して、C++ レベルの音声解析パフォーマンスを Web アプリケーションに直接提供します。
音楽情報検索（MIR）とは？
音楽情報検索（MIR）は、音楽から意味のある情報を抽出する研究分野です。人間は曲を聴くだけでテンポを感じ取り、コードの変化を認識し、楽曲の構造を把握できます。MIR はこれと同じことをコンピュータで実現することを目指しています。
代表的な MIR タスク：
| タスク | 回答する問い |
|---|---|
| テンポ推定 | この曲の速さは？（例：120 BPM） |
| キー検出 | この曲の調は？（例：ハ長調） |
| ビート追跡 | ビートはいつ鳴っているか？ |
| コード認識 | いつ、どのコードが鳴っている？ |
| 構造解析 | Aメロ、サビ、ブリッジはどこ？ |
| ピッチ追跡 | 歌われている・演奏されている音は？ |
BPM とは？
BPM は beats per minute（1 分あたりの拍数）の略で、曲の鼓動の速さを表します。60 BPM なら 1 秒に 1 拍で、多くのポップスは 90〜130 BPM 前後です。
libsonare はこれらすべての機能を単一のライブラリで提供します。
誰のためのライブラリ？
libsonare は音楽関連アプリケーションを開発するデベロッパー向けに設計されています。
Web アプリ開発者 — バックエンドなしで音声解析機能をアプリに追加できます。DJ ツールの BPM 検出、練習アプリのコード表示、自動楽曲構造ビューアなどを、ブラウザ上の WebAssembly でクライアントサイド実行できます。
音楽ツール制作者 — DAW プラグイン、コード検出器、自動採譜ツール、ブラウザミキサー、マスタリングワークフロー、音楽教育ソフトウェアを構築できます。libsonare が解析・ミキシング・マスタリングのエンジンを提供するので、ユーザー体験の構築に集中できます。
DAW とは？
DAW（Digital Audio Workstation）は音声の録音・編集・制作を行うソフトウェアです。Ableton Live、Logic Pro、FL Studio、GarageBand などが代表例です。DAW プラグインはこれらのアプリケーションにエフェクト、楽器、解析ツールなどの機能を追加する拡張モジュールです。
音声研究者 — Python で librosa を使用している方に、互換性のある API とアルゴリズムを提供しつつ、重いパイプラインをネイティブ C++ で実行でき、ブラウザでも動作します。
ゲーム / インタラクティブメディア開発者 — ストリーミング API を使って、リズムゲーム、音楽ビジュアライザー、アダプティブオーディオシステム向けのリアルタイム音楽解析を組み込めます。
ブラウザで試す
デモ一覧 からブラウザ内デモを選べます。MIR 機能は 楽曲分析スタジオ で、アップロード不要の WAV マスタリングは マスタリングスタジオ で試せます。
音声解析の仕組み
音声解析は一発でできるものではなく、各段階が前の段階の出力を利用する パイプライン です。この流れを理解すると、libsonare が内部で何をしているのか、なぜ特定の機能が他の機能に依存するのかが見えてきます。
このセクションは概要、詳しい地図は MIR の全体像
ここではパイプラインをざっと一巡します。各特徴量がどう関係するかの、相互リンク付きの詳しい地図と「どの問いに、どの機能か」の表は MIR の全体像 を参照してください。
音声波形
↓
スペクトル解析（STFT）
↓
特徴量抽出（クロマ、オンセット包絡線、メルスペクトログラム、...）
↓
音楽解析（キー、コード、BPM、ビート、セクション、...）ステージ 1: スペクトル解析
生の音声は時間に沿った振幅値の列、つまり波形です。
音楽的な意味を抽出するには、まずこれを スペクトログラム に変換します。短時間フーリエ変換（STFT）を使い、音声を短いオーバーラップする窓に分割し、各窓の周波数成分を計算します。
結果は「各時刻にどの周波数がどれだけ含まれているか」を示す 2 次元マップになります。
フーリエ変換とは？
フーリエ変換は信号をその構成周波数に分解する手法です。プリズムが白色光を虹色に分けるようなものです。
音声は様々な周波数が異なる振幅で重ね合わさったものです。フーリエ変換によって、どの周波数がどの程度含まれているかがわかります。
短時間フーリエ変換（STFT）は、これを音声の重なり合う窓に繰り返し適用します。これにより、周波数成分の時間変化を可視化できます。
このスペクトログラムが、以降すべての解析の基盤です。
ステージ 2: 特徴量抽出
スペクトログラムから、libsonare は音声の特定の側面を捉えるための 特徴量 を計算します：
- クロマ — すべての周波数を 12 のピッチクラス（C, C#, D, ..., B）に畳み込み、各時刻でどの音が目立っているかを示します。キー推定とコード解析の基盤です。
ピッチクラスとは？
ピッチクラスは、同じ音名のすべてのオクターブをまとめたグループです。例えば、C2、C3、C4 などすべての「ド」はピッチクラス「C」に属します。
西洋音楽には 12 のピッチクラスがあります: C, C#, D, D#, E, F, F#, G, G#, A, A#, B。
クロマ特徴量はオクターブを無視して、これら 12 クラスのエネルギー分布として音声を表現します。
- オンセット包絡線 — フレーム間のスペクトルエネルギーの変化量を測定し、新しい音や打撃音の開始点を強調します。ビート・リズム解析の入力になります。
オンセットとは？
オンセットとは音楽的イベントの始まり、つまり音が鳴り始める瞬間です。鍵盤を叩いた瞬間、ドラムを打った瞬間、新しい音が始まった瞬間がオンセットです。
オンセット包絡線は、これらの瞬間にピークを持つ連続曲線です。そのピークを検出すると、個々の音の発音タイミングを特定できます。
この情報はテンポ推定やビート位置の特定に繋がります。
- メルスペクトログラム — スペクトログラムをメル尺度に再マッピングします。メル尺度は人間のピッチ知覚に合わせたもので、200 Hz と 400 Hz の差と 2000 Hz と 4000 Hz の差を同じ「距離」として扱います。オーディオ ML で広く使用されます。
メル尺度とは？
メル尺度はピッチの知覚的な尺度です。人間は周波数を線形には知覚しません。
100 Hz から 200 Hz への変化は大きく感じますが、5000 Hz から 5100 Hz はほとんど同じに聞こえます。
メル尺度は高い周波数を圧縮して、この知覚に合わせます。メルスペクトログラムはこの尺度を周波数軸に使うため、人間の聴覚に関連するタスクに向いています。
- MFCC（メル周波数ケプストラム係数） — メルスペクトログラムから導出されるスペクトル形状のコンパクトな表現。音色や音楽テクスチャの分類に有用です。
音色（ティンバー）とは？
音色とは、同じ音の高さ・同じ音量でもピアノとギターの音が異なって聞こえる要因のことです。音の「色」や「質感」とも言え、倍音の相対的な強さによって決まります。MFCC はこのスペクトル形状をコンパクトに表現するため、異なる楽器、声、音の種類を区別するのに有用です。
- CQT / VQT — 標準的なフーリエ変換（FFT。上記の STFT を支えるものと同じ計算）ではどの周波数でも分解能の幅が一定ですが、これらの変換は音楽的なピッチに対応した分解能を持ちます。
なぜ音楽のピッチには特別な周波数分解能が必要？
音楽の音は対数的に配置されています。各オクターブで周波数が倍になります（A3 = 220 Hz、A4 = 440 Hz、A5 = 880 Hz）。
標準 FFT は等間隔の周波数ビンを使います。そのため、低音の区別が不十分になり、高音では必要以上に細かい分解能になります。
定Q変換（CQT）は、ビンを対数的に配置して音楽のピッチに合わせます。可変Q変換（VQT）はこれを拡張し、分解能を調整可能にしたものです。
これらの特徴量は単体でも有用です（例：メルスペクトログラムを機械学習モデルに入力）が、次のステージの高レベル解析への入力としても機能します。
ステージ 3: 音楽解析
多くのユーザーが求める高レベルの結果は、ステージ 2 の特徴量の 上に 構築されます：
| 解析 | 構築元 | 処理内容 |
|---|---|---|
| キー検出 | クロマ → Krumhansl-Schmuckler アルゴリズム | クロマプロファイルをキーテンプレートと比較し調を判定（例：「イ短調」） |
| コード認識 | クロマ → テンプレートマッチング | クロマフレームを 192 種類のコードテンプレート（16 クオリティ × 12 ルート）と照合し時系列コードを識別 |
| BPM 検出 | オンセット包絡線 → テンポグラム + 自己相関 | オンセット強度の周期的パターンを見つけてテンポを推定 |
| ビート追跡 | オンセット包絡線 → 動的計画法 | リズムの規則性を使ってビート位置を推定 |
| セクション検出 | クロマ + スペクトル特徴量 → 自己類似性解析 | 音楽的性格が変わる境界を検出し、イントロ・Aメロ・サビ等に分割 |
| ピッチ追跡 | 波形 → YIN / pYIN アルゴリズム | モノフォニック音声の基本周波数（F0）を推定しメロディを抽出 |
テンポグラムとは？
テンポグラムは時間-テンポ表現で、各時刻における異なるテンポ候補の強さを示します。オンセット包絡線の周期的パターンを自己相関（信号が時間シフトした自分自身とどれだけ似ているかを測定）で分析して算出します。テンポグラムのピークが支配的なテンポを示します。
自己類似性解析とは？
自己類似性解析は、楽曲の各部分を他のすべての部分と比較します。その結果として、任意の 2 つの時点がどれだけ似ているかを示す行列を構築します。
ポップスでは、サビ同士は似ている傾向がありますが、A メロとは異なります。
この行列のブロック状パターンを見つけることで、libsonare は音楽がある構造から別の構造に移行するセクション境界を特定できます。
基本周波数（F0）とは？
基本周波数（F0）は周期的な音の最も低い周波数で、知覚されるピッチを決定します。歌手が A4 の音を歌うとき、F0 は 440 Hz ですが、多くの高次倍音（880 Hz、1320 Hz、...）も同時に存在します。YIN や pYIN などのピッチ追跡アルゴリズムはこの F0 を時間軸に沿って推定し、音声からメロディラインを抽出します。
この階層的な設計により、libsonare は結果だけでなく各段階を公開しています。低レベルの特徴量を独自の解析に使ったり、ML パイプラインに組み込めます。
ルーム音響解析と逆変換特徴量
解析の中には、楽曲そのものではなく録音空間を扱うものもあります。
新しく出てくるルーム音響用語
等価ルーム は、音声から推定した実用上の部屋モデルです。シューボックス形状 は、長さ・幅・高さで表す直方体の部屋です。ルームモーフィング は、目標ルームの響きを音作り効果として適用する処理で、残響除去ではありません。
| 入口 | 入力 | 結果 |
|---|---|---|
analyzeImpulseResponse / analyze_impulse_response | クリーンなインパルスレスポンス | RT60、EDT、明瞭度、定義度を直接測定します。 |
detectAcoustic / detect_acoustic | 通常音声 | ルーム音響の手がかりを推定し、信頼度を返します。 |
estimateRoom / estimate_room | 通常音声またはインパルスレスポンス | 体積、寸法、吸音率、DRR、信頼度を含む等価ルームを返します。 |
synthesizeRir / synthesize_rir | シューボックス形状 | 決定論的なモノラルのルームインパルスレスポンスを返します。 |
roomMorph / room_morph | 音声と目標ルーム形状 | 残響除去ではなく、音作り向けのルームモーフィングを行います。 |
ルーム音響の略語を先に押さえる
RT60 は残響が 60 dB 小さくなるまでの時間、EDT は聴感に近い初期減衰時間です。
C50 / C80 は音声／音楽の明瞭度、D50 は最初の 50 ms に届くエネルギー比率です。
ここでは「部屋の響き方を数値化する指標」とだけ理解しておけば十分です。詳しい読み方は ルーム音響解析 で説明します。
使い分けは ルーム音響解析 を参照してください。
また、デバッグや ML ワークフロー向けの逆変換ヘルパーも公開しています。メルスペクトログラムや MFCC が手元にあるとき、これらのヘルパーは変換を逆向きに実行して、近似的なスペクトルや、その特徴量が「どう聞こえるか」のおおまかなプレビューを取り戻します。ML パイプラインの妥当性確認に役立ちます。これは復元ツールではなく、ロスのある確認用プレビューです。詳細は 逆変換特徴量 を参照してください。
オーディオエフェクト
libsonare はスペクトル表現を操作する音声処理機能も提供します：
- HPSS（Harmonic / Percussive Source Separation。倍音成分と打撃成分の分離） — スペクトログラム上のメディアンフィルタリングにより、音声を倍音成分（ボーカル・メロディ・持続音）と打撃成分（ドラム・打楽器・過渡音）に分離します。解析精度を上げる前処理としてよく使われます。
倍音成分と打撃成分とは？
スペクトログラム上で、倍音的な音（ボーカル、弦楽器、持続音）は水平線として現れます。時間方向に安定した周波数を持つためです。
打撃的な音（ドラム、クリック、過渡音）は垂直線として現れます。瞬間的に多くの周波数を含むためです。
HPSS はこの違いをメディアンフィルタで利用します。水平方向のメディアンフィルタが倍音部分を、垂直方向のメディアンフィルタが打撃部分を抽出します。
- タイムストレッチ／ピッチシフト — 位相ボコーダとリサンプリングを組み合わせて、テンポ変更や移調を行います。
- 編集 DSP — ターゲット MIDI ノートへのピッチ補正、ノート区間のストレッチ、ピッチとフォルマントを扱うボイスチェンジを提供します。
- クリエイティブ FX / インサート — リバーブインサート、コーラス、フランジャー、フェイザー、ステレオディレイなどの音作り系 DSP です。
クリエイティブ FX の公開範囲
クリエイティブ FX 有効ビルドでは、ミキサー／マスタリングのインサートファクトリからリバーブインサートプロセッサ（effects.reverb.*）を使えます。
コーラス、フランジャー、フェイザー、ステレオディレイの DSP モジュールはソースツリーにあります。ただし、現行の JS/Python ではトップレベルの単独ヘルパーとしては公開されていません。
ダッキングは一括編集ヘルパーではなく、dynamics.duckingProcessor やミキサールーティングとして扱います。
リアルタイムストリーミング
StreamAnalyzer は同じパイプラインを音声 チャンク単位 で低レイテンシ実行します。
リアルタイム可視化やライブ解析に適したフレーム単位の特徴量を出力します。プログレッシブ推定には BPM、キー、現在のコード、コード進行、小節単位のコード投票、パターンスコアが含まれます。
ブラウザでは、Web Audio API の AudioWorklet と組み合わせてリアルタイム処理できます。
ミキシングとルーティング
libsonare のミキシングエンジンは、チャンネルストリップ、パンモード、ステレオ幅、センド、FX バス、VCA グループを提供します。さらに、シーンプリセット、オートメーションレーン、ゴニオメーター／トゥルーピーク計測、オフラインステレオレンダーも扱えます。
一回きりの解析やマスタリングではなく、保持できるミキサーシーンが必要な場合は ミキシングエンジン を参照してください。
ミキサー用語をまとめて
「センド」はチャンネルのコピーを共有エフェクトへ送る仕組み、「バス」は複数チャンネルがまとまって流れ込むサブミックス、「VCA グループ」は 1 本のフェーダーで多数のチャンネルの音量をまとめて操作する仕組みです。「ゴニオメーター」はステレオの広がりを可視化し、「トゥルーピーク」計測はサンプル間にだけ現れるピークを捉えます。
プラットフォーム対応
| プラットフォーム | インターフェース | ユースケース |
|---|---|---|
| ブラウザ | JavaScript/TypeScript（WebAssembly） | Web アプリ、クライアントサイド解析 |
| Node.js | JavaScript/TypeScript（WebAssembly） | サーバーサイド処理 |
| Node.js | JavaScript/TypeScript（N-API ネイティブアドオン） | 高性能なサーバーサイド処理 |
| Linux / macOS | C++ | ネイティブアプリ、CLI ツール |
| Python | Python（ネイティブ C API を ctypes 経由で利用） | スクリプト、研究、CLI |
| その他（C API 経由） | C | 他言語との FFI 連携 |
現在のサイト同梱版では、WebAssembly / JavaScript アセットは圧縮前で合計約 3,210 KB です。内訳は WebAssembly ガイド を参照してください。
librosa との関係
librosa は MIR コミュニティにおけるデファクトスタンダードの Python ライブラリです。libsonare は、Python が使えない環境、ネイティブ統合が必要な環境、単一の C++ コアを使いたい場面向けに、librosa と似た MIR の基本部品を提供します。
サンプルレート、FFT サイズ、ホップ長とは？
音声解析の基本パラメータです。
| パラメータ | 意味 | トレードオフ |
|---|---|---|
| サンプルレート | 音声が 1 秒あたり何回の振幅測定値を持つか（例：CD 品質は 44,100 Hz） | 高いほど高域まで扱えますが、データ量が増えます |
FFT サイズ（n_fft） | 各解析窓のサンプル数 | 大きいほど周波数分解能が高く、時間分解能は低くなります |
ホップ長（hop_length） | 窓を何サンプルずつ移動させるか | 小さいほど時間的な詳細が得られますが、計算量が増えます |
libsonare は通常、呼び出し側がサンプルレートを明示します。n_fft=2048、hop_length=512 などの一般的な DSP パラメータは、librosa でよく使われる値に寄せています。
- よく使う DSP パラメータと API は、実用上可能な範囲で librosa に近づけています
- STFT、メルスペクトログラム、MFCC、クロマなどのコア特徴量は librosa 参照テストで確認しています
- 関数名と API パターンを意図的に類似させ、移行を容易に
さらに libsonare は librosa の範囲を超えた コード認識、セクション検出、音色解析、リアルタイムストリーミング も提供します。これらは Python エコシステムでは通常別々のツールとして提供される機能です。
詳細な比較と移行ガイドは librosa 互換性 を参照してください。
プロジェクトの状況とサポート
libsonare は単独の開発者が活発に開発しているオープンソースプロジェクト（Apache-2.0）です。バージョンは 1.0 を超えており、リリースにはセマンティックバージョニングのタグが付きますが、若いライブラリとして扱ってください。アップグレード前にリリースノートを確認し、本番環境ではバージョンを固定することをおすすめします。
- リリースと変更点 — すべてのリリースは GitHub Releases にタグ付きで公開され、変更内容のノートが付きます。npm と PyPI のパッケージも同じタグに追従します。
- バグ報告と質問 — libsonare の issue トラッカー に issue を立ててください。このドキュメントサイトやデモの問題は homepage リポジトリ へお願いします。
- 「テスト済み」の意味 — 参照テストでカバーされている機能は 実装検証 に一覧があり、バインディング間の既知の挙動差は バインディング対応表 に記録されています。そこに載っていない機能は、依存する前にお手元の素材で検証してください。