Transformers documentation
FeatureExtractors用のユーティリティ
FeatureExtractors用のユーティリティ
このページでは、生のオーディオから Short Time Fourier Transform や log mel spectrogram などの一般的なアルゴリズムを用いて特別な特徴量を計算するために、オーディオの FeatureExtractor で使用できるすべてのユーティリティ関数をリストしています。
それらの多くは、ライブラリ内のオーディオプロセッサのコードを研究する場合にのみ有用です。
オーディオ変換
transformers.audio_utils.hertz_to_mel
< source >( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
ヘルツからメルへ周波数を変換します。
transformers.audio_utils.mel_to_hertz
< source >( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
周波数をメルからヘルツに変換します。
transformers.audio_utils.mel_filter_bank
< source >( num_frequency_bins: intnum_mel_filters: intmin_frequency: floatmax_frequency: floatsampling_rate: intnorm: str | None = Nonemel_scale: str = 'htk'triangularize_in_mel_space: bool = Falsedtype: str | numpy.dtype = <class 'numpy.float64'> ) → np.ndarray of shape (num_frequency_bins, num_mel_filters)
パラメータ
- num_frequency_bins (
int) — 周波数ビンの数（スペクトログラムを計算するために使用されるフーリエ変換のサイズであるn_fftに対して、n_fft // 2 + 1と同じである必要があります）。 - num_mel_filters (
int) — 生成する mel フィルタの数。 - min_frequency (
float) — 対象とする最低周波数 (Hz)。 - max_frequency (
float) — 対象とする最大周波数(Hz)です。sampling_rate / 2を超えてはいけません。 - sampling_rate (
int) — オーディオ波形のサンプリングレート。 - norm (
str、任意) —"slaney"の場合、三角形の mel 重みを mel バンドの幅で割ります(面積正規化)。 - mel_scale (
str、任意、デフォルトは"htk") — 使用するメル周波数スケール。"htk"、"kaldi"、または"slaney"。 - triangularize_in_mel_space (
bool、省略可、デフォルトはFalse) — このオプションを有効にすると、周波数空間ではなくメル空間で三角状のフィルタが適用されます。メルフィルタを計算する際にtorchaudioと同一の結果を得るには、trueに設定する必要があります。 - dtype (
strまたはnp.dtype、省略可能、デフォルトはnp.float64) — 返されるフィルターのデータ型です。三角形のフィルターは float64 で計算され、"slaney"正規化の前にdtypeにキャストされます。norm="slaney"、mel_scale="slaney"、dtype=np.float32の場合、結果はlibrosa.filters.mel(..., norm="slaney")（転置後）とビット単位で一致します。
戻り値
形状が(num_frequency_bins, num_mel_filters)のnp.ndarray
三角形のフィルタバンク行列。これはスペクトログラムからメルスペクトログラムへの変換を行う射影行列です。
Melスペクトラムの取得に使用される周波数ビンの変換行列を作成します。これはメルフィルタバンクと呼ばれ、フィルタの数、フィルタの形状、フィルタの配置方法、フィルタの帯域幅、スペクトラムの変形方法など、実装によって異なる点があります。これらの機能の目的は、周波数に対するピッチの変化に対する人間の非線形な知覚を近似することです。
文献では、異なるバンクのメルフフィルタが提案されています。以下のバリエーションがサポートされています:
- MFCC FB-20: 1980年にDavisとMermelsteinによって導入されました。サンプリング周波数は10 kHz、音声帯域幅は
[0, 4600]Hzであると仮定しています。 - MFCC FB-24 HTK: Cambridge HMM Toolkit (HTK) (1995) は、音声帯域幅
[0, 8000]Hz に対して 24 フィルターのフィルタバンクを使用します。これはサンプリングレートが 16 kHz 以上であることを前提としています。 - MFCC FB-40: 1998年にSlaney氏によって作成されたMATLAB用Auditory Toolboxからのもの。サンプリングレート16 kHzおよび音声帯域幅
[133, 6854]Hzを前提としています。このバージョンでは、面積正規化も含まれています。 - Skowronski と Harris (2004) の HFCC-E FB-29 (Human Factor Cepstral Coefficients) は、サンプリングレートが 12.5 kHz、音声帯域が
[0, 6250]Hz であると仮定しています。
このコードは torchaudio および librosa から適応したものです。torchaudio の melscale_fbanks のデフォルトパラメータは "htk" フィルターを実装していますが、librosa は "slaney" 実装を使用しています。
window_length に対して最適な FFT 入力サイズを求めます。この関数は、指定されたウィンドウ長を受け取り、2 の累乗でない場合は、次の 2 の累乗に切り上げます。
FFTアルゴリズムは、入力の長さが2の累乗である場合に最も高速に動作します。この長さは、ウィンドウまたは解析フレームのサイズよりも大きくなる場合があります。例えば、ウィンドウが400サンプルの場合、FFTの入力サイズを512サンプルに設定する方が、400サンプルに設定するよりも最適です。より大きなFFTサイズを使用しても、検出される周波数には影響しません。単に周波数分解能が高まる（つまり、周波数ビンの幅が狭くなる）だけです。
transformers.audio_utils.window_function
< source >( window_length: intname: str = 'hann'periodic: bool = Trueframe_length: int | None = Nonecenter: bool = True )
パラメータ
- window_length (
int) — サンプル単位のウィンドウの長さです。 - name (
str、任意、デフォルトは"hann") — ウィンドウ関数の名前です。 - periodic (
bool、省略可能、デフォルトはTrue) — ウィンドウが周期的であるか対称であるかを指定します。 - frame_length (
int, 任意) — 解析フレームの長さ（サンプル数）。ウィンドウがフレーム長より小さい場合は、ゼロパディングが適用されるようにframe_lengthの値を指定してください。 - center (
bool、任意、デフォルトはTrue) — FFT バッファ内でウィンドウを中央に配置するかどうか。frame_lengthが指定された場合のみ使用されます。
指定されたウィンドウを含む配列を返します。このウィンドウはstftで使用することを意図しています。
サポートされているウィンドウタイプは以下の通りです:
"boxcar": 矩形ウィンドウ"hamming": ハミング窓"hann": ハン窓"povey": Povey ウィンドウ
transformers.audio_utils.spectrogram
< source >( waveform: ndarraywindow: ndarrayframe_length: inthop_length: intfft_length: int | None = Nonepower: float | None = 1.0center: bool = Truepad_mode: str = 'reflect'onesided: bool = Truedither: float = 0.0preemphasis: float | None = Nonemel_filters: numpy.ndarray | None = Nonemel_floor: float = 1e-10log_mel: str | None = Nonereference: float = 1.0min_value: float = 1e-10db_range: float | None = Noneremove_dc_offset: bool = Falsedtype: dtype = <class 'numpy.float32'> )
パラメータ
- waveform (
np.ndarray、shape(length,)) — 入力波形です。これは、単一の実数値のモノラル波形である必要があります。 - window (
np.ndarray、shape(frame_length,)) — 適用するウィンドウ関数です。必要に応じてゼロパディングを含みます。実際のウィンドウ長はframe_lengthより短くなる場合がありますが、配列はすでにゼロパディング済みであると仮定しています。 - frame_length (
int) — サンプル単位の解析フレームの長さです。librosa では常にfft_lengthと等しくなりますが、より小さいサイズも許可しています。 - hop_length (
int) — 連続する解析フレーム間のサンプル単位のストライドです。 - fft_length (
int, 任意) — FFTバッファのサイズ（サンプル数）です。スペクトログラムの周波数ビンの数を決定します。 最適な速度を得るためには、2のべき乗であるべきです。Noneの場合、frame_lengthが使用されます。 - power (
float、任意、デフォルト値は 1.0)— 1.0 の場合は振幅スペクトグラムを返します。2.0 の場合は電力スペクトグラムを返します。Noneの場合は複素数を返します。 - center (
bool、省略可能、デフォルトはTrue) — フレームtが時刻t * hop_lengthの中心に来るように、波形をパディングするかどうか。Falseの場合、フレームtは時刻t * hop_lengthから始まります。 - pad_mode (
str, 任意、デフォルトは"reflect") —centerがTrueの場合に使用されるパディングモード。指定可能な値は、"constant"（ゼロでパディング）、"edge"（端の値でパディング）、"reflect"（ミラーリングされた値でパディング）です。 - onesided (
bool、省略可能、デフォルトはTrue) — True の場合、正の周波数のみを計算し、fft_length // 2 + 1個の周波数ビンを含まれるスペクトログラムを返します。False の場合、負の周波数も計算し、fft_length個の周波数ビンを返します。 - dither (
float、任意、デフォルトは 0.0) — ディザリングを追加します。つまり、各フレームに小さなガウスノイズを加えます。 例えば、4.0 を指定すると、平均 0.0、標準偏差 4.0 の正規分布によるディザリングが追加され、0.0 はディザリングなしを意味します。 ディザリングはmel_floorと同様の効果を持ちます。信号に VAD カットオフが存在する場合、ハードゼロ区間を持つ信号の log_mel_fbank の高値を低減します。 - preemphasis (
float、省略可) — DFTの前にプリエンファシスを行うローパスフィルタの係数。 - mel_filters (
np.ndarray、形状(num_freq_bins, num_mel_filters)、任意) — Mel フィルターバンクです。指定された場合、このフィルターバンクを適用して Mel スペクトログラムを生成します。 - mel_floor (
float、任意、デフォルト値: 1e-10) — メル周波数バンクの最小値。 - log_mel (
str, 任意) — スペクトログラムを対数スケールに変換する方法。指定可能なオプションは、None（変換しない）、"log"（自然対数を取る）、"log10"（10を底とする対数を取る）、"dB"（デシベルに変換する）です。powerがNoneでない場合にのみ使用できます。 - reference (
float、任意、デフォルト値は 1.0) — 0 dB に対応する入力スペクトログラムの値を設定します。例えば、np.max(spectrogram)を使用すると、最も大きな音が 0 dB になります。0 より大きい値である必要があります。 - min_value (
float、任意、デフォルトは1e-10) — デシベル変換の前にスペクトログラムをこの最小値でクリップし、log(0)を取ることを避けます。パワースペクトログラムの場合、デフォルトの1e-10は最小 -100 dB に相当します。振幅スペクトログラムの場合、値1e-5が -100 dB に相当します。ゼロより大きい値である必要があります。 - db_range (
float, 任意) — デシベル単位での最大ダイナミックレンジを設定します。例えば、db_range = 80の場合、ピーク値と最小値の差は 80 dB を超えることはありません。0 より大きい値を指定する必要があります。 - remove_dc_offset (
bool, 省略可) — 各フレームの波形から平均値を差し引きます。これはプリエンファシス適用前に実行されます。Melフィルタを計算する際にtorchaudio.compliance.kaldi.fbankと同一の結果を得るためには、trueに設定する必要があります。 - dtype (
np.dtype、任意、デフォルトはnp.float32) — スペクトログラムテンソルのデータ型です。powerが None の場合、この引数は無視され、dtype はnp.complex64になります。
Short-Time Fourier Transformを用いて、1つの波形に対するスペクトログラムを計算します。
この関数は、以下の種類のスペクトログラムを作成できます。
- 振幅スペクトログラム（
power = 1.0） - パワースペクトログラム（
power = 2.0） - 複素数値スペクトログラム（
power = None） - logスペクトログラム（
log_mel引数を使用） - melスペクトログラム(
mel_filtersを指定) - log-mel スペクトログラム(
mel_filtersとlog_melを指定)
仕組み:
- 入力波形はサイズ
frame_lengthのフレームに分割され、- hop_length` サンプル。
- 各フレームはウィンドウで乗算され、サイズが
fft_lengthのバッファに格納されます。 - 各ウィンドウ処理されたフレームに対してDFTが計算されます。
- 結果はスペクトログラムにスタックされます。
サンプルデータの以下の「ブロック」を区別します。それぞれが異なる長さを持つ可能性があります。
- 解析フレーム。入力波形を分割する時間スライスのサイズです。
- ウィンドウ。各解析フレームは、スペクトルリークを回避するためにウィンドウで乗算されます。
- FFT入力バッファ。この長さが、スペクトログラムに含まれる周波数ビンの数を決定します。
この実装では、ウィンドウは解析フレームと同じサイズになるようゼロパディングされていると仮定されます。パディング済みのウィンドウはwindow_function()から取得できます。FFTの入力バッファは、解析フレームよりも大きい場合があり、通常は次の2の累乗です。
注: この関数はまだ速度の最適化が施されていません。librosa.stft および torchaudio.functional.transforms.Spectrogram とほぼ互換性がありますが、スペクトログラムの構築方法が異なるため、より柔軟性があります。
transformers.audio_utils.power_to_db
< source >( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-10db_range: float | None = None ) → np.ndarray
パラメータ
- spectrogram (
np.ndarray) — 入力のパワー（メル）スペクトログラムです。なお、パワースペクトログラムでは振幅が二乗されています。 - reference (
float、任意、デフォルト値は 1.0) — 0 dB に対応する入力スペクトログラムの値を設定します。例えば、np.max(spectrogram)を使用すると、最も大きな音が 0 dB になります。0 より大きい値である必要があります。 - min_value (
float、任意、デフォルトは1e-10) — デシベル変換の前にスペクトログラムをこの最小値にクリップし、log(0)を取ることを避けます。デフォルトの1e-10は -100 dB の最小値に対応します。ゼロより大きい値である必要があります。 - db_range (
float, 任意) — デシベル単位での最大ダイナミックレンジを設定します。例えば、db_range = 80の場合、ピーク値と最小値の差は 80 dB を超えることはありません。0 より大きい値を指定する必要があります。
戻り値
np.ndarray
デシベル表示のスペクトログラム
パワースペクトログラムをデシベルスケールに変換します。10 * log10(spectrogram / reference)を計算し、数値の安定性を確保するために基本的な対数の性質を利用します。
(mel)スペクトログラムにlog関数を適用する動機は、人間の聴覚が線形スケールで音の大きさを認識しないことにあります。一般的に、知覚される音量を2倍にするには、エネルギーを8倍にする必要があります。つまり、音がもともと大きい場合、エネルギーの大きな変動はそれほど大きく聞こえない可能性があります。この圧縮操作により、(mel)スペクトログラムの特徴量が、人間が実際に聴き取る音にさらに近づきます。
librosa.power_to_dbの実装に基づいています。
transformers.audio_utils.amplitude_to_db
< source >( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-05db_range: float | None = None ) → np.ndarray
パラメータ
- spectrogram (
np.ndarray) — 入力振幅(mel)スペクトログラム。 - reference (
float、任意、デフォルト値は 1.0) — 0 dB に対応する入力スペクトログラムの値を設定します。例えば、np.max(spectrogram)を使用すると、最も大きな音が 0 dB になります。0 より大きい値である必要があります。 - min_value (
float、任意、デフォルトは1e-5) — デシベル変換の前にスペクトログラムをこの最小値でクリップし、log(0)を取ることを避けます。デフォルトの1e-5は -100 dB の最小値に対応します。ゼロより大きい値である必要があります。 - db_range (
float, 任意) — デシベル単位での最大ダイナミックレンジを設定します。例えば、db_range = 80の場合、ピーク値と最小値の差は 80 dB を超えることはありません。0 より大きい値を指定する必要があります。
戻り値
np.ndarray
デシベル表示のスペクトログラム
振幅スペクトログラムをデシベルスケールに変換します。20 * log10(spectrogram / reference)を計算し、数値の安定性を確保するために基本的な対数の性質を利用します。
(mel)スペクトログラムにlog関数を適用する動機は、人間の聴覚が線形スケールで音の大きさを認識しないことにあります。一般的に、知覚される音量を2倍にするには、エネルギーを8倍にする必要があります。つまり、音がもともと大きい場合、エネルギーの大きな変動はそれほど大きく聞こえない可能性があります。この圧縮操作により、(mel)スペクトログラムの特徴量が、人間が実際に聴き取る音にさらに近づきます。