Hugging Face's logo

Transformers documentation

Утилиты для FeatureExtractors

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Утилиты для FeatureExtractors

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

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

Преобразования аудио

transformers.audio_utils.hertz_to_mel

< >

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

Параметры

  • freq (float или np.ndarray) — Частота или несколько частот в герцах (Гц).
  • mel_scale (str, необязательный, по умолчанию "htk") — Масштаб мел-частот, который следует использовать: "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_scale (str, необязательный, "htk") — Масштаб мел-частот, который следует использовать: "htk", "kaldi" или "slaney".

Возвращает

float или np.ndarray

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

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

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 = False ) → np.ndarray of shape (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) — Если этот параметр включен, треугольный фильтр применяется в mel-пространстве, а не в частотном. Чтобы получить те же результаты, что и torchaudio при вычислении mel-фильтров, это значение должно быть установлено в true.

Возвращает

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) Skowronski и Harris (2004) предполагает частоту дискретизации 12,5 кГц и полосу частот речи [0, 6250] Гц.

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

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

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

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

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) — Определяет, нужно ли центрировать окно внутри буфера БПФ. Используется только при заданном 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, необязательный) — Размер буфера БПФ в отсчетах. Определяет количество частотных бинов на спектрограмме. Для оптимальной скорости это значение должно быть степенью двойки. Если 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) — Добавляет дитеринг. Иными словами, добавляет небольшой гауссов шум к каждому кадру. Например, значение 4.0 добавляет дитеринг с нормальным распределением, центрированным вокруг 0.0 со стандартным отклонением 4.0; 0.0 означает отсутствие дитеринга. Дитеринг оказывает аналогичный эффект, что и mel_floor. Он снижает высокие значения log_mel_fbank для сигналов с участками, где значения равны нулю, если в сигнале присутствует порог VAD.
  • 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, необязательный, по умолчанию 1.0) — Задает значение входной спектрограммы, соответствующее 0 дБ. Например, используйте np.max(spectrogram), чтобы установить самую громкую часть на 0 дБ. Должно быть больше нуля.
  • min_value (float, необязательный, по умолчанию 1e-10) — Спектрограмма будет обрезана до этого минимального значения перед преобразованием в децибелы, чтобы избежать вычисления log(0). Для спектрограммы мощности значение по умолчанию 1e-10 соответствует минимуму -100 дБ. Для спектрограммы амплитуды значение 1e-5 соответствует -100 дБ. Должно быть больше нуля.
  • db_range (float, необязательный) — Задаёт максимальный динамический диапазон в децибелах. Например, если db_range = 80, разница между пиковым значением и наименьшим значением никогда не превысит 80 дБ. Должно быть больше нуля.
  • remove_dc_offset (bool, необязательный) — Вычитание среднего значения из волнового сигнала в каждом кадре, применяется до предварительного усиления. Это значение должно быть установлено в true, чтобы получить те же результаты, что и torchaudio.compliance.kaldi.fbank, при вычислении мел-фильтров.
  • 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)

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

  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

< >

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

Параметры

  • spectrogram (np.ndarray) — Входная спектральная плотность мощности (мел-спектрограмма). Обратите внимание, что в спектральной плотности мощности амплитуды возведены в квадрат!
  • reference (float, необязательный, по умолчанию 1.0) — Задает значение входной спектрограммы, соответствующее 0 дБ. Например, используйте np.max(spectrogram), чтобы установить самую громкую часть на 0 дБ. Должно быть больше нуля.
  • min_value (float, необязательный, по умолчанию 1e-10) — Спектрограмма будет обрезана до этого минимального значения перед преобразованием в децибелы, чтобы избежать вычисления log(0). Значение по умолчанию 1e-10 соответствует минимуму -100 дБ. Должно быть больше нуля.
  • db_range (float, необязательный) — Задаёт максимальный динамический диапазон в децибелах. Например, если db_range = 80, разница между пиковым значением и наименьшим значением никогда не превысит 80 дБ. Должно быть больше нуля.

Возвращает

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) — Входная амплитудная (мел-) спектрограмма.
  • reference (float, необязательный, по умолчанию 1.0) — Задает значение входной спектрограммы, соответствующее 0 дБ. Например, используйте np.max(spectrogram), чтобы установить самую громкую часть на 0 дБ. Должно быть больше нуля.
  • min_value (float, необязательный, по умолчанию 1e-5) — Спектрограмма будет обрезана до этого минимального значения перед преобразованием в децибелы, чтобы избежать вычисления log(0). Значение по умолчанию 1e-5 соответствует минимуму -100 дБ. Должно быть больше нуля.
  • db_range (float, необязательный) — Задаёт максимальный динамический диапазон в децибелах. Например, если db_range = 80, разница между пиковым значением и наименьшим значением никогда не превысит 80 дБ. Должно быть больше нуля.

Возвращает

np.ndarray

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

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

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

Update on GitHub

←Утилиты для процессоров изображений Общие утилиты→