Transformers documentation

Utilidades para 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

Utilidades para FeatureExtractors

Esta página enumera todas las funciones de utilidad que puede utilizar el FeatureExtractor de audio para calcular características especiales a partir de un audio sin procesar, utilizando algoritmos comunes como la Short Time Fourier Transform o el log mel spectrogram.

La mayoría de esos parámetros solo son útiles si estás estudiando el código de los procesadores de audio de la biblioteca.

Transformaciones de audio

transformers.audio_utils.hertz_to_mel

< >

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

Parámetros

  • freq (float o np.ndarray) — La frecuencia, o varias frecuencias, en hercios (Hz).
  • mel_scale (str, opcional, valor predeterminado "htk") — La escala de frecuencia mel a utilizar, "htk", "kaldi" o "slaney".

Devuelve

float o np.ndarray

Las frecuencias en la escala mel.

Convierte la frecuencia de hercios a mels.

transformers.audio_utils.mel_to_hertz

< >

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

Parámetros

  • mels (float o np.ndarray) — La frecuencia, o múltiples frecuencias, en mels.
  • mel_scale (str, opcional, "htk") — La escala de frecuencia mel a utilizar, "htk", "kaldi" o "slaney".

Devuelve

float o np.ndarray

Las frecuencias en hercios.

Convierte la frecuencia de mels a hercios.

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)

Parámetros

  • num_frequency_bins (int) — Número de bandas de frecuencia (debe ser igual a n_fft // 2 + 1, donde n_fft es el tamaño de la Transformada de Fourier utilizada para calcular el espectrograma).
  • num_mel_filters (int) — Número de filtros mel que se generarán.
  • min_frequency (float) — Frecuencia mínima de interés en Hz.
  • max_frequency (float) — Frecuencia máxima de interés en Hz. Este valor no debe superar sampling_rate / 2.
  • sampling_rate (int) — Tasa de muestreo de la forma de onda de audio.
  • norm (str, opcional) — Si es "slaney", divide los pesos mel triangulares por el ancho de la banda mel (normalización de área).
  • mel_scale (str, opcional, valor predeterminado "htk") — La escala de frecuencia mel a utilizar, "htk", "kaldi" o "slaney".
  • triangularize_in_mel_space (bool, opcional, valor predeterminado False) — Si esta opción está habilitada, el filtro triangular se aplica en el espacio mel en lugar del espacio de frecuencia. Esto debe establecerse en true para obtener los mismos resultados que torchaudio al calcular los filtros mel.

Devuelve

np.ndarray de forma (num_frequency_bins, num_mel_filters)

Matriz de banco de filtros triangular. Esta es una matriz de proyección para pasar de un espectrograma a un espectrograma mel.

Crea una matriz de conversión de bandas de frecuencia utilizada para obtener un espectrograma mel. Esto se denomina banco de filtros mel, y existen diversas implementaciones que difieren en el número de filtros, la forma de los filtros, la forma en que se distribuyen, el ancho de banda de los filtros y la manera en que se deforma el espectro. El objetivo de estas características es aproximar la percepción no lineal humana de la variación del tono con respecto a la frecuencia.

Se introdujeron diferentes bancos de filtros mel en la literatura. Se admiten las siguientes variaciones:

  • MFCC FB-20: introducida en 1980 por Davis y Mermelstein, asume una frecuencia de muestreo de 10 kHz y un ancho de banda de voz de [0, 4600] Hz.
  • MFCC FB-24 HTK: del Kit de HMM de Cambridge (HTK) (1995) utiliza un banco de filtros de 24 filtros para un ancho de banda de voz de [0, 8000] Hz. Esto asume una tasa de muestreo ≥ 16 kHz.
  • MFCC FB-40: del Auditory Toolbox para MATLAB escrito por Slaney en 1998, asume una tasa de muestreo de 16 kHz y un ancho de banda de voz de [133, 6854] Hz. Esta versión también incluye normalización de área.
  • HFCC-E FB-29 (Human Factor Cepstral Coefficients) de Skowronski y Harris (2004) asume una tasa de muestreo de 12,5 kHz y un ancho de banda de voz de [0, 6250] Hz.

Este código se adapta de torchaudio y librosa. Tenga en cuenta que los parámetros predeterminados de melscale_fbanks de torchaudio implementan los filtros "htk", mientras que librosa utiliza la implementación "slaney".

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

Encuentra el mejor tamaño de entrada de FFT para una window_length dada. Esta función toma una longitud de ventana dada y, si no es ya una potencia de dos, la redondea hacia arriba a la siguiente potencia de dos.

El algoritmo FFT funciona más rápido cuando la longitud de la entrada es una potencia de dos, lo cual puede ser mayor que el tamaño de la ventana o el marco de análisis. Por ejemplo, si la ventana es de 400 muestras, usar un tamaño de entrada FFT de 512 muestras es más óptimo que un tamaño FFT de 400 muestras. Usar un tamaño FFT más grande no afecta a las frecuencias detectadas, simplemente proporciona una mayor resolución de frecuencia (es decir, los bins de frecuencia son más pequeños).

transformers.audio_utils.window_function

< >

( window_length: intname: str = 'hann'periodic: bool = Trueframe_length: int | None = Nonecenter: bool = True )

Parámetros

  • window_length (int) — La longitud de la ventana en muestras.
  • name (str, opcional, valor predeterminado "hann") — El nombre de la función de ventana.
  • periodic (bool, opcional, valor predeterminado True) — Si la ventana es periódica o simétrica.
  • frame_length (int, opcional) — La longitud de los cuadros de análisis en muestras. Proporcione un valor para frame_length si la ventana es más pequeña que la longitud del cuadro, para que se rellene con ceros.
  • center (bool, opcional, valor predeterminado True) — Si se centra la ventana dentro del búfer de FFT. Solo se utiliza cuando se proporciona frame_length.

Devuelve un array que contiene la ventana especificada. Esta ventana está destinada a usarse con stft.

Se admiten los siguientes tipos de ventana:

  • "boxcar": una ventana rectangular
  • "hamming": la ventana de Hamming
  • "hann": la ventana de Hann
  • "povey": la ventana de 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'> )

Parámetros

  • waveform (np.ndarray de forma (length,)) — La forma de onda de entrada. Debe ser una forma de onda mono de valor real único.
  • window (np.ndarray de forma (frame_length,)) — La función de ventana a aplicar, incluyendo el relleno con ceros si es necesario. La longitud real de la ventana puede ser menor que frame_length, pero asumimos que el array ya ha sido rellenado con ceros.
  • frame_length (int) — La longitud de los cuadros de análisis en muestras. Con librosa, esto siempre es igual a fft_length, pero también permitimos tamaños menores.
  • hop_length (int) — La distancia entre los marcos de análisis sucesivos en muestras.
  • fft_length (int, opcional) — El tamaño del búfer de FFT en muestras. Esto determina cuántos bins de frecuencia tendrá el espectrograma. Para una velocidad óptima, debería ser una potencia de dos. Si es None, se usa frame_length.
  • power (float, opcional, valor predeterminado 1.0) — Si es 1.0, devuelve el espectrograma de amplitud. Si es 2.0, devuelve el espectrograma de potencia. Si es None, devuelve números complejos.
  • center (bool, opcional, valor predeterminado True) — Indica si se debe rellenar la forma de onda para que el marco t esté centrado en el tiempo t * hop_length. Si es False, el marco t comenzará en el tiempo t * hop_length.
  • pad_mode (str, opcional, valor predeterminado "reflect") — Modo de relleno utilizado cuando center es True. Los valores posibles son: "constant" (rellenar con ceros), "edge" (rellenar con los valores del borde), "reflect" (rellenar con valores reflejados).
  • onesided (bool, opcional, valor predeterminado True) — Si es True, solo calcula las frecuencias positivas y devuelve un espectrograma que contiene fft_length // 2 + 1 bins de frecuencia. Si es False, también calcula las frecuencias negativas y devuelve fft_length bins de frecuencia.
  • dither (float, optional, defaults to 0.0) — Adds dithering. In other words, adds a small Gaussian noise to each frame. E.g. use 4.0 to add dithering with a normal distribution centered around 0.0 with standard deviation 4.0, 0.0 means no dithering. Dithering has similar effect as mel_floor. It reduces the high log_mel_fbank values for signals with hard-zero sections, when VAD cutoff is present in the signal.
  • preemphasis (float, opcional) — Coeficiente para un filtro paso bajo que aplica preénfasis antes de la DFT.
  • mel_filters (np.ndarray de forma (num_freq_bins, num_mel_filters), opcional) — El banco de filtros mel. Si se proporciona, se aplica este banco de filtros para crear un espectrograma mel.
  • mel_floor (float, opcional, valor predeterminado 1e-10) — Valor mínimo de los bancos de frecuencias mel.
  • log_mel (str, opcional) — Cómo convertir el espectrograma a escala logarítmica. Las opciones posibles son: None (no convertir), "log" (tomar el logaritmo natural) "log10" (tomar el logaritmo en base 10), "dB" (convertir a decibelios). Solo se puede usar cuando power no es None.
  • reference (float, opcional, valor predeterminado 1.0) — Establece el valor del espectrograma de entrada que corresponde a 0 dB. Por ejemplo, use np.max(spectrogram) para establecer la parte más fuerte en 0 dB. Debe ser mayor que cero.
  • min_value (float, opcional, valor predeterminado 1e-10) — El espectrograma se recortará a este valor mínimo antes de la conversión a decibelios, para evitar calcular log(0). Para un espectrograma de potencia, el valor predeterminado de 1e-10 corresponde a un mínimo de -100 dB. Para un espectrograma de amplitud, el valor 1e-5 corresponde a -100 dB. Debe ser mayor que cero.
  • db_range (float, opcional) — Establece el rango dinámico máximo en decibelios. Por ejemplo, si db_range = 80, la diferencia entre el valor pico y el valor más pequeño nunca será superior a 80 dB. Debe ser mayor que cero.
  • remove_dc_offset (bool, opcional) — Resta la media de la forma de onda en cada cuadro, aplicado antes de la preénfasis. Esto debe establecerse en true para obtener los mismos resultados que torchaudio.compliance.kaldi.fbank al calcular los filtros mel.
  • dtype (np.dtype, opcional, valor predeterminado np.float32) — Tipo de datos del tensor del espectrograma. Si power es None, este argumento se ignora y el dtype será np.complex64.

Calcula un espectrograma sobre una forma de onda utilizando la Transformada de Fourier de Tiempo Corto.

Esta función puede crear los siguientes tipos de espectrogramas:

  • espectrograma de amplitud (power = 1.0)
  • espectrograma de potencia (power = 2.0)
  • espectrograma de valores complejos (power = None)
  • espectrograma logarítmico (use el argumento log_mel)
  • espectrograma mel (proporcionar mel_filters)
  • espectrograma log-mel (proporcione mel_filters y log_mel)

Cómo funciona:

  1. La forma de onda de entrada se divide en tramas de tamaño frame_length que se solapan parcialmente en `frame_length
    • muestras de `hop_length`.
  2. Cada fotograma se multiplica por la ventana y se coloca en un búfer de tamaño fft_length.
  3. La DFT se toma de cada enventanada.
  4. Los resultados se apilan en un espectrograma.

Hacemos una distinción entre los siguientes “bloques” de datos de muestra, cada uno de los cuales puede tener una longitud diferente:

  • El marco de análisis. Este es el tamaño de las porciones de tiempo en las que se divide la forma de onda de entrada.
  • La ventana. Cada cuadro de análisis se multiplica por la ventana para evitar la fuga espectral.
  • El búfer de entrada de la FFT. La longitud de este determina cuántos bins de frecuencia hay en el espectrograma.

En esta implementación, se asume que la ventana está rellena con ceros para tener el mismo tamaño que el marco de análisis. Una ventana rellena puede obtenerse de window_function(). El búfer de entrada de la FFT puede ser mayor que el marco de análisis, típicamente la siguiente potencia de dos.

Nota: Esta función aún no está optimizada para la velocidad. Debería ser compatible en gran medida con librosa.stft y torchaudio.functional.transforms.Spectrogram, aunque es más flexible debido a las diferentes formas en que se pueden construir los espectrogramas.

transformers.audio_utils.power_to_db

< >

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

Parámetros

  • spectrogram (np.ndarray) — El espectrograma de potencia (mel) de entrada. Tenga en cuenta que un espectrograma de potencia tiene las amplitudes al cuadrado.
  • reference (float, opcional, valor predeterminado 1.0) — Establece el valor del espectrograma de entrada que corresponde a 0 dB. Por ejemplo, use np.max(spectrogram) para establecer la parte más fuerte en 0 dB. Debe ser mayor que cero.
  • min_value (float, opcional, valor predeterminado 1e-10) — El espectrograma se recortará a este valor mínimo antes de la conversión a decibelios, para evitar calcular log(0). El valor predeterminado de 1e-10 corresponde a un mínimo de -100 dB. Debe ser mayor que cero.
  • db_range (float, opcional) — Establece el rango dinámico máximo en decibelios. Por ejemplo, si db_range = 80, la diferencia entre el valor pico y el valor más pequeño nunca será superior a 80 dB. Debe ser mayor que cero.

Devuelve

np.ndarray

el espectrograma en decibelios

Convierte un espectrograma de potencia a la escala de decibelios. Esto calcula 10 * log10(spectrogram / reference), utilizando propiedades básicas de los logaritmos para la estabilidad numérica.

La motivación detrás de aplicar la función logaritmo al espectrograma (mel) es que los humanos no perciben la intensidad sonora en una escala lineal. En general, para duplicar el volumen percibido de un sonido, es necesario introducir 8 veces más energía en él. Esto significa que las grandes variaciones de energía pueden no sonar tan diferentes si el sonido ya es fuerte de por sí. Esta operación de compresión hace que las características del espectrograma (mel) coincidan más de cerca con lo que los humanos realmente oyen.

Basado en la implementación de 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

Parámetros

  • spectrogram (np.ndarray) — El espectrograma de amplitud (mel) de entrada.
  • reference (float, opcional, valor predeterminado 1.0) — Establece el valor del espectrograma de entrada que corresponde a 0 dB. Por ejemplo, use np.max(spectrogram) para establecer la parte más fuerte en 0 dB. Debe ser mayor que cero.
  • min_value (float, opcional, valor predeterminado 1e-5) — El espectrograma se recortará a este valor mínimo antes de la conversión a decibelios, para evitar calcular log(0). El valor predeterminado de 1e-5 corresponde a un mínimo de -100 dB. Debe ser mayor que cero.
  • db_range (float, opcional) — Establece el rango dinámico máximo en decibelios. Por ejemplo, si db_range = 80, la diferencia entre el valor pico y el valor más pequeño nunca será superior a 80 dB. Debe ser mayor que cero.

Devuelve

np.ndarray

el espectrograma en decibelios

Convierte un espectrograma de amplitud a la escala de decibelios. Esto calcula 20 * log10(spectrogram / reference), utilizando propiedades básicas del logaritmo para la estabilidad numérica.

La motivación detrás de aplicar la función logaritmo al espectrograma (mel) es que los humanos no perciben la intensidad sonora en una escala lineal. En general, para duplicar el volumen percibido de un sonido, es necesario introducir 8 veces más energía en él. Esto significa que las grandes variaciones de energía pueden no sonar tan diferentes si el sonido ya es fuerte de por sí. Esta operación de compresión hace que las características del espectrograma (mel) coincidan más de cerca con lo que los humanos realmente oyen.

Update on GitHub