学習順ガイド
このページは、「何を作りたいか」から libsonare のドキュメントを辿るための道案内です。DSP、MIR、WebAssembly、マスタリング用語を最初から理解している必要はありません。
最初に出る略語
DSP（digital signal processing、デジタル信号処理）は音を数値として測定・加工する処理、MIR（Music Information Retrieval、音楽情報検索）は BPM・キー・コードなどを音楽から読み取る処理です。WASM / WebAssembly はブラウザで使う実行形式、API はアプリから呼ぶ関数やクラス、CLI はターミナルで使うコマンドです。ここでは用語を完全に覚えるより、「どの種類のページへ進むか」を選べれば十分です。
サイドバーのガイドは 10 の分野に分かれています。解析、楽器と MIDI、ミキシング、マスタリング、編集、リペア、アレンジとプロジェクト、リアルタイム、ルーム音響、再生の 10 個です。以下の見出しも同じ分野名を使っているので、目的を見つけた分野が、そのガイドが並ぶサイドバーのグループでもあります。分野のあとには実行環境別のリファレンスと根拠のページが続きます。
まだ何も動かしていない場合は、はじめに から始めてください。実行環境ごとに、インストール行 1 つと短いプログラム 1 つを載せています。
ドキュメントを先頭から順に読む場合
- イントロダクション で用語と音声解析パイプラインの全体像を読む。
- サンプル、サンプルレート、デシベル（dBFS、RMS、LUFS）、周波数と倍音、ステレオのどれかが初めてなら、オーディオ基礎 を読む。
- MIR の全体像 で、スペクトログラム、クロマ、オンセット、解析結果がどう積み上がるかを読む。
- このページで、目的がどの分野に属するかを見つける。
- はじめに、インストール、使用例 で小さなプログラムを 1 つ動かす。
- 機能マップ で必要な API ファミリーを探す。
- 組み込みではなく完成した成果物が目的なら、実践ユースケース から通し手順を 1 つ読む。
- 下の一覧から、目的に合う分野のガイドを 1 つ読む。ミキシング、編集、マスタリングには先に読む基礎のページがあります（ミキシングの基礎、編集の基礎、マスタリングとは?）。
- 実行環境別 API から実行環境に合うリファレンスを 1 つ読む。
- 実装詳細、アルゴリズム根拠、検証範囲、性能が必要になったときだけ、根拠のページを読む。
作りたいものから選ぶ
作りたいものを、それが属する分野の中から探してください。最初に読むページ はその目的のために書かれたページ、次に読むページ は最初のページが腑に落ちたあとに詳細を追う場所です。実践ユースケース から始まる行は、実行できるコマンド付きの通し手順です。
解析
この分野の結果はテンポもキーもコードもセクションも、すべて同じ最初の一歩から読み取られます。音声を短い窓に区切って少しずつずらしながら、窓ごとにスペクトルを求めると、録音全体が「どの瞬間にどの周波数が鳴っているか」の一枚の絵になります。その絵を見たことがなければ、下のデモで確かめてください。
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| BPM、キー、コード、セクションを表示するブラウザアプリ | はじめに | 楽曲解析、WebAssembly ガイド |
| 音声解析を行う Python スクリプトやノートブック | はじめに | Python API、楽曲解析 |
| ターミナルでの簡易確認やバッチ解析 | はじめに | CLI リファレンス、CLI コマンド |
| 曲構造、自己類似度、ノート区間を解析するツール | 楽曲解析 | JavaScript API、Python API |
| すでに手元にあるビート列から小節と拍子記号を求める | 楽曲解析 | 拍子とグルーピング |
| librosa からの移行 | librosa 互換性 | 楽曲解析 |
| librosa の数値（フレーム／サンプル変換、デシベル、ピーク検出）をシェルからエンジンと突き合わせる | CLI ユーティリティ | librosa 互換性 |
| 倍音成分と打撃成分を分け、編集にも使える音源分離ビュー | 音源分離 | 楽曲解析、編集 DSP |
楽器と MIDI
この分野では、録音を再生するものは何もありません。エンジンはサンプルデータを一切同梱せず、どの楽器も発音中に計算で音を作ります。その判断と、そこから何が導かれるかを説明するのが 音源方式 です。合成方式を選び終えた前提で書かれているページを開く前に、まずこのページを読んでください。
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| 物理モデル、FM、減算合成、持ち込みの SoundFont のどれにするかを決める | 音源方式 | 内蔵シンセサイザー、物理モデル |
| MIDI を音声にレンダリングするシンセ／インストゥルメントアプリ | 内蔵シンセサイザー | MIDI 入力、リアルタイムとストリーミング |
| MIDI 1.0 と MIDI 2.0 のイベントを扱う MIDI クリップエディタやシーケンサー | MIDI クリップ編集 | MIDI 2.0 と UMP、プロジェクトの MIDI |
| ピアノ、擦弦、リード、金管、フルートといったアコースティック音源を聴き比べたり、コードから音作りする | 物理モデル | 内蔵シンセサイザー |
| SoundFont にないプログラムで、General MIDI の各プログラムがどのエンジンと音作りに落ちるかを調べる | GM 音色マップ | GM／GS フォールバックバンク |
| 内蔵プレイヤーでの SoundFont（SF2）再生 | SoundFont 2 プレイヤー | GM／GS フォールバックバンク、MIDI 入力 |
| 解析やマスタリングは使わず、インストゥルメントだけが必要な C++ アプリ | リンクターゲット | 内蔵シンセサイザー、SoundFont 2 プレイヤー |
ミキシング
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| ブラウザまたはネイティブのミキサー | ミキシングエンジン | ミキシングシーン JSON |
| 動作するデモのソースを読みながら作るブラウザのミキシングアプリ | ブラウザでミキシングアプリを作る | ミキシングエンジン、ミキシングデモのプロジェクト JSON |
| トラックそのものを計測してミックスの出発点を提案させ、判断ごとの理由も受け取る | ミキシングアシスタント | ミキシングシーン JSON、ミキシングエンジン |
| ストリップやバスに挿すリバーブ、モジュレーション、ディレイ | エフェクトインサート | ミキシングシーン JSON |
| 手書きの表を持たず、エンジン自身のパラメータ記述子から描くインサートのコントロール | パラメータ記述子からコントロールを組み立てる | エフェクトインサート、リアルタイムエンジン |
| 声の下で BGM をダッキングし、ラウドネス規定に合わせて納品するトーク番組 | トーク番組を仕上げる | ミキシングエンジン、CLI リファレンス |
マスタリング
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| マスタリング UI や自動マスタリング | マスタリングアシスタント | マスタリングプロセッサ |
| ステムのフォルダから仕上げたマスターを、ターミナルだけで作る | CLI だけでミックスからマスタリングまで | CLI リファレンス、マスタリングプロセッサ |
| ミックスの音色とラウドネスを、リファレンス曲と同じ範囲に寄せる | リファレンス曲に寄せる | マスタリングアシスタント |
| 納品前のマスターに対する合否判定を CI で回す | 納品前チェックを CI で回す | CLI リファレンス |
| マスタリングチェーン自体のパラメータを操作する UI、あるいは処理内容を説明できるレンダリングレポート | マスタリング実装 | マスタリングプロセッサ、パラメータ記述子からコントロールを組み立てる |
編集
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| ピッチ、長さ、声質、音源分離の編集 | 編集 DSP | JavaScript API |
| 音声の採譜、クリップ置換、テンポに沿った MIDI 配置 | 音声から MIDI | MIDI クリップ編集、プロジェクトの MIDI |
| ピアノの録音を MIDI ファイルにし、譜面と照合する | ピアノの録音を MIDI にする | 音声から MIDI |
| 音声クリップへレンダリングし直すノート単位の編集 | 音声内のノート編集 | 編集 DSP |
| 領域指定のスペクトル編集（時間×周波数の矩形を減衰・ミュート・ゲイン・修復） | スペクトル編集 | 編集 DSP |
| 曲を減速・移調・パート分離した練習用トラック | 練習用トラックを作る | 編集 DSP、音源分離 |
| 録音したテイクを MIDI ファイルのメロディに合わせてシェルから補正する | CLI ユーティリティ | プロジェクトの MIDI |
リペア
欠陥を測定してからリペア段を選びます。広帯域ノイズ、電源ハム、クリップしたピーク、衝撃的なクリック、クラックル、拡散残響には、それぞれ異なる根拠と再構成の限界があります。
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| 測定した欠陥から段を選ぶリペアワークフロー | オーディオリペアの流れ | 広帯域ノイズとハムのリペア、クリップ、クリック、クラックルのリペア、拡散残響のリペア |
| 荒い録音素材をまとめて整音し、素材ごとに何が問題だったかを記録する | 録音素材をまとめて整音する | オーディオリペアの流れ |
アレンジとプロジェクト
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| DAW、アレンジ、MIDI シーケンスツール | プロジェクト編集 | プロジェクトの MIDI、プロジェクトのバウンス |
| 歌のテイクをノートごとに（ピッチ、フォルマント、レベル）元に戻せる形で補正し、結果をプロジェクトに置く | ボーカル編集 | 歌のピッチを直す |
| プロジェクトをファイルに保存し、再び開く | プロジェクトの保存と読み込み | プロジェクト編集 |
| マイク録音、ループ録音のテイク、クリップへのコンピング | 録音とテイク | プロジェクト編集 |
| 内蔵シンセの有無を問わず、プロジェクトをオーディオに書き出す | プロジェクトのバウンス | 内蔵シンセサイザー、SoundFont 2 プレイヤー |
リアルタイム
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| ライブ可視化、リズムゲーム補助、AudioWorklet ツール | リアルタイムとストリーミング | WebAssembly ガイド |
| トランスポート、トラックレーン、ライブ MIDI、オートメーションを備えた再生エンジン | リアルタイムエンジン | リアルタイムとストリーミング |
| マイク入力のリアルタイムボイスチェンジャー | リアルタイムボイスチェンジャー | WebAssembly ガイド |
ルーム音響
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| ルームの響き、推定、生成された部屋らしさ | ルーム音響解析 | JavaScript API、Python API |
| メル／MFCC 特徴量をプレビューやデバッグ用に逆変換する | 逆変換特徴量 | librosa 互換性 |
再生
| 作りたいもの | 最初に読むページ | 次に読むページ |
|---|---|---|
| 映像作品の音声を、バイノーラルのヘッドホン出力や較正済みのステレオ／5.1／7.1 スピーカー出力にする | 再生レンダラー | チャンネル形式 |
| モノラル、ステレオ、5.1、7.1 の入力を各モジュールがどう扱うかを確認する | チャンネル形式 | 再生レンダラー |
目的別ページの読み方
各分野の目的別ページは、判断基準、最小のコード例、注意点と関連ページの順に並んでいます。ブラウザ / WASM、Python、CLI で同じワークフローを動かせる場合は、::: code-group で 3 つを併記しています。リアルタイムエンジンや AudioWorklet ブリッジのように WASM / C++ 側に寄る API では、Python / CLI に同じライブコールバック API があるかのようには書かず、代替となるバッチ API を案内します。
リファレンス
実装前のチェックポイント
目的別ページを読んだあと、実装に入る前に次を確認してください。
| 確認すること | 見る場所 | 判断のしかた |
|---|---|---|
| 入力がファイルか、エンコード済みバイト列か、デコード済みサンプルか、ライブブロックか | 各ページの「いつ使うか」「どちらを使うか」 | ブラウザ / WASM は多くの場合 Float32Array と sampleRate を受け取ります。エンコード済みバイト列には Audio.fromMemory* やブラウザのコーデックを使います。Python / CLI はファイル入力を直接扱えます。 |
| 同じ処理をどの実行環境で呼ぶか | ::: code-group のブラウザ / Python / CLI 例 | 3 つを併記しているページでは、API 名、引数名、戻り値の形の違いを見比べてください。 |
| 用語を UI や実装コメントで説明できるか | ページ内の ::: tip / ::: info / ::: warning / ::: details と 用語集 | 実装判断に効く用語は本文に短く置き、長い背景は補足ボックスや用語集に回しています。 |
| 実行環境ごとの差があるか | バインディング対応表 と各 API リファレンス | 目的別ページにその実行環境の例がない場合、対応 API が公開されていないか、実行環境が用途に合っていない可能性があります。 |
4 つの層
| 層 | 内容 | ページ |
|---|---|---|
| 概念 | サンプル、デシベル、BPM、キー、STFT、クロマ、LUFS、True Peak などの意味 | イントロダクション、オーディオ基礎、用語集 |
| 目的 | 上の 10 分野のどれで、何を作りたいか | 機能マップ、楽曲解析 から 再生レンダラー までの各分野ガイド |
| 実行環境 | ブラウザ、Python、Node、CLI、C++ のどこで動かすか | はじめに、実行環境別リファレンス |
| 根拠 | 実装の構造、アルゴリズム、検証状況 | DSP 実装解説、アルゴリズム根拠、実装検証 |
多くの利用者に必要なのは最初の 3 つです。DSP のパラメータを UI に出す、レンダリングレポートを説明する、リアルタイム用途に向く処理か確かめる、アルゴリズムの根拠を示す、といった場面で根拠のページを開いてください。