Transformers documentation

FeatureExtractors 实用工具

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

FeatureExtractors 实用工具

此页面列出了音频 FeatureExtractor 可使用的全部实用函数,用于通过 短时傅里叶变换 或 对数梅尔频谱图 等常见算法,从原始音频中计算特定特征。

这些内容通常仅在你研究库中音频处理器的代码时才有用。

音频转换

transformers.audio_utils.hertz_to_mel

< >

( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray

参数

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

返回值

float 或 np.ndarray

梅尔刻度上的频率。

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

transformers.audio_utils.mel_to_hertz

< >

( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray

参数

  • mels (float 或 np.ndarray) — 以梅尔(mel)为单位的频率,或多个频率。
  • mel_scale (str,可选,"htk") — 要使用的梅尔频率刻度,"htk"、"kaldi" 或 "slaney"。

返回值

float 或 np.ndarray

以赫兹为单位的频率。

将频率从梅尔(mels)转换为赫兹(hertz)。

transformers.audio_utils.mel_filter_bank

< >

( 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 // 2 + 1 相同,其中 n_fft 是用于计算频谱图的傅里叶变换的大小)。
  • 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") — 要使用的 mel 频率刻度,"htk"、"kaldi" 或 "slaney"。
  • triangularize_in_mel_space (bool,可选,默认为 False) — 如果启用此选项,三角滤波器将在 mel 空间而非频率空间中应用。为了在计算 mel 滤波器时获得与 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

三角形滤波器组矩阵。这是一个投影矩阵,用于将频谱图转换为梅尔频谱图。

创建一个用于获取梅尔频谱的频率分箱转换矩阵。这被称为梅尔滤波器组,存在多种实现方式,它们在滤波器数量、滤波器形状、滤波器间距、滤波器带宽以及频谱扭曲方式上有所不同。这些特性的目标是近似人类对音高随频率变化这一现象的非线性感知。

文献中引入了不同组的梅尔滤波器。支持以下变体:

  • MFCC FB-20:由 Davis 和 Mermelstein 于 1980 年提出,假设采样频率为 10 kHz,语音带宽为 [0, 4600] Hz。
  • MFCC FB-24 HTK:源自剑桥 HMM 工具包(HTK)(1995),针对 [0, 8000] Hz 的语音带宽使用 24 个滤波器的滤波器组。此配置假设采样率 ≥ 16 kHz。
  • MFCC FB-40:源自 Slaney 于 1998 年编写的 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" 实现。

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

为给定的 window_length 查找最佳的 FFT 输入大小。该函数接收给定的窗口长度,如果其不是 2 的幂,则将其向上取整到下一个 2 的幂。

当输入长度为 2 的幂时,FFT 算法的运行速度最快,该长度可能大于窗口或分析帧的大小。例如,如果窗口为 400 个采样点,使用 512 个采样点的 FFT 输入大小比使用 400 个采样点的 FFT 大小更优。使用更大的 FFT 大小不会影响检测到的频率,它只是提供了更高的频率分辨率(即频率 bin 更小)。

transformers.audio_utils.window_function

< >

( 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

< >

( 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,形状为 (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 个频率 bin 的频谱图。如果为 False,则同时计算负频率,并返回 fft_length 个频率 bin。
  • dither (float, 可选,默认为 0.0) — 添加抖动。换句话说,为每一帧添加少量高斯噪声。 例如,使用 4.0 可添加以 0.0 为中心、标准差为 4.0 的正态分布抖动,0.0 表示不添加抖动。 抖动的效果与 mel_floor 类似。当信号中存在 VAD 截断时,它会降低具有硬零段的信号的高 log_mel_fbank 值。
  • preemphasis (float, 可选) — 在 DFT 之前应用预加重时,低通滤波器的系数。
  • mel_filters(形状为 (num_freq_bins, num_mel_filters) 的 np.ndarray,可选)— 梅尔滤波器组。如果提供,则应用此滤波器组以生成梅尔频谱图。
  • 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, 可选) — 在每帧波形上减去均值,该操作在预加重之前执行。为了在计算 mel 滤波器时获得与 torchaudio.compliance.kaldi.fbank 相同的结果,应将其设置为 true。
  • dtype (np.dtype,可选,默认为 np.float32) — 频谱张量的数据类型。如果 power 为 None,则忽略此参数,dtype 将为 np.complex64。

使用短时傅里叶变换计算单个波形的频谱图。

此函数可以创建以下类型的频谱图:

  • 幅度频谱图 (power = 1.0)
  • 功率频谱图(power = 2.0)
  • 复数频谱图(power = None)
  • 对数频谱图(使用 log_mel 参数)
  • 梅尔频谱图(提供 mel_filters)
  • log-mel 频谱图(提供 mel_filters 和 log_mel)

其工作原理:

  1. 输入波形被分割为大小为 frame_length 的帧,这些帧之间部分重叠,重叠量为 `frame_length
    • 个样本。
  2. 每一帧都会乘以窗口函数,然后放入大小为 fft_length 的缓冲区中。
  3. 对每个加窗帧执行 DFT。
  4. 结果被堆叠成一张频谱图。

我们将样本数据划分为以下不同的“块”,每个块的长度可能不同:

  • 分析帧。这是将输入波形切分成的时间片的大小。
  • 窗口。每个分析帧都会乘以窗口,以避免频谱泄漏。
  • FFT 输入缓冲区。其长度决定了频谱图中包含多少个频率分箱。

在此实现中,假设窗口经过零填充,使其大小与分析帧相同。可通过 window_function() 获取填充后的窗口。FFT 输入缓冲区可能大于分析帧,通常取下一个 2 的幂次。

注意:此函数尚未针对速度进行优化。它应与 librosa.stft 和 torchaudio.functional.transforms.Spectrogram 基本兼容,但由于构建频谱图的方式不同,它的灵活性更高。

transformers.audio_utils.power_to_db

< >

( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-10db_range: float | None = None ) → np.ndarray

参数

  • spectrogram (np.ndarray) — 输入的功率(mel)频谱图。请注意,功率频谱图的幅度是平方后的值!
  • 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

< >

( 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。该值必须大于零。
  • 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