Transformers documentation
Utilidades para FeatureExtractors
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
< source >( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
Convierte la frecuencia de hercios a mels.
transformers.audio_utils.mel_to_hertz
< source >( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
Convierte la frecuencia de mels a hercios.
transformers.audio_utils.mel_filter_bank
< source >( 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 an_fft // 2 + 1, donden_fftes 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 superarsampling_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 predeterminadoFalse) — Si esta opción está habilitada, el filtro triangular se aplica en el espacio mel en lugar del espacio de frecuencia. Esto debe establecerse entruepara obtener los mismos resultados quetorchaudioal 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".
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
< source >( 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 predeterminadoTrue) — 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 paraframe_lengthsi la ventana es más pequeña que la longitud del cuadro, para que se rellene con ceros. - center (
bool, opcional, valor predeterminadoTrue) — Si se centra la ventana dentro del búfer de FFT. Solo se utiliza cuando se proporcionaframe_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
< source >( 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.ndarrayde forma(length,)) — La forma de onda de entrada. Debe ser una forma de onda mono de valor real único. - window (
np.ndarrayde 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 queframe_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 afft_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 esNone, se usaframe_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 esNone, devuelve números complejos. - center (
bool, opcional, valor predeterminadoTrue) — Indica si se debe rellenar la forma de onda para que el marcotesté centrado en el tiempot * hop_length. Si esFalse, el marcotcomenzará en el tiempot * hop_length. - pad_mode (
str, opcional, valor predeterminado"reflect") — Modo de relleno utilizado cuandocenteresTrue. Los valores posibles son:"constant"(rellenar con ceros),"edge"(rellenar con los valores del borde),"reflect"(rellenar con valores reflejados). - onesided (
bool, opcional, valor predeterminadoTrue) — Si es True, solo calcula las frecuencias positivas y devuelve un espectrograma que contienefft_length // 2 + 1bins de frecuencia. Si es False, también calcula las frecuencias negativas y devuelvefft_lengthbins 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 asmel_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.ndarrayde 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 cuandopowerno esNone. - reference (
float, opcional, valor predeterminado 1.0) — Establece el valor del espectrograma de entrada que corresponde a 0 dB. Por ejemplo, usenp.max(spectrogram)para establecer la parte más fuerte en 0 dB. Debe ser mayor que cero. - min_value (
float, opcional, valor predeterminado1e-10) — El espectrograma se recortará a este valor mínimo antes de la conversión a decibelios, para evitar calcularlog(0). Para un espectrograma de potencia, el valor predeterminado de1e-10corresponde a un mínimo de -100 dB. Para un espectrograma de amplitud, el valor1e-5corresponde a -100 dB. Debe ser mayor que cero. - db_range (
float, opcional) — Establece el rango dinámico máximo en decibelios. Por ejemplo, sidb_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 entruepara obtener los mismos resultados quetorchaudio.compliance.kaldi.fbankal calcular los filtros mel. - dtype (
np.dtype, opcional, valor predeterminadonp.float32) — Tipo de datos del tensor del espectrograma. Sipoweres 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_filtersylog_mel)
Cómo funciona:
- La forma de onda de entrada se divide en tramas de tamaño
frame_lengthque se solapan parcialmente en `frame_length- muestras de `hop_length`.
- Cada fotograma se multiplica por la ventana y se coloca en un búfer de tamaño
fft_length. - La DFT se toma de cada enventanada.
- 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
< source >( 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, usenp.max(spectrogram)para establecer la parte más fuerte en 0 dB. Debe ser mayor que cero. - min_value (
float, opcional, valor predeterminado1e-10) — El espectrograma se recortará a este valor mínimo antes de la conversión a decibelios, para evitar calcularlog(0). El valor predeterminado de1e-10corresponde 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, sidb_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
< source >( 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, usenp.max(spectrogram)para establecer la parte más fuerte en 0 dB. Debe ser mayor que cero. - min_value (
float, opcional, valor predeterminado1e-5) — El espectrograma se recortará a este valor mínimo antes de la conversión a decibelios, para evitar calcularlog(0). El valor predeterminado de1e-5corresponde 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, sidb_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.