Python 型定義
libsonare Python パッケージの結果型と設定型のリファレンスです。これらを返す関数は Python API の索引ページと、その姉妹ページを参照してください。
型定義
結果オブジェクトは属性アクセスできる通常のクラスです。多くは JS との対応のため camelCase のプロパティ別名（例: bpm_confidence / bpmConfidence）も公開します。以下はデータフィールドの形です。
行優先（row-major）の行列レイアウト
このページで「row-major」と記した平坦化フィールドは、[rows x n] の行列を行ごとに並べたものです。先頭の n 個が 0 行目、次の n 個が 1 行目…と続きます。行数で reshape すると 2 次元の NumPy 配列に戻せます。
import numpy as np
mat = np.asarray(flat).reshape(rows, n) # 例: 12 ピッチクラスのクロマグラムなら reshape(12, n_frames)class PitchClass(IntEnum):
C, CS, D, DS, E, F, FS, G, GS, A, AS, B
class Mode(IntEnum):
MAJOR = 0
MINOR = 1
DORIAN = 2
PHRYGIAN = 3
LYDIAN = 4
MIXOLYDIAN = 5
LOCRIAN = 6
class KeyProfile(IntEnum):
KRUMHANSL_SCHMUCKLER = 0
TEMPERLEY = 1
SHAATH = 2
FARALDO_EDMT = 3
FARALDO_EDMA = 4
FARALDO_EDMM = 5
BELLMAN_BUDGE = 6
class Key:
root: PitchClass
mode: Mode
confidence: float # スコアリングされた候補全体のソフトマックス配分。[0, 1)
name: str # プロパティ -> "C major"、"A minor" など
short_name: str # プロパティ -> "C"、"Am" など
class KeyDetection(Key): # detect_key(...) の戻り値の型
tuning: float # クロマの生成に使った半音の端数（指定値または測定値）
class TimeSignature:
numerator: int
denominator: int
confidence: float
class BpmHypothesis:
value: float
confidence: float
relation: Literal["primary", "half", "double", "other"]
class Chord:
root: PitchClass
quality: str # "major"、"minor"、"diminished"、"augmented"、
# "dominant7"、"major7"、"minor7"、"sus2"、"sus4"、
# "add9"、"minorAdd9"、"dim7"、"halfDim7"、
# "major9"、"dominant9"、"sus2Add4"、
# "major6"、"minor6"、"minorMajor7"、
# "dominant7Sus4"、"dominant11"、"dominant13"、
# "dominant7Flat9"、"dominant7Sharp9"、"unknown"
start: float # セグメント開始（秒）
end: float # セグメント終了（秒）
confidence: float
bass: PitchClass | None # スラッシュコードのベース音。root と同じなら None
canonical_name: str
name: str # プロパティ -> "Cmaj7"、"Am"、"G/B"
root_name: str # プロパティ -> "C"（別名 rootName）
bass_name: str # プロパティ（別名 bassName）
duration: float # プロパティ -> end - start
roman_numeral: str | None # analyze() のコードでは解析キーに対するローマ数字
# N.C. は空文字列。それ以外のコード結果では None
class FunctionalChord(Chord): # chord_functions(...) と chord_functional_analysis(...) の戻り値の型
roman: str # "I"、"V7"、"vi"。未知のコードは "N.C."
function: str # "tonic"、"subdominant"、"dominant"、"chromatic"、"none"
class ChordAnalysisResult:
chords: list[Chord] # detect_chords(...) の戻り値の型
tuning: float # クロマの生成に使った半音の端数（指定値または測定値）
class AutoTuneResult: # auto_tune(...) の戻り値の型
samples: list[float] # 補正後の音声。入力と同じ長さ
key: Key # 検出したキー、または呼び出しで指定したキー（confidence 1）
class AnalysisBeatObservations:
onset_strength: list[float] # 拍ごとの、窓処理済みアクセント値
low_frequency_energy: list[float]
chord_change: list[float]
class AnalysisResult:
bpm: float
bpm_confidence: float
key: Key
time_signature: TimeSignature
beat_times: list[float]
beat_strengths: list[float] # 拍ごとの、生で上限のないオンセットエンベロープ 1 フレーム
downbeat_indices: list[int] # beat_times のうち小節頭にあたる位置
downbeat_phase: int # 解析が第 1 小節の何拍目から始まるか
beat_local_bpm: list[float] # beat_times と平行。compute_tempo_curve=True
# でないかぎり空
tuning: float # クロマグラムの生成に使った半音の端数
bpm_candidates: list[BpmHypothesis]
time_signature_candidates: list[TimeSignature]
beats: list[Beat] # プロパティ: 各拍の強度を持つオブジェクト
# (Beat はパッケージ直下ではなく libsonare.types にある)
chords: list[Chord]
sections: list[Section]
timbre: AnalysisTimbre | None
dynamics: AnalysisDynamics | None
rhythm: AnalysisRhythm | None
melody: AnalysisMelody | None
beat_observations: AnalysisBeatObservations | None
form: str
# 専用の detect_chords() / analyze_sections() / analyze_timbre() / ... は、
# 1 つの側面だけ、または呼び出しごとのオプション指定に使えます。
class MeterEstimate:
time_signature: TimeSignature
downbeat_phase: int
searched: bool # False = 系列が短すぎてスコアリングできなかった
grouping: list[int] # アクセントグループ（例 [3, 2, 2]）。合計は分子
candidate_scores: list[float] # 指定した分子の並びと平行
candidates: list[TimeSignature] # 支持度の降順
class NormalizeStereoResult:
left: list[float]
right: list[float]
length: int
applied_gain_db: float # 両チャンネルに適用された単一のゲイン
class HpssResult:
harmonic: list[float]
percussive: list[float]
length: int
sample_rate: int
class StftResult:
n_bins: int
n_frames: int
n_fft: int
hop_length: int
sample_rate: int
magnitude: list[float] # n_bins × n_frames, row-major
power: list[float] # n_bins × n_frames, row-major
class StftMagnitudeResult: # mel_to_stft(...) / mel_result_to_stft(...) の戻り値
n_bins: int
n_frames: int
magnitude: list[float] # n_bins × n_frames, row-major
class MelPowerResult: # mfcc_to_mel(...) / mfcc_result_to_mel(...) の戻り値
n_mels: int
n_frames: int
power: list[float] # n_mels × n_frames, row-major
class MelSpectrogramResult:
n_mels: int
n_frames: int
sample_rate: int
hop_length: int
power: list[float] # n_mels × n_frames, row-major
db: list[float] # n_mels × n_frames, row-major
n_fft: int # 順変換のパラメータ。結果だけで逆変換できる
fmin: float # 適用された値
fmax: float # 適用された値。リクエストが 0 のときはナイキスト
htk: bool
is_db: bool # 順変換では False。power は線形パワー、db はその dB 表現
class MfccResult:
n_mfcc: int
n_frames: int
coefficients: list[float] # n_mfcc × n_frames, row-major
sample_rate: int
hop_length: int
n_fft: int
n_mels: int
fmin: float
fmax: float
htk: bool
is_db: bool # 常に False
lifter: float # 0 は未適用
class ChromaResult:
n_chroma: int
n_frames: int
sample_rate: int
hop_length: int
features: list[float] # n_chroma × n_frames, row-major
mean_energy: list[float] # n_chroma values
class PitchResult:
n_frames: int
f0: list[float] # フレームごとの基本周波数（Hz）
voiced_prob: list[float] # フレームごとの有声確率（0–1）
voiced_flag: list[bool] # フレームごとの有声/無声判定
median_f0: float
mean_f0: float
class WaveformPeaksReport:
min: NDArray[np.float32] # チャンネルメジャー: channel * bucket_count + bucket
max: NDArray[np.float32] # チャンネルメジャー
channels: int
bucket_count: int
samples_per_bucket: int
class StreamConfig:
sample_rate: int = 44100
n_fft: int = 2048 # 44100 Hz でのサンプル数。それ未満のレートでは再スケールされ、hop_length を下回らない
hop_length: int = 512
n_mels: int = 128
fmin: float = 0.0
fmax: float = 0.0
tuning_ref_hz: float = 440.0
compute_magnitude: bool = False
compute_mel: bool = True
compute_chroma: bool = True
compute_onset: bool = True
compute_spectral: bool = True
emit_every_n_frames: int = 1
magnitude_downsample: int = 1
max_pending_frames: int = 4096 # 上限到達時は新たに生成されたフレームを破棄
max_progression_entries: int = 4096 # 進行データそれぞれの保持上限
key_update_interval_sec: float = 5.0
bpm_update_interval_sec: float = 10.0
window: int = 0 # 0=Hann, 1=Hamming, 2=Blackman, 3=Rectangular
output_format: int = 0 # レガシー。省略するか Float32 の値（0）を維持
class StreamFrames:
n_frames: int
n_mels: int
n_chroma: int # クロマがあれば 12、なければ 0
feature_flags: int # MEL=1, CHROMA=2, ONSET=4, SPECTRAL=8
timestamps: list[float]
mel: list[float] # n_frames × n_mels。MEL がなければ空
chroma: list[float] # n_frames × n_chroma。CHROMA がなければ空
onset_strength: list[float] # ONSET がなければ空
rms_energy: list[float]
spectral_centroid: list[float] # SPECTRAL がなければ空
spectral_flatness: list[float] # SPECTRAL がなければ空
chord_root: list[int] # CHROMA がなければ空
chord_quality: list[int] # CHROMA がなければ空
chord_confidence: list[float] # CHROMA がなければ空
class StreamChordChange:
root: int
quality: int
name: str # バッチ解析と同じ綴りのコード名
start_time: float
confidence: float
class StreamBarChord:
bar_index: int
root: int
quality: int
name: str
start_time: float
confidence: float
class StreamPatternScore:
name: str
score: float
class StreamStats:
total_frames: int
total_samples: int
duration_seconds: float
pending_frames: int
dropped_output_frames: int
dropped_chord_progression_entries: int
dropped_bar_progression_entries: int
non_finite_discard_blocks: int # NaN／Inf の入力が置き換えられたブロック数。reset() で消える
bpm: float
bpm_confidence: float
bpm_candidate_count: int
key: int # キーが未推定の間（無音など）は -1
key_minor: bool
key_confidence: float
key_name: str | None # "C major"。キーが未推定の間は None
key_short_name: str | None # "C"、"Am"
chord_root: int # コードなしは -1
chord_quality: int
chord_name: str # コードなしは "N.C."
chord_confidence: float
chord_start_time: float
current_bar: int
bar_duration: float
chord_progression: list[StreamChordChange]
bar_chord_progression: list[StreamBarChord]
voted_pattern: list[StreamBarChord]
pattern_length: int
detected_pattern_name: str
detected_pattern_score: float
all_pattern_scores: list[StreamPatternScore]
accumulated_seconds: float
used_frames: int
updated: bool個別 API が返す追加の Python 結果クラス:
| 分野 | クラス |
|---|---|
| メータリング | ClippingRegion, StreamFramesU8, StreamFramesI16, WaveformPeaksReport |
| マスタリング | MasteringResult, MasteringStereoResult, StreamingLoudnessGain（streaming_loudness_gain* の戻り値） |
| マスタリングの JSON ドキュメント | アシスタント、プロファイル、解析ヘルパーが返す JSON 文字列に対応する TypedDict: MasteringAudioProfile（MasteringAudioProfileLoudness, MasteringAudioProfileSpectral, MasteringAudioProfileDynamics, MasteringAudioProfileDefects）、MasteringAssistantProfile, MasteringAssistantResult, MasteringChainConfigDocument, MasteringStreamingPreviewResult, MasteringStreamingPreviewPlatform, MasteringRepairAnalysis, MatchReferenceLoudnessResult, MatchTonalBalanceResult, MatchTonalBalanceBand, MatchTonalBalanceLogBandsResult, MatchEqCurveResult, MatchEstimateReferenceDelaySamplesResult, StereoMonoCompatCheckResult, StereoMonoCompatBand, StereoMonoCompatCheckLogBandsResult。関数は引き続き JSON 文字列を返すので、json.loads で解析し、結果にこれらの型を注釈します |
| リペア | RepairApplyResult, RepairStageReports（mastering_repair_apply の戻り値） |
| 音響 | RoomEstimate（volume、length_m、width_m、height_m、drr_db、confidence、band_absorption、rt60_bands）、RoomMorphResult（audio、sample_rate、diagnostics）、RoomMorphStereoResult（left、right、sample_rate、diagnostics。room_morph_stereo の戻り値）、RoomGeometry（room_geometry_from_estimate の戻り値となる TypedDict）、MaterialPresetName, AcousticModeName |
| 解析のリテラル型 | ChordFunctionName |
| ミキシング | MixTrackInput（track_id、left、right、name、sample_rate。別のレートのトラックは呼び出しのレートへリサンプルされます）、MixerStereoResult, SidechainCheck（ok と、最初の拒否理由 reason。エンジンの can_set_*_sidechain の戻り値） |
| プロジェクト | AssistSidecar（project.get_assist_sidecar(index) / project.assist_sidecars() の戻り値。プロジェクト編集 を参照）、NotePairValidation |
| リアルタイムエンジンのジョブ／テレメトリ | EngineBounceOptions, EngineBounceResult, EngineFreezeOptions, EngineFreezeResult, EngineCaptureStatus, EngineTelemetry, EngineTelemetryType, EngineTelemetryError, MeterTelemetryRecord, MeterTelemetryRecordWide, ScopeTelemetryRecord |
| ビルド情報 | Capabilities, CapabilityCatalog, CapabilityCatalogPresets, CapabilityCatalogChain, CapabilityCatalogChainStage, CapabilityCatalogChainList, CapabilityCatalogChainAlias, SynthParamInfo, MasteringPresetCatalogEntry, MasteringInsertParamInfo, MasteringInsertParamUnit, MasteringInsertParamScale, MasteringInsertParamRelation, MasteringInsertParamDependency, MasteringInsertSlot, MasteringInsertTiming, MasteringProcessorCatalogEntry（機能カタログ で説明している JSON ドキュメントに対応する TypedDict） |
CapabilityCatalog["chain"]（CapabilityCatalogChain）は、フラットなマスタリングチェーンキーすべてを記述します。ステージ、項目数付きのインデックス付きリスト、どのプロセッサにも属さないキー、別名表記すべてです。CapabilityCatalog["presets"]["playbackRoom"] は常に存在します。SynthParamInfo（synth_engine_param_info と synth_patch_param_info が返す）は name、type（"number" または "boolean"）、default、unit と、省略可能な integer、min、max、activeWhen を持ちます。default は float | bool で、スイッチでは bool です。activeWhen は SynthParamCondition（key、scope（"engine" または "patch"）、relation（"eq"、"ne"、"gt"、"ge"、"lt"、"le" のいずれか）、value）の dict を、選択肢ごとにリストにまとめたリストです。どれか 1 つの内側のリストの条件がすべて成り立てば、そのフィールドはボイスに届きます。無条件のフィールドでは存在しません。CapabilityCatalog["masteringPresets"] は name、kind、targetLufs、truePeakCeilingDb、maxLimiterGainReductionDb を持つ MasteringPresetCatalogEntry を返します。修復プリセットでは 3 つの数値フィールドが None です。MasteringProcessorCatalogEntry の slots は条件付きキー群を列挙し、causal は repair.declick、repair.declip、repair.trimSilence で false です。MasteringInsertParamInfo の記述子は id、rtSafe、type、min、max、default、unit（閉じた集合 MasteringInsertParamUnit の値）、scale（linear または log）、uiMin / uiMax（[min, max] の内側に置く任意の表示範囲）、dependsOn（現在値がこのキーの範囲を左右する兄弟キー。それぞれ key、relation、factor を持ち、this <relation> factor * sibling と読む）、coupledWith（受け入れ範囲を動かすそのほかの兄弟キーのリスト。min / max はそれらを既定値にして測った値）、choices、slot を持ち、MasteringInsertTiming は指定したインサート構成の latencySamples と tailSamples を持ちます。
例外
失敗はすべて 2 つのクラスで表します。後者は前者を継承しているので、2 本ではなく 1 本の階層です。ErrorCode は、それらが運ぶコードの IntEnum です。
class SonareError(RuntimeError):
code: int # C ABI のエラーコード（ErrorCode の値）
code_name: str # プロパティ -> "InvalidParameter"、"FileNotFound" など
# str(e) -> "[4] Invalid parameter": メッセージの先頭にコードが付く
class ErrorCode(IntEnum):
OK = 0
FILE_NOT_FOUND = 1
INVALID_FORMAT = 2
DECODE_FAILED = 3
INVALID_PARAMETER = 4
OUT_OF_MEMORY = 5
NOT_SUPPORTED = 6
INVALID_STATE = 7
CANCELLED = 8
ENCODE_FAILED = 9
ABI_MISMATCH = 10 # バインディング専用: 読み込んだライブラリがバインディングと一致しない
UNKNOWN = 99
class SonareValueError(SonareError, ValueError):
code: int # 送出側が別のコードを渡さないかぎり ErrorCode.INVALID_PARAMETER
# str(e) -> "spectral_centroid: samples contains NaN or Inf at index 0": 接頭辞なしライブラリまたはオブジェクトの状態に由来する失敗は、常に対応するコードを持つ SonareError です。読み込んだライブラリにエントリポイントがなければ NOT_SUPPORTED、閉じたオブジェクトなら INVALID_STATE、ネイティブの結果が健全性検査に通らなければ UNKNOWN です。そのため except RuntimeError は引き続き捕捉でき、.code で場合を区別できます。ABI_MISMATCH は、読み込んだライブラリの ABI バージョンがバインディングと異なるとき、ライブラリを最初に使う時点で送出されます。これらのコードとほかのバインディング、CLI の終了コードとの対応はエラー契約にあります。
SonareValueError は、呼び出しがネイティブコードへ渡る前にバインディングが引数を拒否したとき、また Project、RealtimeEngine、transcribe でコアが未知または範囲外の ID や値を拒否したときに送出されます。数値の引数に数値でないものを渡した場合は、どちらのクラスでもなく TypeError です。どの基底クラスを継承しているかによって、既存のハンドラでどう捕捉されるかが決まります。
| ハンドラ | バインディングの拒否（SonareValueError） | コアの拒否（SonareError、コード 4） |
|---|---|---|
except ValueError | 捕捉する | 捕捉しない |
except SonareError または except RuntimeError | 捕捉する | 捕捉する |
except SonareValueError | 捕捉する | 捕捉しない |
.code == ErrorCode.INVALID_PARAMETER で分岐 | 一致する | 一致する |
インスタンスが持つのはメッセージだけです。問題のパラメータ名を持つ属性も、受理範囲を持つ属性もありません。構造化されたフィールドは .code のみで、引数の拒否ではどれも INVALID_PARAMETER を返します。読み込めないプロジェクト文書だけは C ABI のコード（壊れた JSON は INVALID_FORMAT）を持ちます。パラメータ名と、あるなら範囲は本文に含まれます。バッファの拒否はエントリポイントと引数を名指しし（master_audio_stereo: right must not be empty）、スカラーの拒否はフィールド名と C 型が表現できる区間を示します（sample_rate must be an integer within [-2147483648, 2147483647]）。名前が必要なコードは str(e) から読み取るしかありません。文言と、文言でのマッチが壊れやすい理由は Python API を参照してください。
検証層はどこで止まるか
バインディングの検証は 2 層で、それぞれの形を知っていれば、呼び出し側で SonareValueError が出たときに何が除外できたかが分かります。
サンプルバッファは、先頭パラメータがサンプルバッファである公開エントリポイントすべてで事前検査されます。 共通の事前検査ガードを通るか、同じ検査を本体に直接書いています。検査対象のバッファは連続した 1 次元 float32 配列へ変換され、空なら拒否され、NaN と Inf を走査されます。走査を省くのは、エントリポイントが validate を公開していて呼び出しが validate=False を渡したときだけです（空チェックは省かれません）。ノート系関数に渡す F0 トラックは形だけを検査します。pYIN は無声フレームを nan で表すからです。この集合は手で管理せず導出しています。バインディングのテストが、先頭パラメータにバッファの型注釈を持つ公開関数をすべて列挙し、ガードのないものがあれば失敗します。サンプルのリストに None の要素があれば、NaN サンプルとしてではなく samples[7] is None, not a number のように名指しで報告されます。
スカラーは関数ごとではなく、変換の時点で絞り込まれます。 バインディングの ctypes 読み取りや設定構造体のフィールドを通る整数・浮動小数は、C 型が値を黙って変えてしまう場合に拒否されます。ラップする整数（c_int のサンプルレートに渡した 2**32 + 8000）、c_float で飽和する倍精度値、整数フィールドへの小数、NaN や無限大がそれです。これらは SonareValueError です。文字列や bool のように数値ですらない値は素の TypeError になるため、except ValueError では捕捉されません。メッセージにはフィールド名と区間が入ります。検査が変換の位置にあるため、その値を渡すエントリポイントすべてに効き、関数ごとの数を管理する必要がありません。
5 つのエントリポイントは、結果を返さず拒否します。 拒否は「検査して続行する」とは別の契約です。以下は、定義済みの空の結果を返す代わりに入力をそのまま拒否するものです。trim_silence、split_silence、fix_frames は空のバッファで送出します。tempogram_ratio は空の行列と、有限の正数でない factors の要素で送出します。mix_stereo はストリップがすべて空か、非有限のサンプルを含むシーンで送出します。それぞれの理由は 受け付けなくなった入力 にあります。
この層が しない ことは次のとおりです。
- 値の意味を判断すること。 絞り込みは数値が表現可能かを確かめるだけで、プロセッサが受け入れるかは見ません。
dynamics.compressorのratio=0.5はコアまで届き、SonareErrorコード 4 とメッセージcompressor ratio must be at least 1で返ってきます。effects.modulation.chorusのdryWet=5のようにインサートの範囲外の値や、utility.gainのgainDbのようにプロセッサが読まないキーも、同様に名前を挙げて拒否されます。一部のエントリポイントは Python 側でドメイン規則も検査します。古典的リペア関数のn_fftが 2 の冪であること、hpssのカーネルが奇数であること、time_stretchとpitch_shiftの FFT ジオメトリがそれで、メッセージの読み方は同じです。それ以外の値の意味は、コアが判断します。 params辞書を読むこと。mastering_process、チェーン、インサートに渡すパラメータ辞書は、そのまま直列化されます。未知のキーはプロセッサに無視され、非有限の値はバインディングではなくコアが拒否します（mastering parameters must be finite and representable）。呼び出し側で拒否したいなら、事前に 機能カタログ と照合してください。- 免除対象を事前検査すること。 空のバッファが定義済みの結果になるエントリポイント（要素ごとの変換、パディング補助、テンポグラム系）は空を受け取って空を返します。一覧は 検査されないもの にあります。
- CLI 自身の引数を扱うこと。 コマンドラインの使い方の誤りは通常の
ValueErrorです。API の引数ではなくコマンドの誤りを報告するものだからです。