Transformers 文件
FeatureExtractor 的實用工具
並獲得增強的文件體驗
開始使用
FeatureExtractor 實用工具
本頁面列出了音訊 FeatureExtractor 可以使用的所有實用函式，以便使用常見演算法（如短時傅立葉變換或對數梅爾頻譜圖）從原始音訊計算特殊特徵。
其中大多數僅在您研究庫中音訊處理器的程式碼時有用。
音訊變換
transformers.audio_utils.hertz_to_mel
< 來源 >( freq: typing.Union[float, numpy.ndarray] mel_scale: str = 'htk' ) → float 或 np.ndarray
將頻率從赫茲轉換為梅爾。
transformers.audio_utils.mel_to_hertz
< 來源 >( mels: typing.Union[float, numpy.ndarray] mel_scale: str = 'htk' ) → float 或 np.ndarray
將頻率從梅爾轉換為赫茲。
transformers.audio_utils.mel_filter_bank
< 來源 >( num_frequency_bins: int num_mel_filters: int min_frequency: float max_frequency: float sampling_rate: int norm: typing.Optional[str] = None mel_scale: str = 'htk' triangularize_in_mel_space: bool = False ) → np.ndarray 形態為 (num_frequency_bins, num_mel_filters)
引數
- num_frequency_bins (
int) — 頻率桶的數量（應與n_fft // 2 + 1相同，其中n_fft是用於計算頻譜圖的傅立葉變換的大小）。 - num_mel_filters (
int) — 要生成的梅爾濾波器數量。 - min_frequency (
float) — 感興趣的最低頻率，單位為赫茲。 - max_frequency (
float) — 感興趣的最高頻率，單位為赫茲。這不應超過sampling_rate / 2。 - sampling_rate (
int) — 音訊波形的取樣率。 - norm (
str, 可選) — 如果為"slaney"，則將三角梅爾權重除以梅爾頻帶的寬度（面積歸一化）。 - mel_scale (
str, 可選, 預設為"htk") — 要使用的梅爾頻率刻度，可以是"htk"、"kaldi"或"slaney"。 - triangularize_in_mel_space (
bool, 可選, 預設為False) — 如果啟用此選項，則三角濾波器將在梅爾空間而不是頻率空間應用。為了獲得與torchaudio計算梅爾濾波器時相同的結果，應將其設定為true。
返回
np.ndarray 形態為 (num_frequency_bins, num_mel_filters)
三角濾波器組矩陣。這是一個從頻譜圖到梅爾頻譜圖的投影矩陣。
建立一個用於獲取梅爾頻譜圖的頻率桶轉換矩陣。這被稱為梅爾濾波器組，存在各種實現，它們在濾波器數量、濾波器形狀、濾波器間距方式、濾波器頻寬以及頻譜扭曲方式上有所不同。這些特徵的目標是近似人類對音高相對於頻率變化的非線性感知。
文獻中引入了不同的梅爾濾波器組。支援以下變體：
- MFCC FB-20：由 Davis 和 Mermelstein 於 1980 年引入，它假設取樣頻率為 10 kHz，語音頻寬為
[0, 4600]Hz。 - MFCC FB-24 HTK：來自劍橋 HMM 工具包 (HTK) (1995)，使用 24 個濾波器的濾波器組，語音頻寬為
[0, 8000]Hz。這假設取樣率 ≥ 16 kHz。 - MFCC FB-40：來自 Slaney 於 1998 年編寫的 MATLAB 聽覺工具箱，假設取樣率為 16 kHz，語音頻寬為
[133, 6854]Hz。此版本還包括面積歸一化。 - HFCC-E FB-29 (人因倒譜系數) by Skowronski and Harris (2004)，假設取樣率為 12.5 kHz，語音頻寬為
[0, 6250]Hz。
此程式碼改編自 torchaudio 和 librosa。請注意，torchaudio 的 melscale_fbanks 預設引數實現了 "htk" 濾波器，而 librosa 使用 "slaney" 實現。
找到給定 window_length 的最佳 FFT 輸入大小。此函式獲取給定視窗長度，如果它不是 2 的冪，則將其向上舍入到下一個 2 的冪。
當輸入長度為 2 的冪時，FFT 演算法執行最快，這可能大於視窗或分析幀的大小。例如，如果視窗為 400 個樣本，則使用 512 個樣本的 FFT 輸入大小比 400 個樣本的 FFT 大小更最佳化。使用更大的 FFT 大小不會影響檢測到的頻率，它只會提供更高的頻率解析度（即頻率桶更小）。
transformers.audio_utils.window_function
< 來源 >( window_length: int name: str = 'hann' periodic: bool = True frame_length: typing.Optional[int] = None center: bool = True )
返回包含指定視窗的陣列。此視窗旨在與 stft 一起使用。
支援以下視窗型別
"boxcar"：矩形視窗"hamming"：漢明視窗"hann"：漢寧視窗"povey"：Povey 視窗
transformers.audio_utils.spectrogram
< 來源 >( waveform: ndarray window: ndarray frame_length: int hop_length: int fft_length: typing.Optional[int] = None power: typing.Optional[float] = 1.0 center: bool = True pad_mode: str = 'reflect' onesided: bool = True dither: float = 0.0 preemphasis: typing.Optional[float] = None mel_filters: typing.Optional[numpy.ndarray] = None mel_floor: float = 1e-10 log_mel: typing.Optional[str] = None reference: float = 1.0 min_value: float = 1e-10 db_range: typing.Optional[float] = None remove_dc_offset: typing.Optional[bool] = None dtype: dtype = <class 'numpy.float32'> )
引數
- waveform (
np.ndarray形態為(length,)) — 輸入波形。這必須是單通道實值單聲道波形。 - window (
np.ndarray形態為(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) — 新增抖動。換句話說，向每個幀新增小的 Gaussian 噪聲。例如，使用 4.0 新增標準差為 4.0，以 0.0 為中心的正常分佈的抖動，0.0 表示不抖動。抖動與mel_floor具有類似的效果。它降低了具有硬零部分訊號的高 log_mel_fbank 值，當訊號中存在 VAD 截止時。 - preemphasis (
float, 可選) — 在 DFT 之前應用預加重低通濾波器的係數。 - mel_filters (
np.ndarray形態為(num_freq_bins, num_mel_filters), 可選) — 梅爾濾波器組。如果提供，將此濾波器組應用於建立梅爾頻譜圖。 - 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。必須大於零。 - min_value (
float, 可選, 預設為1e-10) — 在轉換為分貝之前，頻譜圖將被剪裁到此最小值，以避免取log(0)。對於功率譜圖，預設值1e-10對應於 -100 dB 的最小值。對於幅度譜圖，值1e-5對應於 -100 dB。必須大於零。 - db_range (
float, 可選) — 設定分貝的最大動態範圍。例如，如果db_range = 80，則峰值與最小值之間的差異永遠不會超過 80 dB。必須大於零。 - remove_dc_offset (
bool, 可選) — 從每個幀的波形中減去平均值，在預加重之前應用。為了獲得與torchaudio.compliance.kaldi.fbank計算梅爾濾波器時相同的結果，應將其設定為true。 - dtype (
np.dtype, 可選, 預設為np.float32) — 頻譜圖張量的資料型別。如果power為 None，則此引數將被忽略，資料型別將為np.complex64。
使用短時傅立葉變換計算一個波形的頻譜圖。
此函式可以建立以下型別的頻譜圖
- 幅度頻譜圖 (
power = 1.0) - 功率頻譜圖 (
power = 2.0) - 復值頻譜圖 (
power = None) - 對數頻譜圖 (使用
log_mel引數) - 梅爾頻譜圖 (提供
mel_filters) - 對數梅爾頻譜圖 (提供
mel_filters和log_mel)
工作原理
- 輸入波形被分成大小為
frame_length的幀，這些幀部分重疊frame_lengthhop_length樣本。
- 每個幀乘以視窗並放置到大小為
fft_length的緩衝區中。 - 對每個加窗幀進行 DFT。
- 結果堆疊成頻譜圖。
我們區分以下“塊”樣本資料，每個塊可能具有不同的長度
- 分析幀。這是輸入波形被分割成的時間片的尺寸。
- 窗函式。每個分析幀都乘以窗函式，以避免頻譜洩漏。
- FFT輸入緩衝區。其長度決定了頻譜圖中頻率 bin 的數量。
在此實現中，窗函式被假定為零填充，使其大小與分析幀相同。可以透過 window_function() 獲取填充後的窗函式。FFT 輸入緩衝區可能大於分析幀，通常是下一個2的冪。
注意：此函式尚未針對速度進行最佳化。它應與 librosa.stft 和 torchaudio.functional.transforms.Spectrogram 大致相容，儘管由於頻譜圖的不同構建方式，它更靈活。
transformers.audio_utils.power_to_db
< source >( spectrogram: ndarray reference: float = 1.0 min_value: float = 1e-10 db_range: typing.Optional[float] = None ) → np.ndarray
引數
- spectrogram (
np.ndarray) — 輸入功率（梅爾）頻譜圖。請注意，功率頻譜圖的幅度是平方過的！ - reference (
float, 可選, 預設為 1.0) — 設定對應0 dB的輸入頻譜圖值。例如，使用np.max(spectrogram)將最響亮的部分設定為0 dB。必須大於零。 - min_value (
float, 可選, 預設為1e-10) — 在轉換為分貝之前，頻譜圖將被剪裁到此最小值，以避免取log(0)。預設值1e-10對應於最低 -100 dB。必須大於零。 - db_range (
float, 可選) — 設定最大動態範圍（分貝）。例如，如果db_range = 80，則峰值與最小值之間的差異永遠不會超過80 dB。必須大於零。
返回
np.ndarray
分貝標度下的頻譜圖
將功率頻譜圖轉換為分貝標度。此函式使用基本對數性質進行數值穩定性計算，公式為 10 * log10(spectrogram / reference)。
對（梅爾）頻譜圖應用對數函式的動機是，人類對響度的感知不是線性關係。通常，要使聲音的感知音量加倍，我們需要將其能量增加8倍。這意味著，如果聲音本來就很響，則能量的巨大變化可能聽起來並沒有那麼不同。這種壓縮操作使（梅爾）頻譜圖特徵更接近人類實際聽到的聲音。
基於 librosa.power_to_db 的實現。
transformers.audio_utils.amplitude_to_db
< source >( spectrogram: ndarray reference: float = 1.0 min_value: float = 1e-05 db_range: typing.Optional[float] = None ) → np.ndarray
引數
- spectrogram (
np.ndarray) — 輸入幅度（梅爾）頻譜圖。 - reference (
float, 可選, 預設為 1.0) — 設定對應0 dB的輸入頻譜圖值。例如，使用np.max(spectrogram)將最響亮的部分設定為0 dB。必須大於零。 - min_value (
float, 可選, 預設為1e-5) — 在轉換為分貝之前，頻譜圖將被剪裁到此最小值，以避免取log(0)。預設值1e-5對應於最低 -100 dB。必須大於零。 - db_range (
float, 可選) — 設定最大動態範圍（分貝）。例如，如果db_range = 80，則峰值與最小值之間的差異永遠不會超過80 dB。必須大於零。
返回
np.ndarray
分貝標度下的頻譜圖
將幅度頻譜圖轉換為分貝標度。此函式使用基本對數性質進行數值穩定性計算，公式為 20 * log10(spectrogram / reference)。
對（梅爾）頻譜圖應用對數函式的動機是，人類對響度的感知不是線性關係。通常，要使聲音的感知音量加倍，我們需要將其能量增加8倍。這意味著，如果聲音本來就很響，則能量的巨大變化可能聽起來並沒有那麼不同。這種壓縮操作使（梅爾）頻譜圖特徵更接近人類實際聽到的聲音。