# 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]]

#### 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')
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L580)

**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 frecuencias 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[[transformers.audio_utils.mel_to_hertz]]

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

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L616)

**Parámetros:**

mels (`float` o `np.ndarray`) : La frecuencia, o varias frecuencias, en mels.

mel_scale (`str`, *opcional*, `"htk"`) : La escala de frecuencias 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[[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'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L770)

**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 frecuencias 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. Debe establecerse en `true` para obtener los mismos resultados que `torchaudio` al calcular los filtros mel.

dtype (`str` o `np.dtype`, *opcional*, por defecto `np.float64`) : Tipo de datos de los filtros devueltos. Los filtros triangulares se calculan en float64 y se convierten a `dtype` antes de la normalización `"slaney"`. Con `norm="slaney"`, `mel_scale="slaney"` y `dtype=np.float32`, el resultado es exacto a nivel de bits con `librosa.filters.mel(..., norm="slaney")` (transpuesto).

**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 *bancos 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 en función de 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: el de la Cambridge HMM Toolkit (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: proviene del Auditory Toolbox para MATLAB escrito por Slaney en 1998, asume una frecuencia 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 frecuencia 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[[transformers.audio_utils.optimal_fft_length]]

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

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L869)

Encuentra el mejor tamaño de entrada FFT para una `window_length` dada. Esta función toma una longitud de ventana dada y, si no es 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[[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)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L882)

**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`) : Indica 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 menor que la longitud del cuadro, para que se rellene con ceros.

center (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe centrar la ventana dentro del búfer de FFT. Solo se utiliza cuando se proporciona `frame_length`.

**Devuelve:**

`np.ndarray` de forma `(window_length,)` o `(frame_length,)` que contiene la ventana.

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[[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'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L946)

**Parámetros:**

waveform (`np.ndarray` de forma `(length,)`) : La forma de onda de entrada. Debe ser una forma de onda mono con valores reales.

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`) : El desplazamiento 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, este valor debe ser una potencia de dos. Si es `None`, se utiliza `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 fotograma `t` esté centrado en el tiempo `t * hop_length`. Si es `False`, el fotograma `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 se calculan las frecuencias positivas y se devuelve un espectrograma que contiene `fft_length // 2 + 1` bandas de frecuencia. Si es False, también se calculan las frecuencias negativas y se devuelven `fft_length` bandas de frecuencia.

dither (`float`, *opcional*, valor predeterminado 0.0) : Añade dithering. Es decir, añade un pequeño ruido gaussiano a cada fotograma. Por ejemplo, use 4.0 para añadir dithering con una distribución normal centrada en 0.0 con desviación estándar 4.0; 0.0 significa sin dithering. El dithering tiene un efecto similar al de `mel_floor`. Reduce los valores altos de log_mel_fbank para señales con secciones de cero duro, cuando hay un corte de VAD en la señal.

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 de la 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 de pico y el valor más pequeño nunca superará los 80 dB. Debe ser mayor que cero.

remove_dc_offset (`bool`, *opcional*) : Resta la media de la forma de onda en cada marco, aplicado antes de la preénfasis. 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`.

**Devuelve:**

`nd.array` que contiene un espectrograma de forma `(num_frequency_bins, length)` para un espectrograma regular o de forma `(num_mel_filters, length)` para un espectrograma mel.

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 a partir 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[[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)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L1368)

**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 de la 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 de pico y el valor más pequeño nunca superará los 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 del logaritmo para la estabilidad numérica.

La motivación para 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) se ajusten más de cerca a lo que los humanos realmente oyen.

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

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/audio_utils.py#L1468)

**Parámetros:**

spectrogram (`np.ndarray`) : El espectrograma de amplitud (mel) de entrada.

reference (`float`, *opcional*, valor predeterminado 1.0) : Establece el valor de la 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 de pico y el valor más pequeño nunca superará los 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 para 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) se ajusten más de cerca a lo que los humanos realmente oyen.

