# EnCodec

## Resumen

El modelo de códec neuronal EnCodec fue propuesto en [High Fidelity Neural Audio Compression](https://huggingface.co/papers/2210.13438) por Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

El resumen del artículo es el siguiente:

*Presentamos un códec de audio en tiempo real y de alta fidelidad, de última generación, que aprovecha redes neuronales. Consiste en una arquitectura de codificador-decodificador en streaming con un espacio latente cuantizado, entrenada de extremo a extremo. Simplificamos y aceleramos el entrenamiento mediante el uso de un único adversario de espectrograma multiescala, que reduce de manera eficiente los artefactos y produce muestras de alta calidad. Introducimos un mecanismo novedoso de equilibrador de pérdidas para estabilizar el entrenamiento: el peso de una pérdida define ahora la fracción del gradiente total que debe representar, lo que desacopla la elección de este hiperparámetro de la escala típica de la pérdida. Finalmente, estudiamos cómo los modelos Transformer ligeros pueden utilizarse para comprimir aún más la representación obtenida hasta un 40%, manteniéndose más rápidos que el tiempo real. Proporcionamos una descripción detallada de las decisiones de diseño clave del modelo propuesto, que incluyen: el objetivo de entrenamiento, los cambios arquitectónicos y un estudio de diversas funciones de pérdida perceptual. Presentamos una evaluación subjetiva extensa (pruebas MUSHRA) junto con un estudio de ablatión para una serie de anchos de banda y dominios de audio, que incluyen voz, voz con ruido y reverberación, y música. Nuestro enfoque es superior a los métodos de referencia en todos los escenarios evaluados, considerando tanto audio monofónico a 24 kHz como audio estéreo a 48 kHz.*

Este modelo fue aportado por [Matthijs](https://huggingface.co/Matthijs), [Patrick Von Platen](https://huggingface.co/patrickvonplaten) y [Arthur Zucker](https://huggingface.co/ArthurZ). El código original se puede encontrar [aquí](https://github.com/facebookresearch/encodec).

## Ejemplo de uso

Aquí hay un ejemplo rápido de cómo codificar y decodificar un audio con este modelo:

```python
from datasets import Audio, load_dataset

from transformers import AutoProcessor, EncodecModel

librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

model = EncodecModel.from_pretrained("facebook/encodec_24khz", device_map="auto")
processor = AutoProcessor.from_pretrained("facebook/encodec_24khz")
librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
audio_sample = librispeech_dummy[-1]["audio"]["array"]
inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt").to(model.device)

encoder_outputs = model.encode(inputs["input_values"], inputs["padding_mask"])
# `encoder_outputs.audio_codes` contains discrete codes
audio_values = model.decode(**encoder_outputs, padding_mask=inputs["padding_mask"])[0]
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"], inputs["padding_mask"]).audio_values
```

## EncodecConfig[[transformers.EncodecConfig]]

#### transformers.EncodecConfig[[transformers.EncodecConfig]]

```python
transformers.EncodecConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, target_bandwidths: list[float] | tuple[float, ...] = (1.5, 3.0, 6.0, 12.0, 24.0), sampling_rate: int = 24000, audio_channels: int = 1, normalize: bool = False, chunk_length_s: int | float | None = None, overlap: float | None = None, hidden_size: int = 128, num_filters: int = 32, num_residual_layers: int = 1, upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2), norm_type: str = 'weight_norm', kernel_size: int = 7, last_kernel_size: int = 7, residual_kernel_size: int = 3, dilation_growth_rate: int = 2, use_causal_conv: bool = True, pad_mode: str = 'reflect', compress: int = 2, num_lstm_layers: int = 2, trim_right_ratio: float = 1.0, codebook_size: int = 1024, codebook_dim: int | None = None, use_conv_shortcut: bool = True)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/configuration_encodec.py#L27)

**Parámetros:**

target_bandwidths (`list[float]`, *opcional*, valor predeterminado `[1.5, 3.0, 6.0, 12.0, 24.0]`) : El rango de distintas bandas de frecuencia con las que el modelo puede codificar el audio.

sampling_rate (`int`, *opcional*, valor predeterminado `24000`) : La frecuencia de muestreo a la que deben digitalizarse los archivos de audio, expresada en hercios (Hz).

audio_channels (`int`, *opcional*, valor predeterminado `1`) : El número de canales de entrada.

normalize (`bool`, *opcional*, valor predeterminado `False`) : Indica si el audio debe normalizarse al pasarse.

chunk_length_s (`float`, *opcional*) : Si se define, el audio se preprocesa en fragmentos de longitud `chunk_length_s` y luego se codifica.

overlap (`float`, *opcional*) : Define la superposición entre cada fragmento. Se utiliza para calcular `chunk_stride` mediante la siguiente fórmula: `int((1.0 - self.overlap) * self.chunk_length)`.

hidden_size (`int`, *opcional*, valor predeterminado `128`) : Dimensión de las representaciones ocultas.

num_filters (`int`, *opcional*, valor predeterminado 32) : Número de núcleos de convolución de la primera capa de muestreo descendente `EncodecConv1d`.

num_residual_layers (`int`,  *opcional*, valor predeterminado 1) : Número de capas residuales.

upsampling_ratios (`Sequence[int]` , *opcional*, valor predeterminado `[8, 5, 4, 2]`) : Proporciones de tamaño y desplazamiento del kernel. El codificador utiliza proporciones de muestreo descendente en lugar de proporciones de muestreo ascendente, por lo que utilizará las proporciones en el orden inverso al especificado aquí, que debe coincidir con el orden del decodificador.

norm_type (`str`, *opcional*, valor predeterminado `"weight_norm"`) : Método de normalización. Debe estar en `["weight_norm", "time_group_norm"]`

kernel_size (`int`, *opcional*, valor predeterminado 7) : Tamaño del kernel para la convolución inicial.

last_kernel_size (`int`, *opcional*, valor predeterminado: 7) : Tamaño del kernel para la última capa de convolución.

residual_kernel_size (`int`, *opcional*, valor predeterminado 3) : Tamaño del kernel para las capas residuales.

dilation_growth_rate (`int`, *opcional*, valor predeterminado 2) : Cuánto aumentar la dilatación en cada capa.

use_causal_conv (`bool`, *opcional*, valor predeterminado `True`) : Si se debe usar convolución totalmente causal.

pad_mode (`str`, *opcional*, valor predeterminado `"reflect"`) : Modo de relleno para las convoluciones.

compress (`int`, *opcional*, valor predeterminado 2) : Dimensionalidad reducida en las ramas residuales (de Demucs v3).

num_lstm_layers (`int`, *opcional*, valor predeterminado 2) : Número de capas LSTM al final del codificador.

trim_right_ratio (`float`, *opcional*, valor predeterminado 1.0) : Proporción para el recorte en la parte derecha de la convolución transpuesta bajo la configuración `use_causal_conv = True`. Si es igual a 1.0, significa que todo el recorte se realiza en la parte derecha.

codebook_size (`int`, *opcional*, valor predeterminado `1024`) : El número de libros de códigos paralelos que utiliza el modelo.

codebook_dim (`int`, *opcional*) : Dimensionalidad de cada vector de incrustación del libro de códigos.

use_conv_shortcut (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe usar una capa convolucional como conexión 'skip' en el bloque `EncodecResnetBlock`. Si es False, se utilizará una función identidad, lo que proporciona una conexión residual genérica.

Esta es la clase de configuración para almacenar la configuración de un EncodecModel. Se utiliza para instanciar un modelo Encodec según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

Ejemplo:

```python
>>> from transformers import EncodecModel, EncodecConfig

>>> # Initializing a "facebook/encodec_24khz" style configuration
>>> configuration = EncodecConfig()

>>> # Initializing a model (with random weights) from the "facebook/encodec_24khz" style configuration
>>> model = EncodecModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## EncodecFeatureExtractor[[transformers.EncodecFeatureExtractor]]

#### transformers.EncodecFeatureExtractor[[transformers.EncodecFeatureExtractor]]

```python
transformers.EncodecFeatureExtractor(feature_size: int = 1, sampling_rate: int = 24000, padding_value: float = 0.0, chunk_length_s: float | None = None, overlap: float | None = None, **kwargs)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/feature_extraction_encodec.py#L26)

**Parámetros:**

feature_size (`int`, *opcional*, valor predeterminado 1) : La dimensión de las características de las características extraídas. Use 1 para mono y 2 para estéreo.

sampling_rate (`int`, *opcional*, valor predeterminado 24000) : La frecuencia de muestreo a la que se debe digitalizar la forma de onda de audio, expresada en hercios (Hz).

padding_value (`float`, *opcional*, valor predeterminado 0.0) : El valor que se utiliza para rellenar los valores de relleno (padding).

chunk_length_s (`float`, *opcional*) : Si se define, el audio se preprocesa en fragmentos de longitud `chunk_length_s` y luego se codifica.

overlap (`float`, *opcional*) : Define la superposición entre cada fragmento. Se utiliza para calcular `chunk_stride` mediante la siguiente fórmula: `int((1.0 - self.overlap) * self.chunk_length)`.

Construye un extractor de características de EnCodec.

Este extractor de características hereda de [SequenceFeatureExtractor](/docs/transformers/v5.23.0/es/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), que contiene la mayoría de los métodos principales. Los usuarios deben consultar esta superclase para obtener más información sobre dichos métodos.

Instanciar un extractor de características con los valores predeterminados producirá una configuración similar a la de la arquitectura [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz).

#### __llamada__[[transformers.EncodecFeatureExtractor.__call__]]

```python
__call__(raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str | transformers.utils.generic.PaddingStrategy | None = None, truncation: bool | None = False, max_length: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/feature_extraction_encodec.py#L81)

**Parámetros:**

raw_audio (`np.ndarray`, `list[float]`, `list[np.ndarray]`, `list[list[float]]`) : La secuencia o el lote de secuencias a procesar. Cada secuencia puede ser un array de numpy, una lista de valores flotantes, una lista de arrays de numpy o una lista de listas de valores flotantes. El array de numpy debe tener la forma `(num_samples,)` para audio mono (`feature_size = 1`), o `(2, num_samples)` para audio estéreo (`feature_size = 2`).

padding (`bool`, `str` o [PaddingStrategy](/docs/transformers/v5.23.0/es/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, valor predeterminado `True`) : Selecciona una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre:  - `True` o `'longest'`: Rellena hasta la secuencia más larga del lote (o no aplica relleno si solo se proporciona una secuencia). - `'max_length'`: Rellena hasta una longitud máxima especificada con el argumento `max_length` o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona dicho argumento. - `False` o `'do_not_pad'` (predeterminado): Sin relleno (es decir, puede devolver un lote con secuencias de longitudes diferentes).

truncation (`bool`, *opcional*, valor predeterminado `False`) : Activa la truncación para recortar las secuencias de entrada más largas que `max_length` hasta `max_length`.

max_length (`int`, *opcional*) : Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (ver arriba).

return_tensors (`str` o [TensorType](/docs/transformers/v5.23.0/es/internal/file_utils#transformers.TensorType), *opcional*) : Si se establece, devolverá tensores en lugar de listas de enteros de Python. Los valores aceptables son:  - `'pt'`: Devuelve objetos `torch.Tensor` de PyTorch. - `'np'`: Devuelve objetos `np.ndarray` de Numpy.

sampling_rate (`int`, *opcional*) : La tasa de muestreo a la que se muestreó la entrada de `audio`. Se recomienda encarecidamente pasar `sampling_rate` en la llamada forward para evitar errores silenciosos.

Método principal para extraer características y preparar una o varias secuencias para el modelo.

## EncodecModel[[transformers.EncodecModel]]

#### transformers.EncodecModel[[transformers.EncodecModel]]

```python
transformers.EncodecModel(config: EncodecConfig)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L485)

**Parámetros:**

config ([EncodecConfig](/docs/transformers/v5.23.0/es/model_doc/encodec#transformers.EncodecConfig)) : Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método [from_pretrained()](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

El modelo de códec de audio neuronal EnCodec.

Este modelo hereda de [PreTrainedModel](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel). Consulte la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

#### decode[[transformers.EncodecModel.decode]]

```python
decode(audio_codes: LongTensor, audio_scales: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, last_frame_pad_length: int | None = 0)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L661)

**Parámetros:**

audio_codes (`torch.LongTensor` de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`, *opcional*) : Incrustaciones de códigos discretos calculadas usando `model.encode`.

audio_scales (lista de longitud `nb_frames` de `torch.Tensor` de forma `(batch_size, 1)`, *opcional*) : Factor de escala para cada entrada de `audio_codes`.

padding_mask (`torch.Tensor` de forma `(channels, sequence_length)`) : Máscara de relleno utilizada para rellenar `input_values`.

return_dict (`bool`, *opcional*) : Indica si se debe devolver un [ModelOutput](/docs/transformers/v5.23.0/es/main_classes/output#transformers.utils.ModelOutput) en lugar de una tupla simple.

last_frame_pad_length (`int`, *opcional*) : Entero que representa la longitud del relleno en el último fotograma, que se elimina durante la decodificación.

Decodifica los fotogramas dados en una forma de onda de audio de salida.

Tenga en cuenta que la salida puede ser un poco más grande que la entrada. En ese caso, se pueden recortar los pasos adicionales al final.

#### encode[[transformers.EncodecModel.encode]]

```python
encode(input_values: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, bandwidth: float | None = None, return_dict: bool | None = None)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L525)

**Parámetros:**

input_values (`torch.Tensor` de forma `(batch_size, channels, sequence_length)`) : Valores flotantes de la forma de onda de audio de entrada.

padding_mask (`torch.Tensor` de forma `(batch_size, channels, sequence_length)`) : Máscara de relleno utilizada para rellenar `input_values`.

bandwidth (`float`, *opcional*) : El ancho de banda objetivo. Debe ser uno de `config.target_bandwidths`. Si es `None`, se utiliza el ancho de banda más pequeño posible. El ancho de banda se representa como una milésima de su valor real, por ejemplo, un ancho de banda de 6 kbps se representa como bandwidth == 6.0

**Devuelve:** `EncodecEncoderOutput dict or a tuple containing`

- audio_codes (`torch.LongTensor` de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`, *opcional*),
- audio_scales (lista de longitud `nb_frames` de `torch.Tensor` de forma `(batch_size, 1)`, *opcional*),
- last_frame_pad_length (`int`, *opcional*).

Codifica la forma de onda de audio de entrada en códigos discretos de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`.

- `nb_frames=1` si `self.config.chunk_length=None` (ya que el codificador se aplica al audio completo), que es
caso del modelo de 24 kHz. En caso contrario, `nb_frames=ceil(input_length/self.config.chunk_stride)`, que es el caso del modelo de 48 kHz.
- `frame_len` es la longitud de cada cuadro, que es igual a `ceil(input_length/self.config.hop_length)` si
`self.config.chunk_length=None` (p. ej., para el modelo de 24 kHz). En caso contrario, si `self.config.chunk_length` está definido, `frame_len=self.config.chunk_length/self.config.hop_length`, por ejemplo, el caso del modelo de 48 kHz con `frame_len=150`.

#### forward[[transformers.EncodecModel.forward]]

```python
forward(input_values: Tensor, padding_mask: typing.Optional[torch.BoolTensor] = None, bandwidth: float | None = None, audio_codes: typing.Optional[torch.LongTensor] = None, audio_scales: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, last_frame_pad_length: int | None = 0)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/encodec/modeling_encodec.py#L716)

**Parámetros:**

input_values (`torch.Tensor` de forma `(batch_size, channels, sequence_length)`, *opcional*) : Entrada de audio sin procesar convertida a Float y rellena hasta la longitud adecuada para ser codificada usando bloques de longitud self.chunk_length y un desplazamiento de `config.chunk_stride`.

padding_mask (`torch.BoolTensor` de forma `(batch_size, channels, sequence_length)`, *opcional*) : Máscara para evitar el cálculo de factores de escalado en los índices de tokens de relleno (¿podemos evitar el cálculo de conv en estos+?). Valores de la máscara seleccionados en `[0, 1]`:  - 1 para tokens que **no están enmascarados**, - 0 para tokens que **están enmascarados**.    `padding_mask` debe pasarse siempre, a menos que la entrada haya sido truncada o no tenga relleno. Esto se debe a que, para procesar los tensores de manera efectiva, la entrada de audio debe rellenarse de modo que `input_length % stride = step` con `step = chunk_length-stride`. Esto garantiza que todos los fragmentos tengan la misma forma

bandwidth (`float`, *opcional*) : El ancho de banda objetivo. Debe ser uno de `config.target_bandwidths`. Si es `None`, se utiliza el ancho de banda más pequeño posible. El ancho de banda se representa como una milésima de su valor real, por ejemplo, un ancho de banda de 6 kbps se representa como `bandwidth == 6.0`

audio_codes (`torch.LongTensor` de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`, *opcional*) : Incrustaciones de códigos discretos calculadas usando `model.encode`.

audio_scales (`list` de longitud `nb_frames` de `torch.Tensor` de forma `(batch_size, 1)`, *opcional*) : Factor de escala para cada entrada de `audio_codes`.

return_dict (`bool`, *opcional*) : Indica si se deben devolver las salidas como un diccionario.

last_frame_pad_length (`int`, *opcional*) : La longitud del relleno en el último fotograma, si lo hay. Esto se utiliza para garantizar que los fotogramas codificados puedan emitirse como un tensor. Este valor debe pasarse durante la decodificación para asegurarse de que se elimine el relleno de los fotogramas codificados.

**Devuelve:** `EncodecOutput` o `tuple(torch.Tensor)`

Un `EncodecOutput` o una tupla de `torch.Tensor` (si se pasa `return_dict=False` o cuando `config.return_dict=False`) que comprende varios elementos según la configuración ([EncodecConfig](/docs/transformers/v5.23.0/es/model_doc/encodec#transformers.EncodecConfig)) y las entradas.

El método forward de [EncodecModel](/docs/transformers/v5.23.0/es/model_doc/encodec#transformers.EncodecModel) reemplaza el método especial `__call__`.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

- **audio_codes** (`torch.LongTensor` de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`, *opcional*) -- Incrustaciones de códigos discretos calculadas con `model.encode`.
- **audio_values** (`torch.Tensor` de forma `(batch_size, segment_length)`, *opcional*) -- Valores de audio decodificados, obtenidos mediante la parte decodificadora de Encodec.

Ejemplos:

```python
>>> from datasets import load_dataset
>>> from transformers import AutoProcessor, EncodecModel

>>> dataset = load_dataset("hf-internal-testing/ashraq-esc50-1-dog-example")
>>> audio_sample = dataset["train"]["audio"][0]["array"]

>>> model_id = "facebook/encodec_24khz"
>>> model = EncodecModel.from_pretrained(model_id)
>>> processor = AutoProcessor.from_pretrained(model_id)

>>> inputs = processor(raw_audio=audio_sample, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values
```

