Transformers.js 文档

utils/audio

Transformers.js

加入 Hugging Face 社区

并获得增强型文档体验

协作模型、数据集和空间

使用加速推理获得更快的示例

在文档主题之间切换

开始

utils/audio

用于音频处理的辅助模块。

这些函数和类仅在内部使用，这意味着最终用户不需要访问这里的内容。

utils/audio
- static
  - .read_audio(url, sampling_rate) ⇒ Promise.<Float32Array>
    - ~audio : Float32Array
  - .hanning(M) ⇒ Float64Array
  - .hamming(M) ⇒ Float64Array
  - .mel_filter_bank(num_frequency_bins, num_mel_filters, min_frequency, max_frequency, sampling_rate, [norm], [mel_scale], [triangularize_in_mel_space]) ⇒ Array.<Array<number>>
  - .spectrogram(waveform, window, frame_length, hop_length, options) ⇒ Promise.<Tensor>
  - .window_function(window_length, name, options) ⇒ Float64Array
- inner
  - ~generalized_cosine_window(M, a_0) ⇒ Float64Array
  - ~hertz_to_mel(freq, [mel_scale]) ⇒ T
  - ~mel_to_hertz(mels, [mel_scale]) ⇒ T
  - ~_create_triangular_filter_bank(fft_freqs, filter_freqs) ⇒ Array.<Array<number>>
  - ~linspace(start, end, num) ⇒
  - ~padReflect(array, left, right) ⇒ T
  - ~_db_conversion_helper(spectrogram, factor, reference, min_value, db_range) ⇒ T
  - ~amplitude_to_db(spectrogram, [reference], [min_value], [db_range]) ⇒ T
  - ~power_to_db(spectrogram, [reference], [min_value], [db_range]) ⇒ T

utils/audio.read_audio(url, sampling_rate) ⇒ <code> Promise. < Float32Array > </code>

辅助函数，用于从路径/URL 读取音频。

Kind: utils/audio 的静态方法
Returns: Promise.<Float32Array> - 解码后的音频，以 Float32Array 形式表示。

参数	类型	描述
url	`string` \| `URL`	用于加载音频的路径/URL。
sampling_rate	`number`	解码音频时使用的采样率。

read_audio~audio : <code> Float32Array </code>

Kind: read_audio 的内部属性

utils/audio.hanning(M) ⇒ <code> Float64Array </code>

生成长度为 M 的汉宁窗。有关详细信息，请参阅 https://numpy.com.cn/doc/stable/reference/generated/numpy.hanning.html。

Kind: utils/audio 的静态方法
Returns: Float64Array - 生成的汉宁窗。

参数	类型	描述
M	`number`	要生成的汉宁窗的长度。

utils/audio.hamming(M) ⇒ <code> Float64Array </code>

生成长度为 M 的汉明窗。有关详细信息，请参阅 https://numpy.com.cn/doc/stable/reference/generated/numpy.hamming.html。

Kind: utils/audio 的静态方法
返回: Float64Array - 生成的汉明窗。

参数	类型	描述
M	`number`	要生成的汉明窗的长度。

utils/audio.mel_filter_bank(num_frequency_bins, num_mel_filters, min_frequency, max_frequency, sampling_rate, [norm], [mel_scale], [triangularize_in_mel_space]) ⇒ <code> Array. < Array < number > > </code>

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

Kind: utils/audio 的静态方法
返回: Array.<Array<number>> - 三角滤波器组矩阵，它是一个形状为 (num_frequency_bins, num_mel_filters) 的二维数组。这是一个从谱图到梅尔谱图的投影矩阵。

参数	类型	描述
num_frequency_bins	`number`	用于计算谱图的频率数量（应与 `stft` 中的频率数量相同）。
num_mel_filters	`number`	要生成的梅尔滤波器数量。
min_frequency	`number`	感兴趣的最低频率，单位为 Hz。
max_frequency	`number`	感兴趣的最高频率，单位为 Hz。这应该不超过 `sampling_rate / 2`。
sampling_rate	`number`	音频波形的采样率。
[norm]	`string`	如果为 `"slaney"`，则将三角梅尔权重除以梅尔频带的宽度（面积归一化）。
[mel_scale]	`string`	要使用的梅尔频率尺度，`"htk"` 或 `"slaney"`。
[triangularize_in_mel_space]	`boolean`	如果启用此选项，则三角滤波器将应用于梅尔空间，而不是频率空间。为了获得与 `torchaudio` 计算梅尔滤波器时相同的結果，这应该设置为 `true`。

utils/audio.spectrogram(waveform, window, frame_length, hop_length, options) ⇒ <code> Promise. < Tensor > </code>

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

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

幅度谱图 (power = 1.0)
功率谱图 (power = 2.0)
复值谱图 (power = None)
对数谱图（使用 log_mel 参数）
梅尔谱图（提供 mel_filters）
对数梅尔谱图（提供 mel_filters 和 log_mel）

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

Kind: utils/audio 的静态方法
返回: Promise.<Tensor> - 形状为 (num_frequency_bins, length)（常规谱图）或形状为 (num_mel_filters, length)（梅尔谱图）的谱图。

参数	类型	默认	描述
waveform	`Float32Array` \| `Float64Array`		形状为 `(length,)` 的输入波形。这必须是单个实值单声道波形。
window	`Float32Array` \| `Float64Array`		要应用的形状为 `(frame_length,)` 的窗函数，包括必要时的零填充。实际的窗口长度可能短于 `frame_length`，但我们假设数组已经过零填充。
frame_length	`number`		分析帧的长度，以样本为单位（又名 `fft_length`）。
hop_length	`number`		连续分析帧之间的步长，以样本为单位。
options	`Object`
[options.fft_length]	`number`		FFT 缓冲区的大小，以样本为单位。这决定了谱图将有多少个频率箱。为了获得最佳速度，这应该是一个 2 的幂。如果为 `null`，则使用 `frame_length`。
[options.power]	`number`	`1.0`	如果为 1.0，则返回幅度谱图。如果为 2.0，则返回功率谱图。如果为 `null`，则返回复数。
[options.center]	`boolean`	`true`	是否填充波形，使帧 `t` 以时间 `t * hop_length` 为中心。如果为 `false`，则帧 `t` 将从时间 `t * hop_length` 开始。
[options.pad_mode]	`string`	`""reflect""`	当 `center` 为 `true` 时使用的填充模式。可能的值为：`"constant"`（用零填充）、`"edge"`（用边缘值填充）、`"reflect"`（用镜像值填充）。
[options.onesided]	`boolean`	`true`	如果为 `true`，则仅计算正频率，并返回包含 `fft_length // 2 + 1` 个频率箱的谱图。如果为 `false`，则还会计算负频率，并返回 `fft_length` 个频率箱。
[options.preemphasis]	`number`		用于在 DFT 之前应用预加重的低通滤波器的系数。
[options.mel_filters]	`Array.<Array<number>>`		形状为 `(num_freq_bins, num_mel_filters)` 的梅尔滤波器组。如果提供，则应用此滤波器组以创建梅尔谱图。
[options.mel_floor]	`number`	`1e-10`	梅尔频率组的最小值。
[options.log_mel]	`string`	`null`	如何将谱图转换为对数尺度。可能的选项为：`null`（不转换）、`"log"`（取自然对数）`"log10"`（取以 10 为底的对数）、`"dB"`（转换为分贝）。仅当 `power` 不为 `null` 时可以使用。
[options.reference]	`number`	`1.0`	设置对应于 0 dB 的输入谱图值。例如，使用 `max(spectrogram)[0]` 将最响亮的部分设置为 0 dB。必须大于零。
[options.min_value]	`number`	`1e-10`	在转换为分贝之前，谱图将被剪裁到此最小值，以避免取 `log(0)`。对于功率谱图，默认值为 `1e-10` 对应于 -100 dB 的最小值。对于幅度谱图，值 `1e-5` 对应于 -100 dB。必须大于零。
[options.db_range]	`number`		设置分贝中的最大动态范围。例如，如果 `db_range = 80`，则峰值与最小值之间的差值将永远不会超过 80 dB。必须大于零。
[options.remove_dc_offset]	`boolean`		从每个帧的波形中减去平均值，在预加重之前应用。为了获得与 `torchaudio.compliance.kaldi.fbank` 计算梅尔滤波器时相同的結果，这应该设置为 `true`。
[options.max_num_frames]	`number`		如果提供，则将要计算的帧数限制为此值。
[options.min_num_frames]	`number`		如果提供，则确保要计算的帧数至少为此值。
[options.do_pad]	`boolean`	`true`	如果为 `true`，则填充输出谱图以具有 `max_num_frames` 帧。
[options.transpose]	`boolean`	`false`	如果为 `true`，则返回的谱图将具有形状 `(num_frames, num_frequency_bins/num_mel_filters)`。如果为 `false`，则返回的谱图将具有形状 `(num_frequency_bins/num_mel_filters, num_frames)`。

utils/audio.window_function(window_length, name, options) ⇒ <code> Float64Array </code>

返回一个包含指定窗口的数组。

Kind: utils/audio 的静态方法
返回: Float64Array - 形状为 (window_length,) 或 (frame_length,) 的窗口。

参数	类型	默认	描述
window_length	`number`		窗口的长度，以样本为单位。
name	`string`		窗口函数的名称。
options	`Object`		其他选项。
[options.periodic]	`boolean`	`true`	窗口是周期性的还是对称的。
[options.frame_length]	`number`		分析帧的长度，以样本为单位。如果窗口小于帧长度，请提供 `frame_length` 的值，以便进行零填充。
[options.center]	`boolean`	`true`	是否将窗口居中于 FFT 缓冲区内。仅在提供 `frame_length` 时使用。

utils/audio~generalized_cosine_window(M, a_0) ⇒ <code> Float64Array </code>

生成广义余弦窗的辅助函数。有关更多信息，请参阅 https://www.mathworks.com/help/signal/ug/generalized-cosine-windows.html。

类型: utils/audio 的内部方法
返回值: Float64Array - 生成的窗口。

参数	类型	描述
M	`number`	输出窗口中的点数。如果为零或更小，则返回一个空数组。
a_0	`number`	广义余弦窗的偏移量。

utils/audio~hertz_to_mel(freq, [mel_scale]) ⇒ <code> T </code>

类型: utils/audio 的内部方法

参数	类型	默认
freq	`T`
[mel_scale]	`string`	`"htk"`

utils/audio~mel_to_hertz(mels, [mel_scale]) ⇒ <code> T </code>

类型: utils/audio 的内部方法

参数	类型	默认
mels	`T`
[mel_scale]	`string`	`"htk"`

utils/audio~_create_triangular_filter_bank(fft_freqs, filter_freqs) ⇒ <code> Array. < Array < number > > </code>

创建三角滤波器组。

改编自 torchaudio 和 librosa。

类型: utils/audio 的内部方法
返回值: Array.<Array<number>> - 形状为 (num_frequency_bins, num_mel_filters)。

参数	类型	描述
fft_freqs	`Float64Array`	FFT 频段的离散频率（以 Hz 为单位），形状为 `(num_frequency_bins,)`。
filter_freqs	`Float64Array`	要创建的三角滤波器的中心频率（以 Hz 为单位），形状为 `(num_mel_filters,)`。

utils/audio~linspace(start, end, num) ⇒

在指定区间上返回均匀间隔的数字。

类型: utils/audio 的内部方法
返回值: num 个均匀间隔的样本，在区间 [start, stop] 上计算得出。

参数	类型	描述
start	`number`	序列的起始值。
end	`number`	序列的结束值。
num	`number`	要生成的样本数量。

utils/audio~padReflect(array, left, right) ⇒ <code> T </code>

类型: utils/audio 的内部方法
返回值: T - 填充后的数组。

参数	类型	描述
array	`T`	要填充的数组。
left	`number`	要添加到左侧的填充量。
right	`number`	要添加到右侧的填充量。

utils/audio~_db_conversion_helper(spectrogram, factor, reference, min_value, db_range) ⇒ <code> T </code>

计算 amplitude_to_db 和 power_to_db 的辅助函数。

类型: utils/audio 的内部方法

参数	类型
spectrogram	`T`
factor	`number`
reference	`number`
min_value	`number`
db_range	`number`

utils/audio~amplitude_to_db(spectrogram, [reference], [min_value], [db_range]) ⇒ <code> T </code>

将幅度谱图转换为分贝刻度。这计算 20 * log10(spectrogram / reference)，使用基本对数属性来提高数值稳定性。注意：就地操作。

对（梅尔）谱图应用对数函数的动机是，人类的听觉并非线性地感知响度。通常，要使声音的感知音量加倍，我们需要将能量增加 8 倍。这意味着，如果声音本来就很响，能量的巨大变化可能听起来并没有那么大。这种压缩操作使（梅尔）谱图特征更接近人类实际听到的内容。

类型: utils/audio 的内部方法
返回值: T - 以分贝为单位的修改后的谱图。

参数	类型	默认	描述
spectrogram	`T`		输入幅度（梅尔）谱图。
[reference]	`number`	`1.0`	设置对应于 0 dB 的输入谱图值。例如，使用 `np.max(spectrogram)` 将最响的部分设置为 0 dB。必须大于零。
[min_value]	`number`	`1e-5`	在转换为分贝之前，谱图将被剪裁到此最小值，以避免取 `log(0)`。默认值为 `1e-5`，对应于最小值 -100 dB。必须大于零。
[db_range]	`number`		设置分贝中的最大动态范围。例如，如果 `db_range = 80`，则峰值与最小值之间的差值将永远不会超过 80 dB。必须大于零。

utils/audio~power_to_db(spectrogram, [reference], [min_value], [db_range]) ⇒ <code> T </code>

将功率谱图转换为分贝刻度。这计算 10 * log10(spectrogram / reference)，使用基本对数属性来提高数值稳定性。注意：就地操作。

基于 librosa.power_to_db 的实现。

类型: utils/audio 的内部方法
返回值: T - 以分贝为单位的修改后的谱图。

参数	类型	默认	描述
spectrogram	`T`		输入功率（梅尔）谱图。注意，功率谱图的幅度已平方！
[reference]	`number`	`1.0`	设置对应于 0 dB 的输入谱图值。例如，使用 `np.max(spectrogram)` 将最响的部分设置为 0 dB。必须大于零。
[min_value]	`number`	`1e-10`	在转换为分贝之前，频谱图将被裁剪到此最小值，以避免取`log(0)`。 `1e-10`的默认值对应于 -100 dB 的最小值。必须大于零。
[db_range]	`number`		设置分贝中的最大动态范围。例如，如果 `db_range = 80`，则峰值与最小值之间的差值将永远不会超过 80 dB。必须大于零。

< > 在 GitHub 上更新

←图像张量→