# Утилиты для `FeatureExtractors`

На этой странице перечислены все вспомогательные функции, которые могут использоваться аудио `FeatureExtractor` для вычисления специальных признаков из исходного аудио с помощью распространённых алгоритмов, таких как *Short Time Fourier Transform* или *log mel spectrogram*.

Большинство из них полезны только в том случае, если вы изучаете код аудиопроцессоров в библиотеке.

## Преобразования аудио[[transformers.audio_utils.hertz_to_mel]]

#### transformers.audio_utils.hertz_to_mel[[transformers.audio_utils.hertz_to_mel]]

```python
transformers.audio_utils.hertz_to_mel(freq: float | numpy.ndarray, mel_scale: str = 'htk')
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L580)

**Параметры:**

freq (`float` или `np.ndarray`) : Частота или несколько частот в герцах (Гц).

mel_scale (`str`, *необязательный*, по умолчанию `"htk"`) : используемая шкала мел-частот, `"htk"`, `"kaldi"` или `"slaney"`.

**Возвращает:** `float` или `np.ndarray`

Частоты в шкале мел.

Преобразовать частоту из герц в мелы.

#### transformers.audio_utils.mel_to_hertz[[transformers.audio_utils.mel_to_hertz]]

```python
transformers.audio_utils.mel_to_hertz(mels: float | numpy.ndarray, mel_scale: str = 'htk')
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L616)

**Параметры:**

mels (`float` или `np.ndarray`) : Частота или несколько частот в мелах.

mel_scale (`str`, *необязательный*, `"htk"`) : используемая шкала мел-частот, `"htk"`, `"kaldi"` или `"slaney"`.

**Возвращает:** `float` или `np.ndarray`

Частоты в герцах.

Преобразование частоты из мелов в герцы.

#### transformers.audio_utils.mel_filter_bank[[transformers.audio_utils.mel_filter_bank]]

```python
transformers.audio_utils.mel_filter_bank(num_frequency_bins: int, num_mel_filters: int, min_frequency: float, max_frequency: float, sampling_rate: int, norm: str | None = None, mel_scale: str = 'htk', triangularize_in_mel_space: bool = False, dtype: str | numpy.dtype = <class 'numpy.float64'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L770)

**Параметры:**

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`.

dtype (`str` или `np.dtype`, *необязательный*, по умолчанию `np.float64`) : Тип данных возвращаемых фильтров. Треугольные фильтры вычисляются в float64 и приводятся к `dtype` перед нормализацией `"slaney"`. При `norm="slaney"`, `mel_scale="slaney"` и `dtype=np.float32` результат точно совпадает по битам с `librosa.filters.mel(..., norm="slaney")` (транспонированным).

**Возвращает:** `np.ndarray` формы (`num_frequency_bins`, `num_mel_filters`)

Матрица треугольного фильтрационного банка. Это матрица проекции для перехода от спектрограммы к мел-спектрограмме.

Создаёт матрицу преобразования частотных бинов, используемую для получения мел-спектрограммы. Это называется *мел-фильтровой банкой*, и существует множество реализаций, которые различаются количеством фильтров, формой фильтров, способом их размещения, полосой пропускания фильтров и методом искажения спектра. Целью этих характеристик является приближённое воспроизведение нелинейного восприятия человеком изменения высоты тона в зависимости от частоты.

В литературе были предложены различные банки фильтров мел-шкалы. Поддерживаются следующие варианты:

- MFCC FB-20: предложен в 1980 году Дэвисом и Мермелштейном, предполагает частоту дискретизации 10 кГц и полосу частот речи `[0, 4600]` Гц.
- MFCC FB-24 HTK: из набора инструментов Cambridge HMM Toolkit (HTK) (1995) использует фильтр-банк из 24 фильтров для полосы частот речи `[0, 8000]` Гц. Это предполагает частоту дискретизации ≥ 16 кГц.
- MFCC FB-40: из Auditory Toolbox для MATLAB, написанного Slaney в 1998 году, предполагает частоту дискретизации 16 кГц и полосу частот речи `[133, 6854]` Гц. Эта версия также включает нормализацию по площади.
- HFCC-E FB-29 (Human Factor Cepstral Coefficients) по Сковронски и Харрису (2004) предполагает частоту дискретизации 12,5 кГц и полосу частот речи `[0, 6250]` Гц.

Этот код адаптирован из *torchaudio* и *librosa*. Обратите внимание, что параметры по умолчанию функции `melscale_fbanks` в torchaudio реализуют фильтры `"htk"`, тогда как librosa использует реализацию `"slaney"`.

#### transformers.audio_utils.optimal_fft_length[[transformers.audio_utils.optimal_fft_length]]

```python
transformers.audio_utils.optimal_fft_length(window_length: int)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L869)

Находит оптимальный размер входных данных для БФФ для заданного `window_length`. Эта функция принимает заданную длину окна и, если она не является степенью двойки, округляет её до следующей ближайшей степени двойки.

Алгоритм БПФ работает быстрее всего, когда длина входных данных является степенью двойки, что может быть больше размера окна или аналитического кадра. Например, если окно составляет 400 выборок, то использование размера входных данных БПФ 512 выборок является более оптимальным, чем размер БПФ 400 выборок. Использование большего размера БПФ не влияет на обнаруживаемые частоты, а просто обеспечивает более высокое частотное разрешение (то есть частотные интервалы становятся меньше).

#### transformers.audio_utils.window_function[[transformers.audio_utils.window_function]]

```python
transformers.audio_utils.window_function(window_length: int, name: str = 'hann', periodic: bool = True, frame_length: int | None = None, center: bool = True)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L882)

**Параметры:**

window_length (`int`) : Длина окна в сэмплах.

name (`str`, *необязательный*, по умолчанию `"hann"`) : Название оконной функции.

periodic (`bool`, *необязательный*, по умолчанию `True`) : Указывает, является ли окно периодическим или симметричным.

frame_length (`int`, *optional*) : Длина аналитических кадров в отсчетах. Укажите значение для `frame_length`, если окно меньше длины кадра, чтобы оно было дополнено нулями.

center (`bool`, *необязательный*, по умолчанию `True`) : Определяет, нужно ли центрировать окно внутри буфера БПФ. Используется только при заданном `frame_length`.

**Возвращаемое значение:**

`np.ndarray` формы `(window_length,)` или `(frame_length,)`, содержащий окно.

Возвращает массив, содержащий указанное окно. Это окно предназначено для использования с `stft`.

Поддерживаются следующие типы окон:

- `"boxcar"`: прямоугольное окно
- `"hamming"`: окно Хэмминга
- `"hann"`: окно Ханна
- `"povey"`: окно Povey

#### transformers.audio_utils.spectrogram[[transformers.audio_utils.spectrogram]]

```python
transformers.audio_utils.spectrogram(waveform: ndarray, window: ndarray, frame_length: int, hop_length: int, fft_length: int | None = None, power: float | None = 1.0, center: bool = True, pad_mode: str = 'reflect', onesided: bool = True, dither: float = 0.0, preemphasis: float | None = None, mel_filters: numpy.ndarray | None = None, mel_floor: float = 1e-10, log_mel: str | None = None, reference: float = 1.0, min_value: float = 1e-10, db_range: float | None = None, remove_dc_offset: bool = False, dtype: dtype = <class 'numpy.float32'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L946)

**Параметры:**

waveform (`np.ndarray` формы `(length,)`) : Входная звуковая волна. Это должна быть одиночная монофоническая волна с действительными значениями.

window (`np.ndarray` формы `(frame_length,)`) : Функция оконирования, которую необходимо применить, включая дополнение нулями при необходимости. Фактическая длина окна может быть меньше `frame_length`, но предполагается, что массив уже дополнен нулями.

frame_length (`int`) : Длина аналитических кадров в отсчётах. В librosa она всегда равна `fft_length`, но мы также допускаем меньшие размеры.

hop_length (`int`) : Шаг между последовательными кадрами анализа в отсчётах.

fft_length (`int`, *необязательный*) : Размер буфера БПФ в отсчётах. Определяет количество частотных бинов, которые будет иметь спектрограмма. Для оптимальной скорости это значение должно быть степенью двойки. Если `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`, *optional*, по умолчанию 0.0) : Добавляет дитеринг. Иными словами, добавляет небольшой гауссов шум к каждому кадру. Например, значение 4.0 добавляет дитеринг с нормальным распределением, центрированным вокруг 0.0 и со стандартным отклонением 4.0; значение 0.0 означает отсутствие дитеринга. Дитеринг оказывает аналогичный эффект, что и `mel_floor`. Он снижает высокие значения log_mel_fbank для сигналов с участками, где сигнал равен нулю, если в сигнале присутствует VAD cutoff.

preemphasis (`float`, *необязательный*) : Коэффициент для фильтра нижних частот, применяющего предварительное усиление перед ДПФ.

mel_filters (`np.ndarray` формы `(num_freq_bins, num_mel_filters)`, *необязательный*) : Банк мел-фильтров. Если указан, применяет этот банк фильтров для создания мел-спектрограммы.

mel_floor (`float`, *необязательный*, по умолчанию 1e-10) : Минимальное значение банков частот мел-шкалы.

log_mel (`str`, *необязательный*) : Способ преобразования спектрограммы в логарифмическую шкалу. Возможные значения: `None` (не преобразовывать), `"log"` (взять натуральный логарифм), `"log10"` (взять десятичный логарифм), `"dB"` (преобразовать в децибелы). Можно использовать только тогда, когда `power` не равно `None`.

reference (`float`, *optional*, по умолчанию 1.0) : Устанавливает значение входной спектрограммы, соответствующее 0 дБ. Например, используйте `np.max(spectrogram)`, чтобы установить самую громкую часть на 0 дБ. Должно быть больше нуля.

min_value (`float`, *необязательный*, по умолчанию `1e-10`) : Спектрограмма будет обрезана до этого минимального значения перед преобразованием в децибелы, чтобы избежать вычисления `log(0)`. Для спектрограммы мощности значение по умолчанию `1e-10` соответствует минимуму -100 дБ. Для спектрограммы амплитуды значение `1e-5` соответствует -100 дБ. Должно быть больше нуля.

db_range (`float`, *optional*) : Задаёт максимальный динамический диапазон в децибелах. Например, если `db_range = 80`, разница между пиковым значением и минимальным значением никогда не превысит 80 дБ. Должно быть больше нуля.

remove_dc_offset (`bool`, *необязательный*) : Вычитание среднего значения из аудиосигнала в каждом кадре, выполняется до предподчёркивания. Для получения тех же результатов, что и `torchaudio.compliance.kaldi.fbank` при вычислении мел-фильтров, это значение должно быть установлено в `true`.

dtype (`np.dtype`, *необязательный*, по умолчанию `np.float32`) : Тип данных тензора спектрограммы. Если `power` равно None, этот аргумент игнорируется, а dtype будет `np.complex64`.

**Возвращаемое значение:**

`nd.array`, содержащий спектрограмму формы `(num_frequency_bins, length)` для обычной спектрограммы или формы `(num_mel_filters, length)` для мел-спектрограммы.

Вычисляет спектрограмму для одной звуковой волны с использованием коротковременного преобразования Фурье.

Эта функция может создавать следующие виды спектрограмм:

- спектрограмма амплитуды (`power = 1.0`)
- спектрограмма мощности (`power = 2.0`)
- спектрограмма со значениями в комплексной области (`power = None`)
- спектрограмма в логарифмической шкале (используйте аргумент `log_mel`)
- мел-спектрограмма (предоставьте `mel_filters`)
- лог-мел-спектрограмма (укажите `mel_filters` и `log_mel`)

Как это работает:

1. Входной сигнал разбивается на кадры размера `frame_length`, которые частично перекрываются на `frame_length
   - выборок hop_length.
2. Каждый кадр умножается на окно и помещается в буфер размера `fft_length`.
3. ДПФ вычисляется для каждого оконного кадра.
4. Результаты складываются в спектрограмму.

Мы проводим различие между следующими «блоками» выборочных данных, каждый из которых может иметь разную длину:

- Кадр анализа. Это размер временных срезов, на которые разбивается входная волна.
- Окно. Каждый кадр анализа умножается на окно, чтобы избежать спектральных утечек.
- Входной буфер FFT. Длина этого буфера определяет количество частотных бинов в спектрограмме.

В данной реализации предполагается, что окно дополнено нулями до размера, совпадающего с размером кадра анализа. Дополненное окно можно получить с помощью `window_function()`. Буфер входных данных для БПФ может быть больше кадра анализа, как правило, до ближайшей степени двойки.

Примечание: Эта функция пока не оптимизирована по скорости. Она должна быть в основном совместима с `librosa.stft` и `torchaudio.functional.transforms.Spectrogram`, хотя она более гибкая благодаря различным способам построения спектрограмм.

#### transformers.audio_utils.power_to_db[[transformers.audio_utils.power_to_db]]

```python
transformers.audio_utils.power_to_db(spectrogram: ndarray, reference: float = 1.0, min_value: float = 1e-10, db_range: float | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L1368)

**Параметры:**

spectrogram (`np.ndarray`) : Входная спектрограмма мощности (мел). Обратите внимание, что в спектрограмме мощности амплитуды возведены в квадрат!

reference (`float`, *optional*, по умолчанию 1.0) : Устанавливает значение входной спектрограммы, соответствующее 0 дБ. Например, используйте `np.max(spectrogram)`, чтобы установить самую громкую часть на 0 дБ. Должно быть больше нуля.

min_value (`float`, *optional*, по умолчанию `1e-10`) : Спектрограмма будет обрезана до этого минимального значения перед преобразованием в децибелы, чтобы избежать вычисления `log(0)`. Значение по умолчанию `1e-10` соответствует минимуму -100 дБ. Должно быть больше нуля.

db_range (`float`, *optional*) : Задаёт максимальный динамический диапазон в децибелах. Например, если `db_range = 80`, разница между пиковым значением и минимальным значением никогда не превысит 80 дБ. Должно быть больше нуля.

**Возвращает:** `np.ndarray`

спектрограмма в децибелах

Преобразует спектрограмму мощности в децибельную шкалу. Вычисляет `10 * log10(spectrogram / reference)`, используя базовые свойства логарифма для численной устойчивости.

Мотивация применения логарифмической функции к (мел-)спектрограмме заключается в том, что человек воспринимает громкость не по линейной шкале. Как правило, чтобы удвоить воспринимаемую громкость звука, необходимо увеличить его энергию в 8 раз. Это означает, что значительные вариации энергии могут не звучать столь заметно, если звук изначально громкий. Эта операция сжатия позволяет признакам (мел-)спектрограммы точнее соответствовать тому, что человек действительно слышит.

Основано на реализации `librosa.power_to_db`.

#### transformers.audio_utils.amplitude_to_db[[transformers.audio_utils.amplitude_to_db]]

```python
transformers.audio_utils.amplitude_to_db(spectrogram: ndarray, reference: float = 1.0, min_value: float = 1e-05, db_range: float | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L1468)

**Параметры:**

spectrogram (`np.ndarray`) : Входная амплитудная (мел-) спектрограмма.

reference (`float`, *optional*, по умолчанию 1.0) : Устанавливает значение входной спектрограммы, соответствующее 0 дБ. Например, используйте `np.max(spectrogram)`, чтобы установить самую громкую часть на 0 дБ. Должно быть больше нуля.

min_value (`float`, *optional*, по умолчанию `1e-5`) : Спектрограмма будет обрезана до этого минимального значения перед преобразованием в децибелы, чтобы избежать вычисления `log(0)`. Значение по умолчанию `1e-5` соответствует минимуму -100 дБ. Должно быть больше нуля.

db_range (`float`, *optional*) : Задаёт максимальный динамический диапазон в децибелах. Например, если `db_range = 80`, разница между пиковым значением и минимальным значением никогда не превысит 80 дБ. Должно быть больше нуля.

**Возвращает:** `np.ndarray`

спектрограмма в децибелах

Преобразует спектрограмму амплитуд в децибальную шкалу. Вычисляет `20 * log10(spectrogram / reference)`, используя базовые свойства логарифма для численной устойчивости.

Мотивация применения логарифмической функции к (мел-)спектрограмме заключается в том, что человек воспринимает громкость не по линейной шкале. Как правило, чтобы удвоить воспринимаемую громкость звука, необходимо увеличить его энергию в 8 раз. Это означает, что значительные вариации энергии могут не звучать столь заметно, если звук изначально громкий. Эта операция сжатия позволяет признакам (мел-)спектрограммы точнее соответствовать тому, что человек действительно слышит.

