Python API

libsonare は、スクリプト、ノートブック、バッチ処理、ローカルツール向けの Python バインディングを提供します。Python パッケージは ctypes 経由でネイティブの libsonare ライブラリを呼び出すため、独自の C 拡張をビルドしなくても、コンパイル済みの C/C++ エンジンを Python から使えます。対応対象の Linux/macOS 向けに PyPI ホイールを配布しています。

ctypes（と C API）とは？

libsonare のコアはコンパイル済みの C/C++ です。

ctypes は、コンパイル済み共有ライブラリ（.so／.dylib）の関数を直接呼び出せる Python 標準の仕組みです。追加の C 拡張をビルドする必要はありません。

Python パッケージは、呼び出しを C++ ライブラリと同じネイティブコードへ橋渡しします。そのため、素の Python からネイティブ速度を得られます。

ここでいう C API は、Python が内部で呼び出すフラットな C 関数群を指します。

このページは、スクリプト、ノートブック、バッチ解析、ローカルツールから音声ファイルを直接扱いたい人向けです。ブラウザ UI を作らない場合、Python パッケージが最も入りやすい選択肢になることが多いです。リファレンスは 3 つの姉妹ページに続きます。解析関数と特徴抽出関数は Python 解析 API、オーディオエフェクト・ルーム音響解析・リアルタイムボイスチェンジャーは Python エフェクト API、結果と設定の型は Python 型定義を参照してください。

Python での考え方

手順	内容
1. 音声を読み込む	`Audio.from_file(...)` で対応形式のファイルをサンプルへ読み込む
2. 解析または処理する	`detect_bpm`、`analyze`、特徴量関数、編集 DSP、マスタリング、ミキシング API を呼ぶ
3. 結果を使う	値を表示する、JSON を保存する、音声を書き出す、自分のパイプラインへ特徴量を渡す

多くの Python API は、生のサンプル配列と sample_rate を受け取ります。生のサンプル配列とは、MP3 や WAV のファイル名ではなく、デコード後の音声値の並びです。Audio オブジェクトは、ファイルを扱うワークフローを簡単にするためのものです。一度読み込んだ音声に対して、解析や処理のメソッドを続けて呼べます。

最初のスクリプトは、これくらい小さく始めるのがおすすめです。

audio = sonare.Audio.from_file("song.mp3") で読み込む。
sonare.detect_bpm(audio.data, audio.sample_rate) または sonare.analyze(audio.data, audio.sample_rate) を呼ぶ。
結果を表示するか、JSON として保存する。

Audio から始めるか、関数を直接呼ぶか

音声ファイルを読むところから始めるなら Audio.from_file(...) が入口です。すでに NumPy 配列や別ライブラリで読み込んだサンプルを持っているなら、detect_bpm(samples, sample_rate) のようなモジュール直下の関数を直接呼ぶ方が分かりやすくなります。

このリファレンスの読み方

このページは 3 段階で読むと迷いにくくなります。

ファイルを読むなら Audio.from_file(...) から始める。すでにサンプル列があるなら、モジュール直下の関数を直接呼ぶ。
参照全体を眺めるのではなく、目的から API を選ぶで関数ファミリーを 1 つ選ぶ。
属性名、行優先の行列形状、JS 互換の別名が必要になったときだけ型定義に戻る。

analyze(...) を 1 回呼べば、コード、セクション、音色、ダイナミクス、リズム、メロディ、フォーム、拍ごとの強度を含む総合結果が返り、他のバインディングと揃っています。1 つのフィールドだけが欲しいときや、呼び出しごとにオプションを変えたいときは、下の専用関数を使ってください。

既定のサンプルレートはファミリーごとに異なる

楽曲解析系とメータリング系のヘルパーは sample_rate=22050 を既定とし、ルーム音響系のヘルパー（analyze_impulse_response、detect_acoustic、estimate_room）は 48000 を既定とします。Audio.from_file(...) で読み込んだ場合は、必ず audio.sample_rate を渡してください。そうすれば、別のレートで録音した音声にファミリーごとの既定値が気付かないうちに使われることはありません。ここでいうインパルス応答（IR）とは、短い一発の音に対して空間がどう応答するかを録音したものです。

目的から API を選ぶ

やりたいこと	最初に使う API	理由
ファイルを読んでメタデータを出すスクリプト	`Audio.from_file(...)` + `detect_bpm` / `detect_key` / `analyze`	Python 側でデコードでき、短いコードで書けます
詳細な楽曲解析	`analyze_bpm`, `detect_chords`, `analyze_sections`, `analyze_timbre`, `analyze_dynamics`, `analyze_rhythm`	追加パラメータ付きで 1 種類の解析だけを実行します。`analyze(...)` はこれらのフィールドを 1 つの `AnalysisResult` にまとめて返します
ノートブックや ML 用の特徴量	`mel_spectrogram`, `mfcc`, `chroma`, `cqt`, `vqt`, `chroma_cqt`, `nnls_chroma`	Python のリスト／結果オブジェクトで返り、必要なら NumPy に変換できます
クリップを編集する	`time_stretch`, `pitch_shift`, `pitch_correct_to_midi`, `note_stretch`, `voice_change`, `RealtimeVoiceChanger`	解析ではなく音そのものを変えます
ファイルをマスタリングする	`master_audio`, `mastering_chain`, `StreamingMasteringChain`	まずプリセット、必要に応じて明示的なチェーン設定を使います
ライブ音声やチャンク単位の解析	`StreamAnalyzer`	音声ブロックを渡し、特徴フレームと、音が増えるにつれて更新される BPM/キー/コード推定を読み出します
ステムをミックスする	`mix_stereo` または `Mixer.from_scene_json(...)`	一括配列処理から始め、センド・バス・オートメーション・メーターが必要ならシーンミキサーを使います
部屋の残響、明瞭度、等価ルーム推定、ルーム生成を扱う	`analyze_impulse_response`, `detect_acoustic`, `estimate_room`, `synthesize_rir`, `room_morph`	楽曲ではなく録音空間を説明・適用します

インストール

Python 3.11 以上が必要です（3.11、3.12、3.13）。

bash

pip install libsonare

sonare コマンドもあわせてインストールされます。詳しくは CLI リファレンスをご覧ください。

標準の PyPI ホイールは WAV と MP3 をデコードします。読み込まれているビルドが FFmpeg デコードに対応しているかは libsonare.has_ffmpeg_support() で確認できます。M4A/AAC/FLAC/OGG/Opus を直接読み込みたい場合は、リポジトリをクローンし、FFmpeg を有効にしたホイールをビルドしてインストールします。

bash

git clone https://github.com/libraz/libsonare.git
cd libsonare
SONARE_FFMPEG=1 bash bindings/python/build_wheel.sh
python3 -m pip install bindings/python/dist/*.whl

FFmpeg 有効ビルドには FFmpeg の開発ライブラリが必要です。macOS では brew install ffmpeg、Debian/Ubuntu 系では libavformat-dev libavcodec-dev libavutil-dev libswresample-dev をインストールしてください。

ソースからビルド（上級者向け）

PyPI のホイールが利用できない環境では、ソースからビルドすることもできます。

要件:

Python 3.11 以上
CMake 3.16 以上
C++17 対応コンパイラ（対応対象の Linux/macOS では GCC または Clang）
SONARE_FFMPEG=1 でビルドする場合は FFmpeg 開発ライブラリ

bash

git clone https://github.com/libraz/libsonare.git
cd libsonare
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED=ON
cmake --build build -j

cd bindings/python
pip install -e .

クイックスタート

python

from libsonare import Audio, analyze, detect_bpm, detect_key, detect_beats

# ファイルから音声を読み込み
audio = Audio.from_file("music.mp3")

# 個別の解析
bpm = detect_bpm(audio.data, audio.sample_rate)
key = detect_key(audio.data, audio.sample_rate)
beats = detect_beats(audio.data, audio.sample_rate)

# フル解析
result = analyze(audio.data, audio.sample_rate)
print(f"BPM: {result.bpm} ({result.bpm_confidence:.0%})")
print(f"キー: {result.key}")
print(f"拍子: {result.time_signature}")
print(f"ビート数: {len(result.beat_times)}")

エラーハンドリング

例外クラスは 2 つで、あらゆる失敗がどちらかに入ります。引数の型が違う場合だけは素の TypeError です。

送出されるタイミング	クラス	メッセージ
ネイティブライブラリが OK 以外のコードを返したとき	`SonareError`（`RuntimeError` のサブクラス）	`[4]` という数値接頭辞が付きます
バインディングまたはオブジェクトの状態が呼び出しを拒否したとき（読み込んだライブラリにエントリポイントがない、閉じた・解放済みのオブジェクトを使った、ネイティブの結果が健全性検査に通らない）	`NOT_SUPPORTED`、`INVALID_STATE`、`UNKNOWN` のいずれかを持つ `SonareError`	同じ `[code]` 接頭辞が付き、素の `RuntimeError` にはなりません
読み込んだネイティブライブラリがバインディングと一致しないとき	`ABI_MISMATCH`（10）を持つ `SonareError`（`sonare` CLI は終了コード 13）	ライブラリを最初に使う時点で、呼び出しが行われる前に送出されます
引数が拒否されたとき。C ABI に到達する前に Python 側の検証が拒否する場合と、`Project`、`RealtimeEngine`、`transcribe` でライブラリが未知または範囲外の ID・名前・値を拒否する場合	`SonareValueError`	検証メッセージのみで、数値接頭辞は付きません
数値の引数やフィールドに、文字列や `bool` のような数値でないものを渡したとき	`TypeError`	フィールド名と、C 型が持てる区間を示します

SonareValueError は SonareError と ValueError の両方を継承します。そのため except ValueError: でも except sonare.SonareError: でも捕捉でき、どちらの書き方のハンドラも、個々のエントリポイントがどちらのクラスを選ぶかを知る必要がありません。小数・非有限・範囲外の数値は SonareValueError、数値でないものは TypeError で、どちらのハンドラも捕捉しません。.code は引数の拒否なら ErrorCode.INVALID_PARAMETER、読み込めないプロジェクト文書なら C ABI のコード（壊れた JSON は INVALID_FORMAT）です。そのため .code で分岐するコードから見ると、同じ入力を C ABI 側で拒否された場合とまったく同じ扱いになります。SonareError.code は JS バインディングが ErrorCode として公開するのと同じ C ABI の値で、.code_name はバインディング間で共通の名称を返します。どの失敗がどのクラスとコードになるかは、ほかのバインディングと CLI の終了コードも含めてエラー契約にあります。パッケージのビルド時と ABI バージョンが異なるライブラリ、またはバインディングが必要とするシンボルを持たないライブラリは、libsonare ABI mismatch で始まるメッセージとともに ABI_MISMATCH で失敗します。対処はインストールを参照してください。

python

try:
    result = sonare.master_audio_stereo(left, right, sample_rate=48000, preset_name="pop")
except sonare.SonareError as e:
    print(e.code, e.code_name, e)

引数は呼び出し前に検査されます

バッファを受け取るエントリポイントは引数を事前検査します。そのため空・サイズ不一致・非有限値を含むバッファは、内部ヘルパーや素の C シンボルではなく、呼び出した関数の名前で報告されます。

text

master_audio_stereo: right must not be empty
spectral_centroid: samples contains NaN or Inf at index 0

メッセージに現れる名前は、呼び出し側のシグネチャにある名前です。cross_similarity は内部の data ／ rows ではなく x ／ x_rows を報告し、スカラーおよびステレオのメーターは sonare_ 接頭辞付きの C シンボルではなくファサード関数名（metering_peak_db）を報告します。validate を公開しているエントリポイントでは、validate=False を渡すと O(n) の NaN／Inf 走査は省略されますが、空チェックは省略されません。

メッセージ文字列で分岐している場合

SonareError や ValueError を捕捉するハンドラ、.code で分岐するコードは変更不要です。検証メッセージの文字列を照合しているコードは影響を受けます。文言はエントリポイント名と引数名を含む形になっています。

受け付けなくなった入力

trim_silence、split_silence、fix_frames は、空のバッファに対して空の結果を返すのではなく例外を送出します。
tempogram_ratio は、有限かつ正でない factors の要素を拒否します。NaN はコア内で未定義の float→int 変換に到達し、無限大は黙って DC ラグに縮退するためです。
mix_stereo はミックスできないシーンを拒否します。すべてのストリップが空である場合、またはいずれかのストリップが NaN／Inf を含む場合で、ストリップのインデックスとチャンネルを示します（mix_stereo: strips[1] right contains NaN or Inf at index 0）。C ABI では 0 フレームのブロックは「このブロックを処理する」という意味の正当な no-op であり、「このストリップ群をミックスする」という意味ではありません。

検査されないもの

要素ごとの変換は「空を渡せば空が返る」という契約を保っています。power_to_db、amplitude_to_db、db_to_power、db_to_amplitude、preemphasis、deemphasis、vector_normalize、frame_signal、pad_center、fix_length は空のシーケンスを受け取り、空を返します。テンポ系ヘルパーで入力行列を検査するのは tempogram_ratio だけで、tempogram、fourier_tempogram、cyclic_tempogram、plp は検査しません。

f0_hz は非有限値の走査を一切受けません。pYIN は無声フレームを nan で表し、そのトラック表現はピッチ補正へそのまま渡される必要があるためです。note_segments、extract_notes、decompose_note_pitch、split_note、merge_notes は f0_hz の形状だけを検査し、値は検査しません。

「未指定」は `None`

値を持たない任意の数値引数は、省略するか None を渡します。-1 は「未指定」の綴りではなく、SonareValueError で拒否されます。対象は、すべてのトランスポート・パラメータ・MIDI 呼び出しにおけるエンジンの render_frame（None は次のブロック先頭で適用）、SpectralRegionOp.end_sample（None は信号の末尾まで）、fix_frames(x_max=...)、set_program(bank=...) と set_program_on_channel(bank=...)（None は Bank Select を送出しない）、metering_dynamic_range と Audio.dynamic_range のパーセンタイル、vqt と vqt_to_audio の gamma（None は帯域幅の自動選択）です。C ABI では -1 がそのまま使われます。

sonare CLI の引数パーサーが検出する使い方の誤り（未知のフラグ、引数不足、int32 を超える整数オプション、float32 を超える浮動小数オプション）は終了コード 2 です。コマンドが値を拒否した場合は、API 引数ではなくコマンドラインの誤りを報告するため、SonareValueError ではなくプレーンな ValueError を送出し、SonareValueError と同じ 3 で終了します。ABI 不一致は 13 です。CLI の終了コードを参照してください。

このビルドで何ができるか

capabilities() は sonare doctor が表示するのと同じビルド診断レポートを返します。capability_catalog() は、schemas/capability-catalog.schema.json で検証された機械可読なプロセッサ／パラメータ／プリセットのカタログを返します。

python

import libsonare as sonare

caps = sonare.capabilities()
if not caps["features"]["ffmpeg"]:
    print("このホイールがデコードできる形式:", caps["decode"]["builtin"])

catalog = sonare.capability_catalog()
for processor in catalog["processors"]:
    for param in processor["params"]:
        # コアが範囲を宣言していない場合、min / max / default は None になります。
        build_slider(processor["id"], param)

手で管理した表ではなくカタログで分岐してください。パラメータの範囲・既定値・単位・リアルタイム安全性は、すべて読み込まれているビルドから得られます。Node と WASM では同じデータが capabilities() / capabilityCatalog() です。

catalog["masteringPresets"] には、組み込みのマスタリングおよび修復プリセットが並びます。各要素は name、kind、targetLufs、truePeakCeilingDb、maxLimiterGainReductionDb を持ち、修復プリセットでは 3 つの数値フィールドが None になります。プロセッサ要素には条件付きパラメータ群を表す slots もあり、name、parent、activation、minCrossoverCutoffs を持ちます。

長い処理をキャンセルする

進捗を報告する解析・マスタリングの呼び出しは cancel も受け取ります。これは同じネイティブ境界でポーリングされる述語で、True を返すと呼び出しが中断され、SonareError のコード 8（SONARE_ERROR_CANCELLED）になります。途中結果は残りません。

python

import threading

stop = threading.Event()

try:
    result = sonare.master_audio(
        samples,
        sample_rate,
        preset_name="pop",
        on_progress=lambda p, stage: print(stage, p),
        cancel=stop.is_set,
    )
except sonare.SonareError as e:
    if e.code == 8:
        print("キャンセルされました")
    else:
        raise

マスタリング API

Python からもブラウザデモと同じ名前付きマスタリングプロセッサを利用できます。まず一覧取得用のヘルパー関数で、現在のビルドに含まれるプロセッサ名を確認したうえで、モノラル／ステレオ／ペア／解析の各 API をパラメータ明示で呼び出します。フルチェーンは各ステージを下の固定順で実行します。

マスタリングチェーンの順序

有効化したステージだけが処理されますが、有効なステージは常にこの順で実行されます。

目的から入口を選ぶには、次の表を使います。

目的	関数
シンプルなラウドネスマスタリング	`mastering()`
組み込みプリセット一覧	`mastering_preset_names()`
組み込みプリセットのフラットなチェーンパラメータを取得	`mastering_preset_params(preset)`
プリセットをモノラルに適用	`master_audio()`
プリセットをステレオに適用	`master_audio_stereo()`
フルチェーン実行（モノラル）	`mastering_chain()`
フルチェーン実行（ステレオ）	`mastering_chain_stereo()`
ブロック単位のストリーミング	`StreamingMasteringChain`
マスタリング判断用の音源プロファイルを取得	`mastering_audio_profile()`
ステレオ両チャンネルから音源プロファイルを取得	`mastering_audio_profile_stereo()`
音源解析からマスタリングの提案を取得	`mastering_assistant_suggest()`
ステレオ両チャンネルからマスタリングの提案を取得	`mastering_assistant_suggest_stereo()`
アシスタントの提案を JSON ではなくチェーンパラメータとして取得	`mastering_assistant_suggest_chain()`、`mastering_assistant_suggest_chain_stereo()`
配信先ごとのラウドネス見込みをプレビュー	`mastering_streaming_preview()`
ステレオ両チャンネルから配信先ごとのラウドネス見込みをプレビュー	`mastering_streaming_preview_stereo()`
組み込みの配信先一覧	`mastering_platform_names()`
名前付きプロセッサ一覧（モノラル／ステレオ）	`mastering_processor_names()`
プロセッサ分類カタログを取得	`mastering_processor_catalog()`
ギターアンプのプリセットとそのパラメータ一覧	`mastering_amp_preset_catalog()`
チェーンのインサートプロセッサ一覧	`mastering_insert_names()`
インサートが受け付けるパラメータキー一覧	`mastering_insert_param_names(name)`
インサートの構築キーとオートメーション対象の記述子	`mastering_insert_param_info(name)`
構成したインサートのレイテンシとテールを取得	`mastering_insert_timing(name, params, sample_rate)`
モノラルプロセッサを単体で実行	`mastering_process()`
ステレオプロセッサを単体で実行	`mastering_process_stereo()`
ペアプロセッサ一覧	`mastering_pair_processor_names()`
ソース／リファレンスのペア処理	`mastering_pair_process()`
ステレオのソース／リファレンスのペア処理	`mastering_pair_process_stereo()`
ペア解析の一覧	`mastering_pair_analysis_names()`
ソース／リファレンスのペア解析	`mastering_pair_analyze()`
ソースのラウドネスをリファレンスへ合わせる	`mastering_ab_match_loudness()`
ステレオソースのラウドネスをステレオリファレンスへ合わせる	`mastering_ab_match_loudness_stereo()`
ステレオ解析の一覧	`mastering_stereo_analysis_names()`
ステレオチャンネル解析	`mastering_stereo_analyze()`

関連するマスタリングガイド: プリセット選択、配信ターゲット、メーターの読み方、品質チェックリスト。

単体プロセッサの実行

python

import json
import libsonare as sonare

print(sonare.mastering_processor_names())
# 例: ['dynamics.compressor', 'eq.parametric', 'spectral.airBand', 'stereo.imager', ...]

result = sonare.mastering_process(
    "spectral.airBand",
    samples,
    sample_rate=sample_rate,
    params={
        "amount": 0.4,
        "shelfFrequencyHz": 14000,
    },
)

report = sonare.mastering_stereo_analyze(
    "stereo.monoCompatCheck",
    left,
    right,
    sample_rate=sample_rate,
)
print(json.loads(report))

catalog = sonare.mastering_processor_catalog()
insert_params = sonare.mastering_insert_param_info("eq.parametric")

プリセットとフルチェーン

python

# プリセット式のチェーン（一括処理）
sonare.mastering_preset_names()
# -> ['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', 'vinyl', 'tapeHiss', 'fieldRecording', 'voiceMemo', 'shellac78']
preset_params = sonare.mastering_preset_params("aiMusic")
chain_result = sonare.master_audio(
    samples,
    sample_rate=sample_rate,
    preset_name="aiMusic",
    overrides={
        "loudness.targetLufs": -13,
        "maximizer.truePeakLimiter.releaseMs": 50,
        "maximizer.truePeakLimiter.applyGainAtInputRate": False,
    },
)
print(chain_result.output_lufs, chain_result.output_true_peak_dbtp, chain_result.output_lra)
print(chain_result.stage_gain_reductions)
if chain_result.report is not None:
    print(chain_result.report.before, chain_result.report.after)
    print(chain_result.report.band_energy_delta_db)

ストリーミングチェーン

python

# ブロック単位のストリーミング処理
with sonare.StreamingMasteringChain({
    "eq.tilt.tiltDb": 0.5,
    "dynamics.compressor.thresholdDb": -20.0,
}) as chain:
    chain.prepare(sample_rate=48000, max_block_size=512, num_channels=1)
    print(chain.stage_names(), chain.latency_samples)  # latency_samples はプロパティ
    output = chain.process_mono([0.0] * 512)
    while True:
        tail = chain.flush_mono()
        if not tail:
            break
        output.extend(tail)

prepare() のあとに chain.set_parameter(key, value) を呼ぶと、ストリーミングで安全なパラメータをブロック境界で 1 つ変更できます。この呼び出しは処理、フラッシュ、リセット、prepare と直列化されます。未知のキー、構造を変えるキー、無効化したステージのキーは変更前に拒否されるため、失敗してもチェーンと音声履歴は変わりません。パラメータ変更に自動スムージングはありません。

ストリーミング入力の最終ブロック後は、空のリストが返るまで flush_mono() を呼び、ステレオでは 2 つの空リストが返るまで flush_stereo() を呼びます。

アシスタント・プロファイル・プレビュー

python

profile = json.loads(sonare.mastering_audio_profile(samples, sample_rate=sample_rate, params={
    "n_fft": 2048,
    "hop_length": 512,
    "true_peak_oversample": 4,
}))
suggestions = json.loads(sonare.mastering_assistant_suggest(samples, sample_rate=sample_rate, params={
    "target_lufs": -14,
    "ceiling_db": -1,
    "prefer_streaming_safe": True,
}))
preview = json.loads(sonare.mastering_streaming_preview(samples, sample_rate=sample_rate, platforms=[
    {"name": "YouTube", "targetLufs": -14, "ceilingDb": -1},
    {"name": "Podcast", "targetLufs": -16, "ceilingDb": -1},
]))
# ステレオ入口: パラメータも戻り値の JSON も同じで、測定だけが両チャンネル基準になります。
stereo_profile = json.loads(sonare.mastering_audio_profile_stereo(left, right, sample_rate=sample_rate, params={
    "n_fft": 2048,
    "hop_length": 512,
    "true_peak_oversample": 4,
}))
stereo_suggestions = json.loads(sonare.mastering_assistant_suggest_stereo(left, right, sample_rate=sample_rate, params={
    "target_lufs": -14,
    "ceiling_db": -1,
    "prefer_streaming_safe": True,
}))
# platforms を省略すると、組み込みの Spotify / Apple Music / YouTube のセットが使われます。
stereo_preview = json.loads(sonare.mastering_streaming_preview_stereo(left, right, sample_rate=sample_rate))

3 つの JSON ヘルパーにはそれぞれ _stereo 版があります。バッファ 1 本ではなく left と right を受け取り、params / platforms は同じもの、戻り値も同じ JSON 文字列です。2 チャンネルの素材を扱うときは常にこちらを使ってください。モノラル側の入口は 0.5 * (left + right) のダウンミックスを測定するため、相関の低いステレオ素材では約 6 dB 低く出ます。その分だけ、積分ラウドネス、そこから導かれる正規化ゲイン、ピーク余裕の判定がまとめて過小評価されます。

ステレオ版を使う理由

相関を落としたピンクノイズのペア（48 kHz・4 秒）では、ダウンミックス経由が -22.55 LUFS、ステレオ経由が -16.44 LUFS で、差は 6.11 dB でした。同じ差が Spotify の normalizationGainDb を +2.44 から +8.55 に押し上げます。相関の高いペアでは差は 3.01 dB にとどまり、これはダウンミックスで振幅が半分になる分です。残りの約 3 dB が相関の低さによるものです。

ステレオプロファイルのうち、両チャンネルから測るのは loudness ブロックだけです。積分 LUFS と LRA はチャンネルを合算したプログラムから求め、True Peak は 2 つのうち大きい方を採ります。スペクトル・ダイナミクス・テンポの各フィールドは絶対レベルではなく形と時間構造を表すため、ダウンミックス基準のまま据え置き、モノラル呼び出しの結果とそのまま比較できます。

オプションと結果フィールド

エントリポイント／結果	キー	備考
`mastering_audio_profile(params=)`	`n_fft`、`hop_length`、`true_peak_oversample`	すべて任意です。
`mastering_assistant_suggest(params=)`	`target_lufs`、`ceiling_db`、`enable_repair`、`prefer_streaming_safe`、`speech_mono_amount`	共有ネイティブパーサーを通るため、camelCase の別名も使えます。
`mastering(...)`	`release_ms`、`apply_gain_at_input_rate`	リミッターのリリースと静的ゲイン段の位置です。`release_ms=0` は 50 ms のライブラリ既定値を維持します。プリセットやチェーンの上書きではフラットキーの `"maximizer.truePeakLimiter.releaseMs"` と `"maximizer.truePeakLimiter.applyGainAtInputRate"` を使い、渡した値がそのまま適用されます。
オフラインのチェーン／プリセット結果	`output_true_peak_dbtp`、`output_lra`、`stage_gain_reductions`	True Peak は設定したラウドネス用オーバーサンプル倍率で測ります。`output_lra` は EBU R128 のラウドネスレンジ（LU）です。各リダクションには、ダイナミクスまたはマキシマイザーのステージ名と、その直近のゲインリダクション（0 以下の dB）が入ります。
`result.report`	`before`、`after`、`band_energy_delta_db`	`before` と `after` にはそれぞれ `integrated_lufs`、`max_momentary_lufs`、`max_short_term_lufs`、`true_peak_dbtp`、`loudness_range` が入ります。`band_energy_delta_db` は処理前後の対数スペクトルエネルギー変化を示す 32 バンドの値です。レポートには適用ゲイン、最大ゲインリダクション、ピークの余裕によってラウドネス目標が制限されたかどうかも入ります。

リファレンストラックを使う処理

リファレンストラックを使う処理では mastering_pair_processor_names()、mastering_pair_process()、mastering_pair_process_stereo()、mastering_pair_analysis_names()、mastering_pair_analyze() を使います。モノラルの mastering_pair_process(processor_name, source, reference, sample_rate=22050, params=None, *, reference_sample_rate=None) は MasteringResult を返し、ソースとリファレンスの長さが異なっていても処理できます。ステレオ版は source_left、source_right、reference_left、reference_right を受け取り、left、right、sample_rate、input_lufs、output_lufs、applied_gain_db、latency_samples、loudness_target_limited、non_finite_substitution_count を持つ MasteringStereoResult を返します。各ソースペアと各リファレンスペアは左右の長さを揃える必要がありますが、ソースペアとリファレンスペアの長さは異なって構いません。ステレオの match.abCrossfade は短い方のペア長を使います。ペアプロセッサ、ペア解析、A/B マッチはいずれも reference_sample_rate（既定は sample_rate）を受け取ります。別のレートのリファレンスはソースのレートへリサンプルされ、遅延推定はソースのレートのサンプル数で返ります。

ラウドネスを揃えた A/B 比較には、mastering_ab_match_loudness(source, reference, sample_rate=22050, *, with_match=True, reference_sample_rate=None) を使うと (np.ndarray, LoudnessMatch | None) が返ります。mastering_ab_match_loudness_stereo(source_left, source_right, reference_left, reference_right, sample_rate=22050, *, with_match=True, reference_sample_rate=None) は ((np.ndarray, np.ndarray), LoudnessMatch | None) を返します。ステレオの各ソース／リファレンスペアは左右の長さを揃えますが、ソースとリファレンスの長さは異なって構いません。ステレオ版はソースの両チャンネルに 1 つのゲインを共有して適用し、シーリングは行いません。

単発のダイナミクスとリペア

名前付きの各ステージは、単発のモジュールレベル関数としても利用できます。チェーンを組まずに 1 つのプロセッサだけを実行できます。パラメータはキーワード専用で、対応する MasteringChainConfig のキーを snake_case にしたものです。ダイナミクス系は (processed_samples, latency_samples) のタプルを返し、latency_samples は int です。リペア系は処理後サンプル（np.ndarray）を返します。

関数	戻り値	主なパラメータ
`mastering_dynamics_compressor(samples, sample_rate?, *, ...)`	`tuple[np.ndarray, int]`	`threshold_db=-18.0`、`ratio=2.0`、`attack_ms=10.0`、`release_ms=100.0`、`knee_db`、`makeup_gain_db`、`auto_makeup`、`detector='rms'`、`sidechain_hpf_enabled`、`sidechain_hpf_hz`、`pdr_time_ms`、`pdr_release_scale`
`mastering_dynamics_gate(samples, sample_rate?, *, ...)`	`tuple[np.ndarray, int]`	`threshold_db=-50.0`、`attack_ms=2.0`、`release_ms=80.0`、`range_db=-80.0`、`hold_ms`、`close_threshold_db`、`key_hpf_hz`
`mastering_dynamics_transient_shaper(samples, sample_rate?, *, ...)`	`tuple[np.ndarray, int]`	`attack_gain_db=3.0`、`sustain_gain_db`、`fast_attack_ms`、`fast_release_ms=20.0`、`slow_attack_ms=15.0`、`slow_release_ms=200.0`、`sensitivity=1.0`、`max_gain_db=12.0`、`gain_smoothing_ms`、`lookahead_ms`
`mastering_repair_declick(samples, sample_rate?, *, ...)`	`np.ndarray`	`threshold=0.8`、`neighbor_ratio=4.0`、`max_click_samples=8`、`lpc_order=20`、`residual_ratio=8.0`
`mastering_repair_declip(samples, sample_rate?, *, ...)`	`np.ndarray`	`clip_threshold=0.98`、`lpc_order=36`、`iterations=2`、`lpc_blend=0.65`
`mastering_repair_decrackle(samples, sample_rate?, *, ...)`	`np.ndarray`	`threshold=0.4`、`mode='median'`、`levels=4`
`mastering_repair_dehum(samples, sample_rate?, *, ...)`	`np.ndarray`	`fundamental_hz=50.0`、`harmonics=4`、`q=20.0`、`adaptive`、`search_range_hz`、`adaptation`、`frame_size`、`pll_bandwidth`、`mode='subtract'`
`mastering_repair_denoise_classical(samples, sample_rate?, *, ...)`	`np.ndarray`	`mode='logMmse'`、`noise_estimator='quantile'`、`n_fft=1024`、`hop_length=256`、`dd_alpha=0.98`、`reduction_db=26.0`、`over_subtraction=2.0`、`spectral_floor=0.05`、`noise_estimation_quantile=0.1`、`speech_presence_gain`、`gain_smoothing`
`mastering_repair_dereverb_classical(samples, sample_rate?, *, ...)`	`np.ndarray`	`threshold=0.0`、`attenuation=1.0`、`n_fft=1024`、`hop_length=256`、`t60_sec=0.4`、`late_delay_ms=50.0`、`over_subtraction=1.0`、`spectral_floor=0.08`、`wpe_enabled`、`wpe_iterations`、`wpe_taps`、`wpe_strength`
`mastering_repair_trim_silence(samples, sample_rate?, *, ...)`	`np.ndarray`	`threshold=0.001`、`padding_samples` または `padding_sec`（どちらか一方）、`mode='peak'`、`gate_lufs=-60.0`、`window_ms=400.0`

信号全体を対象とするリペアステージ（declick、declip、decrackle、dehum、dereverb）は StreamingMasteringChain では拒否されます。これらの単発ヘルパー、または mastering_chain* / master_audio* の中で実行してください。リアルタイムエンジンでは、decrackle、dehum、クラシックなデノイザー、クラシックなデリバーブがカタログ ID のインサートとしても使えます。declick と declip はオフラインのままです。

リペア系の各ヘルパーには _stereo 版があり、デノイザーとデリバーブにはチャンネルを 1 つのプログラムとして扱う _linked 版もあります。mastering_repair_detect_* 関数は、音声を変えずに欠陥（クリック、ノイズフロア、クリッピング、クラックル、ハム、残響、トリム範囲）を測定します。mastering_repair_dereverb_config_for_room(estimate) は RoomEstimate から完全なデリバーブ設定を作ります。

任意のチャンネル数の音声は 2 回の呼び出しでリペアできます。mastering_repair_analyze(channels, sample_rate) はチャンネルごとの欠陥を測定し、アシスタントが実行するステージを recommended として返します（そのまま渡せます。デリバーブは推奨されません）。mastering_repair_apply(channels, sample_rate, stages=[...]) はそれを実行します。ステージはリストの順序に関わらず、declip、declick、decrackle、dehum、denoise、dereverb の固定順で実行され、重複したステージや未知の設定は拒否されます。結果には、リペア後のチャンネルと、ステージごとのレポート（チャンネルごと、またはリンクされた denoise と dereverb では 1 回）が入り、on_progress / cancel は進捗コールバックと同じ使い方です。

python

analysis = sonare.mastering_repair_analyze([left, right], 48000)
result = sonare.mastering_repair_apply([left, right], 48000, stages=analysis["recommended"])

streaming_loudness_gain(samples, sample_rate, config) と streaming_loudness_gain_stereo(left, right, sample_rate, config) は、StreamingMasteringChain の構築に使う数値を、ラウドネスステージの入力で測定します。戻り値の StreamingLoudnessGain は loudness_static_gain_db（オフラインチェーンが適用するゲインと等しく、シーリングのクランプを含みます。無音では 0）、true_peak_db、integrated_lufs を持ちます。前の 2 つをコンストラクタの loudness_static_gain_db と loudness_static_gain_peak_db に渡します。詳細はダイナミクスとリペアを参照してください。

進捗コールバック

mastering_chain()、mastering_chain_stereo()、master_audio()、master_audio_stereo() は、オプションの on_progress=callable キーワードを受け取ります。

このコールバックは、各ステージ完了時に (progress: float, stage: str) で呼び出されます。

値	意味
`progress`	`0.0`〜`1.0` の全体進捗。
`stage`	完了した名前付きプロセッサ。例: `eq.tilt`, `dynamics.compressor`, `loudness.targetLufs`。

UI の進捗バー表示や、ステージごとの所要時間ロギングに利用できます。

python

def on_step(progress: float, stage: str) -> None:
    print(f"{progress:5.1%}  {stage}")

result = sonare.mastering_chain(
    samples,
    sample_rate=sample_rate,
    config={"loudness": {"targetLufs": -14, "ceilingDb": -1}},
    on_progress=on_step,
)

設定キーとインサート記述子

設定 dict からは、任意バンド数のマルチバンドコンプレッサーも扱えます。dynamics.multibandComp は crossover（cutoffsHz、slope、mode、firKernelSize）と bands（バンドごとの dict）を受け付けます。overrides ではフラットキーの dynamics.multibandComp.crossover.cutoffsHz.<i> と dynamics.multibandComp.bands.<i>.<field> も使えます。バンド数は 2 から 64 で、cutoffsHz はカットオフ一覧を置き換えて、バンド数を要素数 + 1 に決めます。列挙型のキーは数値と並んで choices の名前でも指定できます（"repair.denoise.noiseEstimator": "spp"、dynamics.compressor.detector、マルチバンドのスロープ・モード・ディテクターのキー）。mastering_process、mastering_process_stereo、mastering_insert_timing の params も同じ名前を受け付けます。repair.denoise.enabled を有効にしたストリーミングチェーンは、ノイズ推定器の既定が spp で、quantile は名前を示して拒否されます。

mastering_insert_param_info(name, sample_rate=None) は、インサートが構築時に読むキーとリアルタイムオートメーション対象の記述子を返します。型、範囲、既定値、選択肢、条件付きの slot、範囲を動かす兄弟キーを示す dependsOn / coupledWith を確認できます。sample_rate を渡すと、ナイキスト周波数で決まる上限がそのレートで解決され、オフラインのリペアステージを含むすべてのカタログ id に答えます。mastering_insert_timing(name, params, sample_rate) はそのパラメータでインサートを構築し、latencySamples と tailSamples を返します。インサートが読まないキーは拒否されます。params は記述子が宣言するあらゆる値の型（数値、真偽値、列挙名、文字列、数値のリスト）を受け付け、型の違う値は TypeError、有限でない数値は SonareValueError です。mastering_preset_params(preset) はプリセットのフラットな上書きマップを返し、そのまま master_audio(..., overrides=...) に渡せます。

ミキシング API

Python からも libsonare のミキシングエンジンを使えます。ステムを一括でレンダリングするだけなら mix_stereo(...)、センド、バス、オートメーション、メーター、シーンの保存が必要ならシーン JSON から読み込む Mixer を使います。組み込みのシーンプリセット一覧は mixing_scene_preset_names() で取得できます。

python

import libsonare as sonare

print(sonare.mixing_scene_preset_names())
scene_json = sonare.mixing_scene_preset_json("vocalReverbSend")

offline = sonare.mix_stereo(
    [(vocal_l, vocal_r), (music_l, music_r)],
    sample_rate=48000,
    input_trim_db=[3, 0],
    fader_db=[-3, -12],
    pan=[0, -0.2],
    width=[1, 0.9],
)

with sonare.Mixer.from_scene_json(scene_json, sample_rate=48000, block_size=512) as mixer:
    print(mixer.scene_warnings())  # 非致命的: どのプロセッサも読まない insert パラメータ（タイプミス）
    print(mixer.latency_samples())  # ドライ／ウェット整列用のコンパイル済みグラフ遅延
    block = mixer.process_stereo([vocal_block_l, music_block_l], [vocal_block_r, music_block_r])
    meter = mixer.strip_meter(0, tap="postFader")
    mixer.schedule_fader_automation(0, 48000 * 8, -6, curve="s-curve")

mixer.process_stereo(...) は MixerStereoResult 名前付きタプルを返します。.left と .right（list[float]）、.sample_rate（int）を持ち、Node/WASM の {left, right, sampleRate} と同じ形です。入力チャンネルがストリップより少ない場合、残りのストリップは無音になります。入力チャンネルがストリップより多い場合は、両方の数を示す SonareValueError が送出されます。

Mixer.set_pan_law(...) と RealtimeEngine.set_track_strip_pan_law(...) は、PanLaw enum、整数の序数、または大文字小文字を区別しない文字列エイリアスを受け取ります。const3db、const-3db、-3db、const4.5db、const-4.5db、-4.5db、const6db、const-6db、-6db、linear0db、linear-0db、linear、0db が使え、アンダースコアはハイフンとして扱われます。

ルーティングの考え方、シーンプリセット、リアルタイム処理の注意点はミキシングエンジンを参照してください。

プロジェクト・インストゥルメント・ライブ MIDI

ヘッドレス DAW の機能群は Python からも利用できます。Project でアレンジを作り、内蔵インストゥルメントでレンダリングし、ライブ MIDI をリアルタイムエンジンへ送れます。詳細は各専用ガイドにあります。ここは Python の入口をまとめたマップです。

やりたいこと	API	ガイド
トラック、クリップ、テンポ、マーカー、undo/redo を編集する	`Project`（コンテキストマネージャ。`with` を使う）	プロジェクト編集
内蔵シンセサイザー（NativeSynth）で MIDI をレンダリングする	`Project.bounce_with_synth_instrument(...)`、`synth_preset_names()`、`synth_preset_patch(name)`、`SynthPatch`	内蔵シンセサイザー、プロジェクトのバウンス
SoundFont で MIDI をレンダリングする	`Project.load_soundfont(data)`、`Project.bounce_with_sf2_instrument(...)`	SoundFont プレイヤー
バウンス中に自前のインストゥルメントをホストする	`ExternalInstrument` プロトコルを使う `Project.bounce_with_instruments(...)`。`render(channels, num_frames)` コールバックに加え、任意の `prepare`/`on_event` フックと `latency_samples` を持ちます。Node と WASM には、コールバック形式が `bounceWithInstruments` / `bounceWithInstrument` としてあります。	プロジェクトのバウンス
MIDI イベントからインストゥルメントをライブ演奏し、送出先（デスティネーション）の MIDI FX を差し替える	`RealtimeEngine.set_synth_instrument(...)`、`RealtimeEngine.load_soundfont(...)`、`RealtimeEngine.set_midi_fx(...)`、エンジンの MIDI 入力キュー（各 push は `offset_in_block_samples` を取り、絶対的なクロック位置ではなく、次に処理されるブロック内のオフセットを表します）、`push_midi_program(...)` / `push_midi_input_program(...)`（バンク指定を含められるプログラムチェンジを 1 回の呼び出しで送る。SoundFont プレイヤーと GM プログラムを割り当てたシンセはバンクに従う）	MIDI 入力
ライブエンジンへ MIDI クリップをサンプル精度でスケジュールする	`EngineMidiClipSchedule` / `EngineMidiEvent` を渡す `RealtimeEngine.set_midi_clips([...])`、`RealtimeEngine.sample_at_ppq(ppq)`。ppq は音楽的時間の単位で、四分音符あたりのパルス数です	リアルタイムエンジン
トラック単位のキューモニタリングを設定する	`RealtimeEngine.set_track_monitor_mode(lane_index, mode, render_frame=None)`。`EngineTrackMonitorMode`（`off`／`pfl`／`afl`）を使います。PFL はフェーダー前、AFL はフェーダー後を試聴します。`process()` は有効なキューをプログラム出力に折り込みますが、オフラインのレンダリング、バウンス、フリーズには含まれません	リアルタイムエンジン
デスティネーションを外部 MIDI ハードウェアへ送る	`set_midi_destination_external(...)`、`set_external_midi_clock_enabled(...)`、`drain_external_midi(...)`、`external_midi_dropped_count()`	プロジェクト編集：MIDI
エンジンのトラックをライブミックス／自動化する	レーン／ストリップ操作に加え、`set_track_sends(track_id, sends)`、`set_track_output_bus(track_id, bus_id)`、`set_bus_strip_insert_param_by_name(...)`、`set_bus_strip_insert_bypassed(...)`、`resolve_track_insert_automation_id(...)`、`resolve_master_insert_automation_id(...)`、`resolve_bus_insert_automation_id(...)`、`set_param_smoothing_ms(...)`	リアルタイムエンジン
ワイドメーターとスコープを読む	`drain_meter_telemetry_wide(...)`、`configure_scope_telemetry(...)`、`drain_scope_telemetry(...)`	リアルタイムエンジン

python

import libsonare as sonare

with sonare.Project() as project:
    project.set_sample_rate(48000)
    track = project.add_track(kind="midi")
    # ... クリップと MIDI イベントを追加（プロジェクト編集ガイドを参照） ...
    audio = project.bounce_with_synth_instrument("e-piano", num_channels=2)

ネイティブメモリを所有するオブジェクト（Audio、Project、Mixer、RealtimeEngine、StreamAnalyzer、RealtimeVoiceChanger、StreamingMasteringChain、StreamingEqualizer など）はすべて close() を持ち、コンテキストマネージャとして使えます。close() のあとにメソッドを呼ぶと、INVALID_STATE を持つ SonareError になります。

シンセプリセットの確認には synth_preset_patch(name) を使います。名前付きカタログプリセットを SynthPatch として返すので、バインドする前にフィールドを確認・調整できます（不明な名前では SonareError を送出し、'va:' ルーティング接頭辞も受け付けます）。synth_enum_tables() は実行時の enum 名テーブル（dict[str, tuple[str, ...]]）を返し、SynthModRouting のソース／デスティネーション名を、読み込まれたビルドに対して検証できます。エンジンモード・波形・フィルター・モジュレーションのテーブルに加えて、sample_loop_modes、sample_key_tracks、retriggers、lfo_shapes、part_rig_modes、sample_desc_loop_modes も含みます。

SynthPatch の数値フィールドはすべて既定値が None で、「ベースプリセットの値を保つ」という意味です。設定していないフィールドを読むと 0.0 ではなく None が返り、値を渡せばそれは明示的な上書きになります。0 も同様なので、SynthPatch(preset="warm-pad", amp_sustain=0) は未設定として扱われず、アンプサステインを本当にゼロにします。synth_preset_patch(name) から得たパッチはプリセットの具体値で埋まって返るため、数値フィールドが None になることはありません。enum フィールド（engine_mode、waveform、filter_model、filter_output、body、retrigger、lfo_shape）では 0 ／ "default" が「ベースを保つ」を意味します。mod_routings=None はベースのモッドマトリクスを保ち、空タプルは消去、要素のあるタプルは置き換えです。lfo_shape は "triangle"・"sine"・"random"（ボイスごとにシードされる滑らかなサンプル＆ホールド）で、ビブラートとトレモロの LFO にすべての宛先で効きます。filter_model="svf-4-pole" は飽和しない 24 dB/オクターブのローパスです。synth_patch_param_info() が示す範囲の外や非有限の数値フィールドは、クランプされずに名前を挙げて拒否されます。

不透明なアシストサイドカー

Project は、プロジェクトごとでアンドゥ可能、モジュールが所有する不透明なバイト列（アシストサイドカー）を保持できます。スコープはモジュール ID・ターゲットトラック・領域です。project.set_assist_sidecar(module_id, payload, *, schema_version=0, target_track_id=0, region_start_ppq=0.0, region_end_ppq=0.0) で設定し、project.assist_sidecar_count()、project.get_assist_sidecar(index) -> AssistSidecar、project.assist_sidecars() で読み出します。バインディング間の詳細はプロジェクト編集を参照してください。

その他のエントリポイント

他のページが扱う分野の関数と型です。完全なシグネチャは、パッケージに同梱の型スタブにあります。

やりたいこと	API	ガイド
検出済みのコードに、再検出なしでローマ数字と機能を付ける	`chord_functions(chords, key)`（`FunctionalChord` のリストを返す）	解析
解析にチューニングを測定させ、Hz に変換する	`analyze`、`detect_chords`、`detect_key` の `tuning="auto"`（`KeyDetection` が使った `tuning` を持つ）、`transcribe` の `reference_hz="auto"`、`tuning_to_reference_hz`、`reference_hz_to_tuning`	音声からノートへ
モノフォニックなテイクを、検出または指定したキーに合わせる	`auto_tune(samples, sample_rate, key="detect")`（`AutoTuneResult` を返す。Python エフェクト API）、`scale_mask_for_mode(root, mode)`（Python 解析 API）	Python エフェクト API
パラメータを言い直さずに Mel／MFCC の結果を逆変換する	`mel_result_to_stft`、`mel_result_to_audio`、`mfcc_result_to_mel`、`mfcc_result_to_audio`	逆変換
検出したコードやキーをアレンジの注釈に変換する	`chord_symbol_from_analysis(chord)`、`key_mode_from_analysis(mode)`	プロジェクト編集：MIDI
ルーム推定を `synthesize_rir` の入力にする	`room_geometry_from_estimate(estimate, source=..., listener=...)`（`RoomGeometry` を返し、`source`、`listener`、`absorption` は上書きしない限り推定結果から導かれます）	音響解析
デコードした全チャンネルを保持する、またはチャンネルを狭いレイアウトに畳み込む	`decode_channels(data)`（`(channels, sample_rate)` を返す）、`downmix(channels, target_layout)`（センターとサラウンドは -3 dB、LFE は破棄）	チャンネル形式
サイドチェイン接続が受理されるか、されないならなぜかを尋ねる	`RealtimeEngine.can_set_lane_sidechain`、`can_set_bus_sidechain`、`can_set_master_sidechain`（`SidechainCheck` を返す）	リアルタイムエンジン
エンジンのクリップ集合を 1 クリップずつ編集する	`RealtimeEngine.upsert_clip`、`remove_clip`	リアルタイムエンジン
プロセッサのリセット、繰り返しレンダリングの準備、テールとレイテンシの読み取り	`reset_processor_state`、`prime_offline_parameters`、`tail_samples`、`graph_latency_samples_q8`	リアルタイムエンジン
フェーダー・パン・ウィズのオートメーションをトラック、バス、マスターで指定する	`resolve_track_lane_automation_id`、`resolve_bus_automation_id`、`resolve_master_automation_id`（`"faderDb"`・`"pan"`・`"width"`）。`resolve_instrument_automation_id(destination_id, param_name)` を含むすべての `resolve_*_automation_id` は、未知のトラック・バス・インサート・デスティネーション・パラメータ、またはリアルタイム安全でないパラメータに `SonareValueError` を送出します	リアルタイムエンジン
エンジンの音声を配列で受け取る、レーン数の上限	`RealtimeEngine.process`、`process_with_monitor`、`render_offline` は float32 の NumPy 配列（チャンネルごとの配列のリスト）を返し、`EngineBounceResult.interleaved` は float32 配列です。`set_track_lanes` は `MAX_TRACK_LANES`（32）レーンまでで、それより長いリストは `SonareValueError` です	リアルタイムエンジン
既存のプレイバックレンダラーでバッファをレンダリングする	`PlaybackRenderer.render_offline(samples, in_channels)` はレンダラーをリセットし、インターリーブされたバッファをレンダリングして、インターリーブされた float32 配列を返します。その後の `diagnostics()` はこのレンダリングを表します。閉じたレンダラーは `INVALID_STATE` の `SonareError` です	プレイバックレンダラー
信号の終わりで True Peak メーターの保留ウィンドウを反映する	`Mixer.flush_meters()`	ミキシングエンジン
プロジェクトで解決できなかったオーディオソースを列挙する	`Project.unresolved_audio_sources()`	プロジェクト編集
ミキサーシーンの認識されないキーを読む	`Mixer.scene_warnings()`	ミキシングシーン JSON

リファレンスの所在

ページ	内容
Python 解析 API	Audio、解析関数、特徴抽出、逆再構成、メータリング、スケール量子化、変換、ストリーミング解析
Python エフェクト API	オーディオエフェクト、ルーム音響解析、エフェクト関数、リアルタイムボイスチェンジャー、librosa 互換ヘルパー、ストリーミング EQ
Python 型定義	結果とオプションの型、例外

Python API ​

Python での考え方 ​

このリファレンスの読み方 ​

目的から API を選ぶ ​

インストール ​

ソースからビルド（上級者向け） ​

クイックスタート ​

エラーハンドリング ​

引数は呼び出し前に検査されます ​

受け付けなくなった入力 ​

検査されないもの ​

「未指定」は None ​

このビルドで何ができるか ​

長い処理をキャンセルする ​

マスタリング API ​

単体プロセッサの実行 ​

プリセットとフルチェーン ​

ストリーミングチェーン ​

アシスタント・プロファイル・プレビュー ​

オプションと結果フィールド ​

リファレンストラックを使う処理 ​

単発のダイナミクスとリペア ​

進捗コールバック ​

設定キーとインサート記述子 ​

ミキシング API ​

プロジェクト・インストゥルメント・ライブ MIDI ​

不透明なアシストサイドカー ​

その他のエントリポイント ​

リファレンスの所在 ​

Python API

Python での考え方

このリファレンスの読み方

目的から API を選ぶ

インストール

ソースからビルド（上級者向け）

クイックスタート

エラーハンドリング

引数は呼び出し前に検査されます

受け付けなくなった入力

検査されないもの

「未指定」は `None`

このビルドで何ができるか

長い処理をキャンセルする

マスタリング API

単体プロセッサの実行

プリセットとフルチェーン

ストリーミングチェーン

アシスタント・プロファイル・プレビュー

オプションと結果フィールド

リファレンストラックを使う処理

単発のダイナミクスとリペア

進捗コールバック

設定キーとインサート記述子

ミキシング API

プロジェクト・インストゥルメント・ライブ MIDI

不透明なアシストサイドカー

その他のエントリポイント

リファレンスの所在