学習順ガイド
このページは、libsonare のドキュメントを初学者向けに読むための道案内です。DSP、MIR、WebAssembly、マスタリング用語を最初から理解している必要はありません。
最初に出る略語
DSP は音を数値として測定・加工する信号処理、MIR は BPM・キー・コードなどを音楽から読み取る処理です。
WASM / WebAssembly はブラウザで使う実行形式、API はアプリから呼ぶ関数やクラス、CLI はターミナルで使うコマンドです。
ここでは用語を完全に覚えるより、「どの種類のページへ進むか」を選べれば十分です。
ドキュメントを先頭から順に読む場合は、次の順序で読むと前提が積み上がります。
- イントロダクション で用語と音声解析パイプラインの全体像を読む。
- 学習順ガイド で、解析・ストリーミング・編集・ミキシング・マスタリング・研究用途のどれを作るか決める。
- はじめに、インストール、使用例 で小さなプログラムを 1 つ動かす。
- 機能マップ で必要な API ファミリーを探す。
- 作りたいもの別 から該当する機能ガイドを 1 つ読む。
- 利用環境別 API から実行環境に合うリファレンスを 1 つ読む。
- 実装詳細、アルゴリズム根拠、検証範囲、性能が必要になったときだけ、詳説ページを読む。
作りたいものから選ぶ
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| BPM、キー、コード、セクションを表示するブラウザアプリ | はじめに | WebAssembly ガイド、JavaScript API |
| 音声解析を行う Python スクリプトやノートブック | はじめに | Python API |
| ターミナルでの簡易確認やバッチ解析 | はじめに | CLI リファレンス |
| ピッチ、長さ、声質、音源分離の編集 | 編集 DSP | JavaScript API |
| 領域指定のスペクトル編集（時間×周波数の矩形を減衰・ミュート・ゲイン・修復） | スペクトル編集 | 編集 DSP |
| ブラウザまたはネイティブのミキサー | ミキシングエンジン | ミキシングシーン JSON |
| マスタリング UI や自動マスタリング | マスタリングアシスタント | マスタリングプロセッサ |
| MIDI を音声にレンダリングするシンセ／インストゥルメントアプリ | 組み込み楽器 | MIDI 入力、リアルタイムとストリーミング |
| DAW、アレンジ、MIDI シーケンスツール | プロジェクト編集 | MIDI 入力、プロジェクトバウンス |
| 内蔵プレイヤーでの SoundFont（SF2）再生 | SoundFont 2 プレイヤー | 組み込み楽器、MIDI 入力 |
| ライブ可視化、リズムゲーム補助、AudioWorklet ツール | リアルタイムとストリーミング | WebAssembly ガイド |
| マイク入力のリアルタイムボイスチェンジャー | リアルタイムボイスチェンジャー | WebAssembly ガイド |
| ルームの響き、推定、生成された部屋らしさ | ルーム音響解析 | JavaScript API、Python API |
| メル／MFCC 特徴量をプレビューやデバッグ用に逆変換する | 逆変換特徴量 | librosa 互換性 |
| librosa からの移行 | librosa 互換性 | 機能マップ |
目的別ページの読み方
「作りたいもの別」の各ページは、同じ順序で読めるようにしています。
- 最初に判断基準を示す。
- 次に最小コード例を示す。
- 最後に注意点と関連ページを置く。
ブラウザ / WASM、Python、CLI の 3 つで同じワークフローを安全に示せる場合は、::: code-group で併記しています。
リアルタイムエンジンや AudioWorklet のように実行環境が WASM / C++ 側に寄る機能では、Python / CLI に同じライブコールバック API があるかのようには書きません。代替となるバッチ API や参照先を明記します。
ルーム音響には、残響時間、明瞭度、ブラインド推定、等価ルーム推定、RIR 合成、ルームモーフィングが含まれます。
実装者向けチェックポイント
目的別ページを読んだあと、実装に入る前に次を確認してください。
| 確認すること | 見る場所 | 判断のしかた |
|---|---|---|
| 入力がファイルか、エンコード済みバイト列か、デコード済みサンプルか、ライブブロックか | 各ページの「いつ使うか」「どちらを使うか」 | ブラウザ / WASM は多くの場合 Float32Array と sampleRate を受け取ります。エンコード済みバイト列には Audio.fromMemory* やブラウザ codec を使います。Python / CLI はファイル入力を直接扱えます。 |
| 同じ処理をどの実行環境で呼ぶか | ::: code-group のブラウザ / Python / CLI 例 | 3 つを併記しているページでは、API 名、引数名、戻り値の形の違いを見比べてください。 |
| 用語を UI や実装コメントで説明できるか | ページ内の ::: tip / ::: info / ::: warning / ::: details と 用語集 | 実装判断に効く用語は本文に短く置き、長い背景は VitePress の補足ボックスや用語集へ逃がしています。 |
| ランタイム差分があるか | バインディング対応表 と各 API リファレンス | 目的別ページの例がないランタイムでは、対応 API が未公開または用途違いの可能性があります。 |
4 つの層で考える
libsonare は、4 つの層に分けて読むと理解しやすくなります。
| 層 | 内容 | ページ |
|---|---|---|
| 概念 | BPM、キー、STFT、クロマ、LUFS、トゥルーピークなどの意味 | イントロダクション、用語集 |
| 目的 | 解析、ストリーミング、編集、ミキシング、マスタリングなど、作りたい機能 | 機能マップ、各機能ガイド |
| 実行環境 | ブラウザ、Python、Node、CLI、C++ のどこで動かすか | はじめに、利用環境別リファレンス |
| 根拠 | 実装の構造、アルゴリズム、検証状況 | DSP 実装解説、アルゴリズム根拠、実装検証 |
多くの利用者は、最初に概念、目的、実行環境の 3 つを読めば十分です。実装と根拠のページは、必要になった時点で開いてください。
最初のプロジェクトまでの最短ルート
- イントロダクション で基本用語を確認する。
- はじめに で利用環境を選ぶ。
- 使用例 から小さなサンプルを 1 つ動かす。
- 必要な API ファミリーを探すときは 機能マップ を使う。
- 実行環境をまたいでコードを移すときだけ バインディング対応表 を確認する。
深掘りページを読むタイミング
DSP のパラメータを UI に出す、レンダリングレポートを説明する、リアルタイム用途に向く処理か確認する、アルゴリズム上の根拠を確認する、といった場面で実装ページを開きます。最初の組み込みでは必須ではありません。