マスタリングプロセッサ
このページは libsonare の名前付きマスタリング API のレジストリです。「何を呼べるか」に答え、「内部でどう動くか」には答えません。
実行時の根拠は masteringProcessorNames()、masteringPairProcessorNames()、masteringPairAnalysisNames()、masteringStereoAnalysisNames()、masteringPresetNames() です。このページはそれらを反映します。
マスタリングが初めてなら、ここから始めない
プロセッサを 1 つずつ呼ぶのは難しい道です。まずはプリセット（masterAudio）か、音声をプロファイルしてチェーン全体を提案する マスタリングアシスタント から始めてください。ソロプロセッサは、ある段を外科的に制御したいときだけ使います。
挙動・処理境界・DSP ファミリーごとのリアルタイム注意点は DSP 実装解説 を、規格と論文の引用は アルゴリズム根拠 を、テストカバレッジは 実装検証 を参照してください。
このページで身につくこと
このページを読むと、次のことを判断・実装できるようになります。
- プリセット、ソロプロセッサ、ペアプロセッサ、JSON を返す解析を区別できる。
- ID をアルファベット順に眺めるのではなく、「ダイナミクスを制御する」「リファレンスに合わせる」といった目的から入口を選べる。
- 直接プロセッサを呼ぶより、プリセットやアシスタントの流れが適している場面を判断できる。
- JavaScript、Python、Node ネイティブ、C ABI に渡す正確なレジストリ名を見つけられる。
名前の種類
| 種類 | 意味 | 例 |
|---|---|---|
| プリセット | スタイルや配信ターゲット向けの名前付きチェーン設定 | streaming、podcast、jpop |
| ソロプロセッサ | モノラル／ステレオ信号に適用する 1 プロセッサ | dynamics.compressor、eq.tilt |
| ペアプロセッサ | ソースとリファレンス信号を使うプロセッサ | match.applyMatchEq |
| 解析 | 音声ではなく JSON を返す測定 | match.referenceLoudness、stereo.monoCompatCheck |
サイドチェイン／ラウドネス系プロセッサ
ダイナミクス系には、dynamics.duckingProcessor（サイドチェインダッキング）、maximizer.loudnessOptimize（LUFS ターゲットのマキシマイズ）、dynamics.deesser の bandpass Q コントロール（ステレオ保持つき）があります。
これらは dynamics.transientShaper、dynamics.upwardCompressor、dynamics.upwardExpander、dynamics.vocalRider、dynamics.sidechainRouter と並ぶ名前付きプロセッサです。
プリセット
プリセットは別アルゴリズムではなく、名前付きのチェーン設定です。masterAudio(samples, sr, preset, overrides?) の overrides?（上書き値）で必要な項目だけ調整できます。
pop, edm, acoustic, hipHop, aiMusic, speech, streaming, youtube, broadcast, podcast, audiobook, cinema, jpop, ambient, lofi, classical, drumAndBass, techno, metal, trap, rnb, jazz, kpop, trance, gameOst
プリセットを完成マスターと見なさずに選ぶ方法は プリセットの選び方 を参照してください。
目的別プロセッサ早見表
以下のレジストリへの目的起点のインデックスです。規則ではなく出発点なので、決める前にリンク先のガイドを読んでください。
| やりたいこと | 使うもの | 概念を学ぶ |
|---|---|---|
| レベルをそろえる／ダイナミクス制御 | dynamics.compressor、dynamics.limiter、multiband.compressor | ダイナミクス |
| 潰さずパンチを出す | dynamics.transientShaper、dynamics.parallelComp | ダイナミクス |
| 耳障りな「サ行」を抑える | dynamics.deesser | ダイナミクス |
| 音楽ベッドを声の下に下げる | dynamics.duckingProcessor、dynamics.sidechainRouter | ミキシングエンジン |
| 全体のトーン／明るさを整える | eq.tilt、eq.parametric、spectral.airBand | トーンと Air |
| 温かみ／倍音を加える | saturation.tape、saturation.tube、saturation.exciter | トーンと Air |
| ステレオを広げる／狭める／確認 | stereo.imager、stereo.monoMaker、stereo.monoCompatCheck | ステレオとラウドネス |
| ラウドネスに安全に到達 | loudness 段、maximizer.loudnessOptimize、maximizer.truePeakLimiter | 配信ターゲット |
| ノイズ／クリック／クリップ除去 | repair.denoiseClassical、repair.declick、repair.declip | リペアと入力 |
| リファレンスに合わせる | match.applyMatchEq、match.referenceLoudness | リファレンスマッチ |
サイドチェイン／ダッキングとは？
サイドチェインは、ある信号で別の信号にかけたプロセッサを制御する仕組みです。最もよくある用途がダッキングで、声があるときは音楽ベッドが自動で下がり、隙間で戻ります。ナレーションの下で BGM が下がるあの動きです。
パラレルコンプレッションとは？
通常のコンプレッサーは大きい部分を下げます。
パラレルコンプレッションは、原音と強くかけたコピーを混ぜます。圧縮したコピーが小さなディテールを持ち上げ、手つかずの原音が自然なピークを保ちます。
トランジェントを潰さずに密度と「まとまり」を足したいときに使います。ニューヨークコンプとも呼ばれます。dynamics.transientShaper は逆向きの道具で、各打撃のアタックを強調・緩和します。
プロセッサファミリーを役割で読む
コードでは正確な ID が重要ですが、選ぶときはまず役割で見ます。
| ファミリー | 使う場面 | 避ける場面 |
|---|---|---|
| Dynamics | 音量の包絡が問題のとき。ピークが飛び出す、ボーカルが不均一、トランジェントを整えたい、声の下にベッドを下げたい | 問題が音色バランスなら EQ や spectral 系の方が明確です |
| EQ | 暗い、刺さる、膨らむ、特定帯域を切りたいなど、周波数バランスが問題のとき | ラウドネスを稼ぎたい場合。dynamics / maximizer を使います |
| Multiband | 帯域ごとに異なるダイナミクスや幅処理が必要なとき | 単一帯域の処理で十分なとき。multiband は過剰調整になりやすいです |
| Saturation | 倍音密度、エッジ、温かみ、クリップ感を加えたいとき | クリーンな補正が必要なとき。saturation は意図的に色を付けます |
| Spectral | Air、プレゼンス、低域のフォーカスなど、知覚上のトーンを広く整えたいとき | 正確なフィルター操作が必要なとき。EQ を使います |
| Stereo | 幅、モノラル互換性、位相、左右バランスが問題のとき | すでに位相に敏感なミックスや、モノラル配信が主目的のとき |
| Maximizer / final | 配信直前。ラウドネス、シーリング、ビット深度、最終出力の調整 | まだバランスやアレンジの問題を直している段階 |
| Repair | 入力にクリック、クラックル、ハム、クリップ、ノイズ、過剰な残響があるとき | 音源分離やニューラル修復を期待しているとき |
多くのチェーンは、必要ならリペア、トーン段を 1 つ、ダイナミクス段を 1 つ、必要に応じてサチュレーション / ステレオ、最後にマキシマイザー / ラウドネスで十分です。レジストリから大量に積むより、プリセットから始めて 1〜2 箇所だけ上書きする方が安定します。
ラウドネス・オーバーサンプリング・メーターの詳細
マキシマイザー／final と解析の API の下には、いくつかの機能があります。
- インテグレーテッド LUFS 測定は最大 8 チャンネルのサラウンド構成に対応し、BS.1770 のチャンネル重み付けを適用します。
- 内部のオーバーサンプラーとトゥルーピーク段はオーバーサンプリング係数として 1〜16 の 2 のべき乗（1, 2, 4, 8, 16）を受け付けます（ライブメーターも同じ係数）。CPU と引き換えにサンプル間ピークの精度を上げます。
- UI 向けには表示用に間引いたメーターのバリアントがあります。
meteringVectorscopeDecimated(...)とmeteringPhaseScopeDecimated(...)は点列を最大maxPoints点まで間引くので、点数の多いスコープでも描画コストを抑えられます。meteringSpectrumFrame(...)は、スペクトラムアナライザーのスナップショット向けに単一フレーム（時間平均なし）のスペクトラムを読み取ります。 - ステレオイメージャー（バンドごとにステレオ幅を広げる／狭める）とダイナミック EQ（レベルに応じてブースト／カットが変化する、周波数を狙ったコンプのような EQ）はマルチバンド版も用意されています。
multiband.imagerとmultiband.dynamicEqはバンドごとのパラメータを公開し、クロスオーバー数も任意に指定できます。固定 3 バンドではなく、素材に合わせたバンド数で分割できます。
クロスオーバーとは？
クロスオーバーは、信号を周波数帯（たとえば低域／中域／高域）に分割し、各帯域を別々に処理できるようにします。「クロスオーバー周波数」は、ある帯域が終わり次の帯域が始まる境界の周波数です。クロスオーバーが多いほど帯域が増え、より細かく制御できます。
ソロプロセッサ
| ファミリー | プロセッサ名 |
|---|---|
| Dynamics | dynamics.brickwallLimiter, dynamics.compressor, dynamics.deesser, dynamics.expander, dynamics.gate, dynamics.limiter, dynamics.parallelComp, dynamics.sidechainRouter, dynamics.duckingProcessor, dynamics.transientShaper, dynamics.upwardCompressor, dynamics.upwardExpander, dynamics.vocalRider |
| EQ | eq.apiStyle, eq.bandPass, eq.cutFilter, eq.dynamic, eq.equalizer, eq.graphic, eq.linearPhase, eq.midSide, eq.minimumPhase, eq.parametric, eq.pultec, eq.shelving, eq.tilt |
| Final | final.bitDepth, final.dither, final.outputChain |
| Maximizer | maximizer.adaptiveRelease, maximizer.loudnessOptimize, maximizer.maximizer, maximizer.softKneeMax, maximizer.truePeakLimiter |
| Multiband | multiband.compressor, multiband.dynamicEq, multiband.expander, multiband.imager, multiband.limiter, multiband.saturation |
| Repair | repair.declick, repair.declip, repair.decrackle, repair.dehum, repair.denoiseClassical, repair.dereverbClassical, repair.trimSilence |
| Saturation | saturation.ampSim, saturation.bitcrusher, saturation.exciter, saturation.hardClipper, saturation.multibandExciter, saturation.softClipper, saturation.tape, saturation.transformer, saturation.tube, saturation.waveshaper |
| Spectral | spectral.airBand, spectral.lowEndFocus, spectral.presenceEnhancer, spectral.spectralShaper |
| Stereo | stereo.autoPan, stereo.haasEnhancer, stereo.imager, stereo.monoMaker, stereo.phaseAlign, stereo.stereoBalance |
ディザーとは？
ビット深度を下げる（たとえば CD／配信向けに 24bit から 16bit へ）と、丸め処理が静かな余韻にかすかな歪みを生みます。ディザーは、注意深く整形した微小なノイズを加えてその歪みを覆い隠し、フェードがざらつかず滑らかに聞こえるようにします。最終のビット深度削減のときに、最後に 1 回だけ適用します。
リペアは設計上クラシカル DSP
repair.denoiseClassical・repair.dereverbClassical などは、明示的なノイズ推定を伴うスペクトル減算／MMSE-STSA／LogMMSE を使います。
DNN 音源分離やニューラルなスペクトル修復ではありません。
- 向く用途: ノイズ、ハム、クリック、クリッピング、軽い部屋鳴りの整理。
- 向かない用途: 完成トラックの分離、失われた音源の再構成。
- 設計上の理由: リペア経路を決定的で外部依存なしに保つためです。
レジストリ名とチェーンキーは異なります
名前付きプロセッサレジストリでは、単発のリペアプロセッサ名は repair.denoiseClassical と repair.dereverbClassical です。
フルチェーン設定では、短いステージキーの repair.denoise.* と repair.dereverb.* を使います。これらは MasteringChainConfig 内のリペアスロットを指します。
どちらの名前も、同じクラシカルなデノイズ／ディリバーブ実装を呼び出します。
スペクトル減算（MMSE-STSA／LogMMSE）とは？
いずれもクラシカルなノイズ除去手法です。
- 静かな箇所からノイズプロファイル（定常的なヒスやハム）を推定します。
- スペクトル減算は、各短時間スペクトルフレームからその推定ノイズを差し引きます。
- MMSE-STSA と LogMMSE は、周波数ビンごとに信号とノイズの割合を推定してから差し引く統計的手法です。
これにより、素朴な減算で残る「ミュージカルノイズ」のようなざらつきを抑えます。楽器を分離するものではなく、ノイズを減衰させるだけです。
saturation.ampSim とは？
ギターアンプ系の色付け段で、drive → トーンスタック → キャビネットの構成です。オーバーサンプリングした 12AX7 三極管のドライブ段が 1 つの [0, 1] ドライブノブの背後にあり、ドライブ量に応じてプリエンファシスのシェルフが変化するため、押し込むほど歪みの質感が変わります。ドライブの後にはバス／ミッド／トレブルのトーンスタックが続き、最後に固定のデータレスなキャビネット特性（ローカット、ボディの膨らみ、プレゼンスのピーク、4.8 kHz 付近の急峻なロールオフ）が入ります。これはクリーンな DI トーン用にバイパスできます。ドライブ、トーン、プレゼンス、レベルの各コントロールは、全バインディングで set_parameter から自動化できます。構築／パラメータキーは次の通りです。drive（0〜1、12AX7 三極管段をオーバードライブ）、bassDb、midDb、trebleDb（120 Hz／550 Hz／3 kHz でのトーンスタックゲイン[dB]）、presenceDb（キャビネット特性のプレゼンスピークゲイン[dB]、約 3.8 kHz）、levelDb（出力トリム[dB]）の 6 つが、そのまま set_parameter のオートメーションレーンになります。cab ブール値（既定値 true）は離散的なトポロジースイッチで、false にするとキャビネット特性をバイパスしてクリーンな DI トーンになります。他とは異なり set_parameter には公開されません。
ペアプロセッサと解析
ペアプロセッサはソースとリファレンスを取ります。ペア／ステレオ解析は測定 JSON を返し、それ自体では音声をレンダリングしません。
| 種類 | 名前 |
|---|---|
| ペアプロセッサ | match.applyMatchEq, match.alignReferenceToSource, match.abSwitch, match.abCrossfade |
| ペア解析 | match.referenceLoudness, match.tonalBalance, match.tonalBalanceLogBands, match.matchEqCurve, match.estimateReferenceDelaySamples |
| ステレオ解析 | stereo.monoCompatCheck, stereo.monoCompatCheckLogBands |
「トーナルバランス」と「モノラル互換性」は何を測る？
- トーナルバランス（
match.tonalBalance）は、トラックのエネルギーが各周波数帯（サブ・低域・中域・プレゼンス・エア）にどう分布しているかを表します。リファレンス曲と比べると、自分の音がどこで暗い／明るいかが分かり、match.applyMatchEqがそれを補正します。 - モノラル互換性（
stereo.monoCompatCheck）は、ステレオミックスをモノラルに合算したときに何が起きるかを予測します。スマホのスピーカー、クラブの PA、一部の放送経路では、この確認が重要です。
左右が逆相だと、合算時に打ち消し合ってレベルが失われることがあります。このチェックはそのリスクを事前に知らせます。詳しくは モノラル互換性 を参照してください。
ミキサーインサート名
ミキサーシーンのインサートはマスタリングインサートと同じファクトリを使いますが、有効なインサート集合は masteringProcessorNames() より少し広いです。何が使えてどう設定するかは、次の 4 つの実行時 API で把握できます。
| API | 返すもの |
|---|---|
masteringInsertNames() | 有効なインサート id の全リスト |
masteringInsertParamNames(name) | 1 つのインサートが受け付ける構築用キー（バンド／サブバンド型はインデックス付きの band{i}.* キーを列挙し、未知の名前には空配列を返す） |
masteringInsertParamInfo(name) | リアルタイムオートメーション可能なサブセット。各パラメータの JSON キー、数値のオートメーション id、リアルタイム安全フラグ |
masteringProcessorCatalog() | kind、realtimeInsertable、stereoOnly、channelPolicy を持つ機械処理しやすいエントリ。ピッカー／フィルタ UI 向けで、オフライン専用・ペア処理・ステレオ専用・サラウンドバスでのラップ方法をプロセッサ ID のハードコードなしに絞り込める |
Python の対応関数は mastering_insert_param_names(name)、mastering_insert_param_info(name)、mastering_processor_catalog() です。
一覧外のキーはプロセッサに無視され、そのキーを含むシーンを読み込むと Mixer.sceneWarnings() が報告します。上のソロプロセッサに加え、クリエイティブ FX 有効ビルドではリバーブやモジュレーションのインサート ID も使えます。
| Insert ID | 意味 |
|---|---|
effects.reverb.plate | Dattorro 系プレートリバーブのエイリアス |
effects.reverb.dattorro | Dattorro リバーブ |
effects.reverb.fdn | フィードバックディレイネットワークリバーブ |
effects.reverb.velvet | Velvet-noise 系リバーブ |
effects.reverb.convolution | Convolution リバーブ。ネイティブ insert 作成経路ではインパルスレスポンスを使えます |
effects.reverb.room | ルームパラメータから合成する幾何ベースのルームリバーブ |
effects.acoustic.roomMorph | 目標の幾何ベースルームへ寄せるルームモーフィング |
effects.modulation.ensemble | Solina 系 BBD ストリングマシンアンサンブル |
effects.modulation.chorus | ステレオコーラス |
effects.modulation.flanger | フランジャー |
effects.modulation.phaser | フェイザー |
effects.delay.stereo | ステレオディレイ |
これらの insert ID は、SONARE_HAVE_FX 有効ビルドでのみ使えます。幾何ベースのルーム系インサートは BUILD_ACOUSTIC_SIM も必要です。
実用上の注意は次の通りです。
| 項目 | 意味 |
|---|---|
effects.reverb.plate と effects.reverb.dattorro | 同じ Dattorro プロセッサの別名 |
| リバーブの params | decaySec、decay、damping / hfDamping、dryWet、preDelayMs、reverbTimeS、densityHz、enableShelf（アルゴリズムにより該当キーは異なる）。Dattorro／プレート insert はコーラスのかかったテイル用に modRateHz（図形8タンクの LFO レート[Hz]、既定値 0.5）と modDepthSamples（リバーブの基準レートでの変調深さ[サンプル]、既定値 6.0）も受け付ける |
effects.modulation.chorus の params | rateHz、depthMs、centerDelayMs、dryWet |
effects.modulation.flanger の params | rateHz、depthMs、centerDelayMs、feedback、dryWet |
effects.modulation.phaser の params | rateHz、minHz、maxHz、stages、dryWet |
effects.modulation.ensemble の params | rateSlowHz、rateFastHz、depthSlowMs、depthFastMs、centerDelayMs、toneHz、dryWet |
effects.delay.stereo の params | delayTimeLMs、delayTimeRMs、feedback、pingPong、dryWet |
effects.reverb.convolution | ネイティブの insert 構築時にインパルスレスポンスを渡す必要がある |
| IR のない convolution insert | 実質的にパススルーとして動作する |
これらのリバーブアルゴリズムの違いは？
いずれも残響のテイルを生成する方式の違いです。正しさではなく、欲しい質感で選んでください — どれも有効です。
- Plate / Dattorro — 滑らかで密度の高い、定番スタジオ的な響き。Dattorro 方式は広く使われるプレート系の設計で、
plateはその別名です。 - FDN（フィードバックディレイネットワーク） — 相互接続したディレイラインで構成する柔軟なアルゴリズミックリバーブ。小さな部屋から大ホールまで調整しやすいのが特長です。
- Velvet-noise — まばらなランダムインパルスを使い、低い CPU 負荷で自然なテイルを作ります。
- Convolution（畳み込み） — 実空間で測定したインパルスレスポンスと信号を畳み込み、実際の空間を再現します。
effects.modulation.ensemble とは？
Solina 系の BBD ストリングマシンアンサンブルで、ビンテージのストリングシンセらしい厚いコーラス感のある音色です。チャンネルごとに 3 つのディレイタップを持ち、低速と高速の 2 つの 3 相 LFO バンクで同時に揺らすため、単純なコーラスの揺れではなく密度の高いモジュレーションになります。ウェット経路には BBD のバケツ帯域を模したローパスがかかり、アナログのバケツリレー素子らしく暗くなります。右チャンネルの LFO 極性は反転しており、モノラルのソースを広いステレオ像へ広げます。インサートファクトリから利用でき、パラメータは全バインディングで set_parameter から自動化できます。
これらは ミキシングシーン JSON の insert.processor フィールドで使います。出荷される FX 有効の WASM ビルドでは、多くは一括マスタリングプロセッサでもあります。effects.reverb.plate、effects.reverb.dattorro、effects.reverb.fdn、effects.reverb.velvet、effects.reverb.convolution、effects.modulation.chorus、effects.modulation.flanger、effects.modulation.phaser、effects.delay.stereo は masteringProcessorNames() から返り、一括適用パスで動作します。一方、幾何ベースのインサートとアンサンブル — effects.reverb.room、effects.acoustic.roomMorph、effects.modulation.ensemble — はインサート専用で、masteringProcessorNames() には現れません。これらは masteringInsertNames() とシーンインサート経由で使ってください。
呼び出し方
masteringProcessorNames(); // 実行時にソロプロセッサ id を取得
masteringProcessorCatalog(); // ピッカー／フィルタ用にプロセッサを分類
masteringInsertParamInfo('eq.parametric'); // リアルタイムオートメーション用メタデータ
const out = masteringProcess('dynamics.compressor', samples, sampleRate, {
thresholdDb: -24,
ratio: 1.5,
});
const stereo = masteringProcessStereo('stereo.imager', left, right, sampleRate, { width: 1.1 });
// 解析は JSON 文字列を返す — パースする
const report = JSON.parse(masteringPairAnalyze('match.referenceLoudness', source, reference, sampleRate));
const mono = JSON.parse(masteringStereoAnalyze('stereo.monoCompatCheck', left, right, sampleRate));import json
import libsonare as sonare
sonare.mastering_processor_names() # 実行時にソロプロセッサ id を取得
out = sonare.mastering_process('dynamics.compressor', samples, sample_rate=sr, params={
'thresholdDb': -24,
'ratio': 1.5,
})
stereo = sonare.mastering_process_stereo('stereo.imager', left, right, sample_rate=sr, params={'width': 1.1})
# 解析は JSON 文字列を返す — パースする
report = json.loads(sonare.mastering_pair_analyze('match.referenceLoudness', source, reference, sample_rate=sr))
mono = json.loads(sonare.mastering_stereo_analyze('stereo.monoCompatCheck', left, right, sample_rate=sr))# ソロプロセッサ id を取得
sonare mastering-processors
# ソロプロセッサを 1 つ適用（--params は浮動小数の k=v,k=v）
sonare mastering-processor song.wav --processor dynamics.compressor \
--params "thresholdDb=-24,ratio=1.5" -o out.wav
# 2 入力（ペア）解析は JSON を出力
sonare mastering-pair-analyze song.wav --reference ref.wav --analysis match.referenceLoudness
# ステレオプロセッサ（stereo.imager）には Python CLI サブコマンドはない。
# ソースビルドの C++ CLI では mastering-stereo-analyze / analyses も使える。チェーンの入口で設定スタイルが異なる
レジストリは文字列ベースなので、C・Python・Node・WASM・CLI が同じプロセッサ識別子を共有できます。
単一プロセッサではなくチェーンを組むときは、入口ごとに設定スタイルが変わります。
| 入口 | 設定スタイル |
|---|---|
WASM masteringChain(...) | ネストした設定オブジェクト |
masterAudio(...) と Python/Node 相当 | 'loudness.targetLufs' のようなフラットなドット記法 |
マスタリングアシスタント の chainConfig.params | masterAudio にそのまま渡せるフラット形式 |
repair のチェーンキーは、単発プロセッサの registry 名ではなくチェーン内の slot に合わせます。フラットな上書きでは repair.denoise.* / repair.dereverb.*、masteringChain(...) のネスト形式では repair: { denoise: ..., dereverb: ... } を使ってください。
関連
- マスタリングアシスタント — profile/suggest/preview の JSON と提案→レンダリング経路
- マスタリング実装 — ブラウザデモでレンダリングするチェーン
- DSP 実装解説 — 各ファミリーの挙動
- ミキシングエンジン — これらをチャンネルストリップ／バスのインサートとして読み込む