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_length
hop_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倍。这意味着,如果声音本来就很响,则能量的巨大变化可能听起来并没有那么不同。这种压缩操作使(梅尔)频谱图特征更接近人类实际听到的声音。