Transformers 文档

特征提取器的实用工具

FeatureExtractors 的工具

本页面列出了所有可由音频FeatureExtractor使用的实用函数,以便使用常见算法(如短时傅里叶变换对数梅尔频谱图)从原始音频中计算特殊特征。

大多数这些内容只有在您研究库中的音频处理器代码时才有用。

音频转换

transformers.audio_utils.hertz_to_mel

< >

( freq: typing.Union[float, numpy.ndarray] mel_scale: str = 'htk' ) floatnp.ndarray

参数

  • freq (float or np.ndarray) — 频率,或多个频率,单位为赫兹(Hz)。
  • mel_scale (str, 可选, 默认为 "htk") — 使用的梅尔频率刻度,"htk", "kaldi""slaney".

返回

floatnp.ndarray

梅尔尺度上的频率。

将频率从赫兹转换为梅尔。

transformers.audio_utils.mel_to_hertz

< >

( mels: typing.Union[float, numpy.ndarray] mel_scale: str = 'htk' ) floatnp.ndarray

参数

  • mels (floatnp.ndarray) — 频率,或多个频率,以mels为单位。
  • mel_scale (str, optional, "htk") — 使用的梅尔频率刻度,"htk""kaldi""slaney".

返回

floatnp.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) — 用于计算频谱图的频率数量(应与stft中的相同)。
  • num_mel_filters (int) — 生成的梅尔滤波器数量。
  • min_frequency (float) — 感兴趣的最低频率,单位为Hz。
  • max_frequency (float) — 感兴趣的最高频率,单位为Hz。此值不应超过sampling_rate / 2.
  • sampling_rate (int) — 音频波形的采样率。
  • norm (str, 可选) — 如果为 "slaney",则将三角梅尔权重除以梅尔频带的宽度(区域归一化)。
  • mel_scale (str, 可选, 默认为 "htk") — 使用的梅尔频率刻度,"htk", "kaldi""slaney".
  • triangularize_in_mel_space (bool, 可选, 默认为 False) — 如果启用此选项,三角滤波器将在mel空间而不是频率空间中应用。为了在计算mel滤波器时获得与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编写的Auditory Toolbox,假设采样率为16 kHz,语音带宽为[133, 6854] Hz。此版本还包括面积归一化。
  • HFCC-E FB-29(人类因素倒谱系数)由Skowronski和Harris(2004年)提出,假设采样率为12.5 kHz,语音带宽为[0, 6250] Hz。

此代码改编自torchaudiolibrosa。请注意,torchaudio的melscale_fbanks默认参数实现了"htk"滤波器,而librosa使用的是"slaney"实现。

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

找到给定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 )

参数

  • window_length (int) — 窗口的长度,以样本为单位。
  • name (str, optional, defaults to "hann") — 窗口函数的名称。
  • periodic (bool, optional, defaults to True) — 窗口是周期性的还是对称的。
  • frame_length (int, optional) — 分析帧的长度,以样本为单位。如果窗口小于帧长度,请为frame_length提供一个值,以便进行零填充。
  • center (bool, 可选, 默认为 True) — 是否在FFT缓冲区中居中窗口。仅在提供frame_length时使用。

返回包含指定窗口的数组。此窗口旨在与stft一起使用。

支持以下窗口类型:

  • "boxcar": 一个矩形窗口
  • "hamming": 汉明窗口
  • "hann": 汉恩窗口
  • "povey": Povey窗口

transformers.audio_utils.spectrogram

< >

( 波形: ndarray 窗口: ndarray 帧长度: int 跳跃长度: int FFT长度: typing.Optional[int] = None 功率: typing.Optional[float] = 1.0 中心: bool = True 填充模式: str = 'reflect' 单边: bool = True 预加重: typing.Optional[float] = None 梅尔滤波器: typing.Optional[numpy.ndarray] = None 梅尔下限: float = 1e-10 对数梅尔: typing.Optional[str] = None 参考: float = 1.0 最小值: float = 1e-10 分贝范围: typing.Optional[float] = None 移除直流偏移: typing.Optional[bool] = None 数据类型: dtype = )

参数

  • 波形 (np.ndarray 形状为 (length,)) — 输入的波形。这必须是一个单通道的实值波形。
  • window (np.ndarray of shape (frame_length,)) — 要应用的窗口函数,包括必要的零填充。实际窗口长度可能比frame_length短,但我们假设数组已经被零填充了。
  • frame_length (int) — 分析帧的长度,以样本为单位。在librosa中,这总是等于fft_length,但我们也允许更小的尺寸。
  • hop_length (int) — 连续分析帧之间的步长,以样本为单位。
  • fft_length (int, optional) — 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") — 当 centerTrue 时使用的填充模式。可能的值为:"constant"(用零填充),"edge" (用边缘值填充),"reflect"(用镜像值填充)。
  • onesided (bool, 可选, 默认为 True) — 如果为True,仅计算正频率并返回包含 fft_length // 2 + 1 频率区间的频谱图。如果为False,还计算负频率并返回 fft_length 频率区间。
  • preemphasis (float, optional) — 在DFT之前应用预加重处理的低通滤波器的系数。
  • mel_filters (np.ndarray of shape (num_freq_bins, num_mel_filters), optional) — 梅尔滤波器组。如果提供,将应用此滤波器组以创建梅尔频谱图。
  • mel_floor (float, 可选, 默认值为 1e-10) — mel频率库的最小值。
  • log_mel (str, 可选) — 如何将频谱图转换为对数刻度。可能的选项有:None(不转换),"log"(取自然对数),"log10"(取以10为底的对数),"dB"(转换为分贝)。只能在power不为None时使用。
  • 参考 (float, 可选, 默认值为 1.0) — 设置对应于 0 dB 的输入频谱图值。例如,使用 np.max(spectrogram) 将最响亮的部分设置为 0 dB。必须大于零。
  • min_value (float, optional, defaults to 1e-10) — 在转换为分贝之前,频谱图将被裁剪到此最小值,以避免取 log(0)。对于功率频谱图,默认值1e-10对应于-100 dB的最小值。对于 幅度频谱图,值1e-5对应于-100 dB。必须大于零。
  • db_range (float, 可选) — 设置以分贝为单位的最大动态范围。例如,如果 db_range = 80,峰值与最小值之间的差异永远不会超过80 dB。必须大于零。
  • remove_dc_offset (bool, optional) — 从每个帧的波形中减去均值,应用于预加重之前。为了在计算梅尔滤波器时获得与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)
  • log-mel 频谱图 (提供 mel_filterslog_mel)

这是如何工作的:

  1. 输入波形被分割成大小为frame_length的帧,这些帧部分重叠,重叠长度为`frame_length
    • hop_length`个样本。
  2. 每一帧都乘以窗口并放入大小为fft_length的缓冲区中。
  3. 对每个加窗帧进行DFT。
  4. 结果被堆叠成频谱图。

我们对以下“块”的样本数据进行了区分,每个块的长度可能不同:

  • 分析框架。这是输入波形被分割成的时间片的大小。
  • 窗口。每个分析帧都乘以窗口以避免频谱泄漏。
  • FFT输入缓冲区。其长度决定了频谱图中有多少个频率区间。

在此实现中,假设窗口被零填充以具有与分析帧相同的大小。可以通过window_function()获得填充窗口。FFT输入缓冲区可能大于分析帧,通常是下一个二的幂。

注意:此函数尚未针对速度进行优化。它应该与librosa.stfttorchaudio.functional.transforms.Spectrogram大部分兼容,尽管由于频谱图可以通过不同方式构建,它更加灵活。

transformers.audio_utils.power_to_db

< >

( spectrogram: ndarray reference: float = 1.0 min_value: float = 1e-10 db_range: typing.Optional[float] = None ) np.ndarray

参数

  • spectrogram (np.ndarray) — 输入功率(mel)频谱图。请注意,功率频谱图的振幅是平方的!
  • 参考 (float, 可选, 默认为 1.0) — 设置对应于 0 dB 的输入频谱图值。例如,使用 np.max(spectrogram) 将最响亮的部分设置为 0 dB。必须大于零。
  • min_value (float, optional, defaults to 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

< >

( spectrogram: ndarray reference: float = 1.0 min_value: float = 1e-05 db_range: typing.Optional[float] = None ) np.ndarray

参数

  • spectrogram (np.ndarray) — 输入的幅度(mel)频谱图。
  • 参考 (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倍的能量。这意味着,如果声音一开始就很响,能量的巨大变化可能听起来并没有那么不同。这种压缩操作使得(梅尔)频谱图特征更接近人类实际听到的声音。

< > Update on GitHub