イントロダクション
このページでは、基本用語と libsonare が扱う範囲の地図を示します。先に動かしてみたい場合は はじめに へ進み、あとで戻ってきてください。作りたいものが決まっているなら、学習順ガイド が最短ルートを選びます。各用語をさらに深く知りたくなったら、用語集 と MIR の全体像 を参照してください。
このページで身につくこと
このページを読むと、次のことを説明・判断できるようになります。
- libsonare が何であり、どの種類の音楽／音声ツールを支えるかを説明できる。
- 波形からスペクトログラム、特徴量、高レベル楽曲解析へ進む MIR（Music Information Retrieval、音楽情報検索）パイプラインの基本を理解できる。
- 解析、編集、ミキシング、マスタリング、リアルタイムストリーミング、ルーム音響、内蔵シンセサイザー、ヘッドレス DAW ランタイム、逆変換特徴量を区別できる。
- DSP の前提知識がなくても、次に 学習順ガイド から読むページを選べる。
libsonare とは？
libsonare は、ブラウザネイティブおよびネイティブ環境の音楽ツール向けの、外部依存のないオーディオエンジンです。既存の音声を解析する処理（テンポ、キー、コード）から、新しい音声を作り出す処理（ミキシング、マスタリング、MIDI をシーケンスして完成トラックに仕上げる）まで、一連の流れ全体をカバーします。
libsonare が扱う領域は大きく分けると次のとおりです。
| 領域 | libsonare でできること | 次に読む |
|---|---|---|
| 音楽情報検索（MIR） | テンポ、キー、コード、ビート、ダウンビート、拍子、構成、メロディ、音色、ダイナミクスを抽出する | 楽曲解析 |
| 音源分離 | 録音を倍音成分と打撃成分（HPSS）や、ラベルのないスペクトル成分（NMF）に分ける。学習済みの分離モデルではなく信号処理 | 音源分離 |
| 音声から MIDI | モノラルの録音をノートイベントに採譜する。プロジェクトの MIDI クリップへ直接書き込むこともできる | 音声から MIDI |
| 編集とクリエイティブ FX | ピッチ、タイミング、声質、リバーブ、モジュレーション系エフェクトを扱う | 編集 DSP、エフェクトインサート |
| リペア | ノイズ、ハム、クリップ、クリック、クラックル、拡散残響を測定して抑える | オーディオリペアの流れ |
| ミキシング | リアルタイム安全なミキサー、ルーティング、バス、センド、メーターを構築する | ミキシングエンジン |
| マスタリング | 放送品質のマスタリングプロセッサと、ラウドネス／True Peak の処理 | マスタリングプロセッサ、マスタリングアシスタント |
| 内蔵シンセサイザーと MIDI | MIDI のノートを、17 種のエンジン（うち 11 が物理モデル）を備えた内蔵シンセサイザー（サンプルファイル不要の GM と GS フォールバックバンク付き）か、SoundFont 2 プレイヤー（SoundFont は自分で用意する、サンプリングした楽器をまとめたファイル）で音にする | サンプルを同梱しない理由は 音源方式、その先は 内蔵シンセサイザー |
| ヘッドレス DAW ランタイム | オーディオ／MIDI トラックでプロジェクトを編集し、MIDI をシーケンスし、バウンス（プロジェクトを音声ファイルに書き出すこと）やリアルタイム再生を行う | プロジェクト編集、プロジェクトのバウンス |
| ストリーミングとリアルタイム | 届いた音声をブロック単位で解析し、ライブ MIDI 付きのトランスポート（再生・停止・位置を管理する時計）を動かす | リアルタイムとストリーミング |
| ルーム音響 | 部屋の残響・明瞭度の測定や推定、RIR（ルームインパルス応答）合成、ルームモーフィングを行う | ルーム音響解析 |
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）は音声の録音・編集・制作を行うソフトウェアです。DAW プラグインは、そこにエフェクト、楽器、解析ツールを追加する拡張モジュールです。
音声研究者 — Python で librosa を使用している方向けに、互換性のある API とアルゴリズムを提供します。重いパイプラインはネイティブ C++ で実行でき、ブラウザでも動作します。
ゲーム / インタラクティブメディア開発者 — ストリーミング API を使って、リズムゲーム、音楽ビジュアライザー、アダプティブオーディオシステム向けのリアルタイム音楽解析を組み込めます。
音声解析の仕組み
音声解析は一発でできるものではなく、各段階が前の段階の出力を利用する パイプライン です。そのため、ある機能が別の機能に依存します。ここでは要点だけを述べます。全体の地図と各機能のデモは MIR の全体像 にあります。
ステージ 1: スペクトル解析。 生の音声は波形、つまりサンプルと呼ぶ振幅値の列で、1 秒が何サンプルでできているかをサンプルレートと呼びます（サンプル、デシベル、周波数の基礎は オーディオ基礎 でゼロから説明しています）。短時間フーリエ変換（STFT）は、波形を短い重なり合う窓に切り分け、各窓にどの周波数が含まれているかを測り、周波数を時間に対して描いた地図である スペクトログラム を作ります。設定する数値は 3 つです。サンプルレート（CD 品質なら 44,100 Hz）は、扱える最高周波数をその半分の 22,050 Hz（ナイキスト周波数）に制限します。FFT サイズ（n_fft、よくある値は 2048）は 1 窓のサンプル数で、大きいほど音の高さを細かく分けられますが時間は粗くなります。ホップ長（hop_length、よくある値は 512）は窓を 1 回に動かす幅で、小さいほど時間の詳細が増え、計算量も増えます。各窓の端をなだらかにする窓関数は スペクトログラムと STFT で説明しています。
ステージ 2: 特徴量抽出。 スペクトログラムから、音の特定の側面を捉える 特徴量 を計算します。クロマは、12 の音名（C, C#, ... B）がそれぞれどれだけ鳴っているかをオクターブを無視して表したもので、キーとコード解析の基盤です。オンセット包絡線は新しい音や打撃の始まりでピークになり、テンポとビート追跡の入力になります。メルスペクトログラムは周波数軸を聴覚に合わせた間隔にしたもので、MFCC はそれを音色のコンパクトな要約にまとめます。CQT / VQT は、等幅のビンではなく 1 半音ごとに 1 ビンを持ちます。これらは単体でも使え（メルスペクトログラムは機械学習モデルの典型的な入力です）、次のステージへの入力にもなります。
ステージ 3: 音楽解析。 多くの人が求める結果は、特徴量の 上に 構築されます。クロマからはキー検出とコード認識、オンセット包絡線からは BPM とビート追跡、音色と和声からはセクション検出（イントロ、A メロ、サビ）、波形そのものからはピッチ追跡（メロディの F0）が得られます。各段階が公開されているので、答えだけで終わらせず、低レベルの特徴量を独自の解析に使ったり ML パイプラインに組み込んだりできます。
ルーム音響解析と逆変換特徴量
解析の中には、楽曲そのものではなく録音空間を扱うものもあります。インパルス応答（IR）は、1 回のクリックに対する部屋の返事を録音したもので、部屋の響きだけが入っています。残響は測定できる速さで減衰するので、IR から、あるいは精度は落ちますが減衰する余韻を含む通常の音声から、libsonare は部屋の特徴を数値で表します。
| 手元にあるもの | 得られるもの | 参照 |
|---|---|---|
| クリーンなインパルス応答 | 部屋がどれだけ長く響くか（RT60、EDT）と、どれだけ明瞭に聞こえるか（明瞭度、定義度）の直接測定 | ルーム音響解析 |
| 通常の音声 | 信頼度付きのルーム音響の手がかり、または音から推定した実用上の部屋モデルである 等価ルーム（体積、寸法、吸音率） | ルーム音響解析 |
| 箱として表した部屋（長さ・幅・高さ） | 合成したルームインパルス応答、または目標ルームの響きを音作り効果として音声に適用するルームモーフィング（残響除去ではありません。モノラルとステレオに対応） | ルーム音響解析 |
ルーム音響の略語を先に押さえる
RT60 は残響が 60 dB 小さくなるまでの時間、EDT は聴感に近い初期減衰時間です。
C50 / C80 は音声／音楽の明瞭度、D50 は最初の 50 ms に届くエネルギー比率です。
等価ルームの推定は DRR（直接音対残響音比：直接音が残響に対してどれだけ大きいか。音源距離）も返します。
ここでは「部屋の響き方を数値化する指標」とだけ理解しておけば十分です。
また、デバッグや ML ワークフロー向けの逆変換ヘルパーも公開しています。メルスペクトログラムや MFCC が手元にあるとき、これらのヘルパーは変換を逆向きに実行して、近似的なスペクトルや、その特徴量が「どう聞こえるか」のおおまかなプレビューを得ます。ML パイプラインの妥当性確認に役立ちます。これは復元ツールではなく、ロスのある確認用プレビューです。詳細は 逆変換特徴量 を参照してください。
オーディオエフェクト
libsonare はスペクトル表現を操作する音声処理機能も提供します：
- HPSS（Harmonic / Percussive Source Separation。倍音成分と打撃成分の分離） — スペクトログラム上のメディアンフィルターによる処理により、音声を倍音成分（ボーカル・メロディ・持続音）と打撃成分（ドラム・打楽器・過渡音）に分離します。解析精度を上げる前処理としてよく使われます。ほかの分離方式とあわせて 音源分離 で扱います。
- タイムストレッチ／ピッチシフト — 位相ボコーダ（短い窓を重ねたスペクトルのフレームから信号を組み立て直す処理）とリサンプリングを組み合わせて、テンポや音の高さを変えます。
- 編集 DSP — ターゲット MIDI ノートへのピッチ補正、ノート区間のストレッチ、ピッチとフォルマントを扱うボイスチェンジを提供します（編集 DSP）。
- クリエイティブ FX / インサート — リバーブ、コーラス、フランジャー、フェイザー、ステレオディレイなどの音作り系 DSP です。クリエイティブ FX を有効にしたビルドで使えます。インサートとパラメータの一覧は エフェクトインサート にあります。
リアルタイムストリーミング
StreamAnalyzer は同じパイプラインを音声 チャンク単位 で低レイテンシ実行します。
リアルタイム可視化やライブ解析に適したフレーム単位の特徴量を出力し、BPM、キー、現在のコード、コード進行（各小節でもっとも多く聞こえたコード）の推定を更新し続けます。
ブラウザでは、Web Audio API の AudioWorklet と組み合わせてリアルタイム処理できます。どちらも リアルタイムとストリーミング で扱います。
ミキシングとルーティング
libsonare のミキシングエンジンは、チャンネルストリップ、パンモード、ステレオ幅、センド、FX バス、VCA グループを提供します。さらに、シーンプリセット、オートメーションレーン、ゴニオメーター／True Peak 計測、オフラインステレオレンダーも扱えます。
一回きりの解析やマスタリングではなく、保持できるミキサーシーンが必要な場合は ミキシングエンジン を参照してください。
ミキサー用語をまとめて
「センド」はチャンネルのコピーを共有エフェクトへ送る仕組み、「バス」は複数チャンネルがまとまって流れ込むサブミックス、「VCA グループ」は 1 本のフェーダーで多数のチャンネルの音量をまとめて操作する仕組みです。「ゴニオメーター」はステレオの広がりを可視化し、「True Peak」計測はサンプル間ピーク（ISP）、つまりサンプルとサンプルの間にだけ現れるピークを捉えます。
プラットフォーム対応
| プラットフォーム | インターフェース | ユースケース |
|---|---|---|
| ブラウザ | JavaScript/TypeScript（WebAssembly） | Web アプリ、クライアントサイド解析 |
| Node.js | JavaScript/TypeScript（WebAssembly） | サーバーサイド処理 |
| Node.js | JavaScript/TypeScript（N-API ネイティブアドオン） | 高性能なサーバーサイド処理 |
| Python | Python（ネイティブ C API を ctypes 経由で利用） | データサイエンス、スクリプティング、librosa からの移行 |
| Linux / macOS | C++ | ネイティブアプリ、CLI ツール |
| その他（C API 経由） | C | 他言語との FFI 連携 |
WebAssembly と JavaScript のフルバンドルは約 8,500 KB、gzip 圧縮後は 2,792 KB です。解析だけを行うページなら、ずっと小さい解析専用エントリを読み込めます。内訳は WebAssembly ガイド を参照してください。
librosa との関係
librosa は MIR コミュニティにおけるデファクトスタンダードの Python ライブラリです。libsonare は、Python が使えない環境、ネイティブ統合が必要な環境、単一の C++ コアを使いたい場面向けに、librosa と似た MIR の基本部品を提供します。
- よく使う 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 リポジトリ へお願いします。
- 「テスト済み」の意味 — 参照テストでカバーされている機能は 実装検証 に一覧があり、バインディング間の既知の挙動差は バインディング対応表 に記録されています。そこに載っていない機能は、依存する前にお手元の素材で検証してください。
次のステップ
これから何をしたいかに合わせて、道を選んでください。
ブラウザで試したい
どのデモもエンジンをブラウザ内で動かし、何もアップロードしません。
| やりたいこと | 試す | 次に読む |
|---|---|---|
| 曲から BPM、キー、コード、セクションを読み取る | 楽曲解析スタジオ | はじめに |
| トラックをマスタリング、ミックスする | マスタリングスタジオ、ミキシングスタジオ | マスタリングアシスタント、ミキシングエンジン |
| MIDI を音にする | シンセプレイグラウンド | 音源方式 |
| 録音をノートに採譜する、録音を編集・リペアする | ピアノ採譜 | 音声から MIDI、オーディオリペアの流れ |
ラウドネス、LUFS、True Peak とは？
マスタリングのデモはこれらを表示します。デジタルのレベルは、フルスケールを基準にしたデシベル（dBFS）で測ります。0 dBFS はサンプルが取れる最大の値なので、ふつうのレベルは負の数になります。デシベルの基礎は オーディオ基礎 で説明しています。
LUFS（Loudness Units relative to Full Scale）は、配信・放送で使う番組ラウドネスの標準化された推定値です。2 曲の積分 LUFS を合わせると比較の出発点になりますが、周波数特性やダイナミクスが違えば、同じ大きさには聞こえないこともあります。True Peak（トゥルーピーク）は、サンプル間のピークを含む再構成波形の最大レベルを推定します。サンプルピークメーターでは見落とすピークが、再生やエンコード時の歪みにつながることがあります。
何かを作りたい
- はじめに — 普段使っている実行環境で、短いプログラム 1 つから最初の結果を得る
- 学習順ガイド — 10 の分野を目的別に辿り、作りたいもののために書かれたガイドを 1 つ開く
- 使用例 — 実行環境ごとの小さな動作パターン。読むより写すためのページ
- 機能マップ — 機能ファミリーがどこにあり、どのバインディングから使えるか