# EnCodec

## Visão geral

O modelo de codec neural EnCodec foi proposto em [High Fidelity Neural Audio Compression](https://huggingface.co/papers/2210.13438) por Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

O resumo do artigo é o seguinte:

*Apresentamos um codec de áudio em tempo real, de alta fidelidade e estado da arte, que utiliza redes neurais. Ele consiste em uma arquitetura de codificador-decodificador em streaming com espaço latente quantizado, treinada de forma ponta a ponta. Simplificamos e aceleramos o treinamento ao usar um único adversário de espectrograma multiescala, que reduz eficientemente artefatos e produz amostras de alta qualidade. Introduzimos um mecanismo inovador de balanceamento de perdas para estabilizar o treinamento: o peso de uma perda agora define a fração do gradiente total que ela deve representar, desacoplando assim a escolha desse hiperparâmetro da escala típica da perda. Por fim, estudamos como modelos Transformer leves podem ser usados para comprimir ainda mais a representação obtida em até 40%, mantendo-se mais rápido que o tempo real. Fornecemos uma descrição detalhada das principais escolhas de design do modelo proposto, incluindo: objetivo de treinamento, alterações arquitetônicas e um estudo de diversas funções de perda perceptual. Apresentamos uma avaliação subjetiva extensa (testes MUSHRA) juntamente com um estudo de ablação para uma faixa de larguras de banda e domínios de áudio, incluindo fala, fala com ruído e reverberação, e música. Nossa abordagem é superior aos métodos de referência em todos os cenários avaliados, considerando tanto áudio monofônico de 24 kHz quanto estéreo de 48 kHz.*

Este modelo foi contribuído por [Matthijs](https://huggingface.co/Matthijs), [Patrick Von Platen](https://huggingface.co/patrickvonplaten) e [Arthur Zucker](https://huggingface.co/ArthurZ). O código original pode ser encontrado [aqui](https://github.com/facebookresearch/encodec).

## Exemplo de uso

Aqui está um exemplo rápido de como codificar e decodificar um áudio usando 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)
```

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

**Parâmetros:**

target_bandwidths (`list[float]`, *opcional*, padrão `[1.5, 3.0, 6.0, 12.0, 24.0]`) : A faixa de diferentes larguras de banda com as quais o modelo pode codificar o áudio.

sampling_rate (`int`, *opcional*, padrão `24000`) : A taxa de amostragem na qual os arquivos de áudio devem ser digitalizados, expressa em hertz (Hz).

audio_channels (`int`, *opcional*, padrão `1`) : O número de canais de entrada.

normalize (`bool`, *opcional*, padrão `False`) : Se o áudio deve ser normalizado quando for passado.

chunk_length_s (`float`, *opcional*) : Se definido, o áudio é pré-processado em blocos de comprimento `chunk_length_s` e, em seguida, codificado.

overlap (`float`, *opcional*) : Define a sobreposição entre cada bloco. É usado para calcular o `chunk_stride` usando a seguinte fórmula: `int((1.0 - self.overlap) * self.chunk_length)`.

hidden_size (`int`, *opcional*, padrão `128`) : Dimensão das representações ocultas.

num_filters (`int`, *opcional*, padrão 32) : Número de núcleos de convolução da primeira camada de downsampling `EncodecConv1d`.

num_residual_layers (`int`,  *opcional*, padrão 1) : Número de camadas residuais.

upsampling_ratios (`Sequence[int]` , *opcional*, padrão `[8, 5, 4, 2]`) : Razões de tamanho e passo do kernel. O codificador usa razões de downsampling em vez de razões de upsampling, portanto, ele usará as razões na ordem inversa àquelas especificadas aqui, que devem corresponder à ordem do decodificador.

norm_type (`str`, *opcional*, padrão `"weight_norm"`) : Método de normalização. Deve estar em `["weight_norm", "time_group_norm"]`

kernel_size (`int`, *opcional*, padrão 7) : Tamanho do kernel para a convolução inicial.

last_kernel_size (`int`, *opcional*, padrão 7) : Tamanho do kernel para a última camada de convolução.

residual_kernel_size (`int`, *opcional*, padrão 3) : Tamanho do kernel para as camadas residuais.

dilation_growth_rate (`int`, *opcional*, padrão 2) : Quanto aumentar a dilatação em cada camada.

use_causal_conv (`bool`, *opcional*, padrão `True`) : Se deve usar convolução totalmente causal.

pad_mode (`str`, *opcional*, padrão `"reflect"`) : Modo de preenchimento para as convoluções.

compress (`int`, *opcional*, padrão 2) : Dimensionalidade reduzida nos ramos residuais (do Demucs v3).

num_lstm_layers (`int`, *opcional*, padrão 2) : Número de camadas LSTM no final do codificador.

trim_right_ratio (`float`, *opcional*, padrão 1.0) : Proporção para o recorte à direita da convolução transposta na configuração `use_causal_conv = True`. Se for igual a 1.0, significa que todo o recorte é feito à direita.

codebook_size (`int`, *opcional*, padrão `1024`) : O número de codebooks paralelos usados pelo modelo.

codebook_dim (`int`, *opcional*) : Dimensionalidade de cada vetor de incorporação do codebook.

use_conv_shortcut (`bool`, *opcional*, padrão `True`) : Se deve usar uma camada convolucional como a conexão 'skip' no bloco `EncodecResnetBlock`. Se False, uma função identidade será usada, resultando em uma conexão residual genérica.

Esta é a classe de configuração para armazenar a configuração de um EncodecModel. Ela é usada para instanciar um modelo Encodec de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

Exemplo:

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

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

**Parâmetros:**

feature_size (`int`, *opcional*, padrão 1) : A dimensão dos recursos dos recursos extraídos. Use 1 para mono, 2 para estéreo.

sampling_rate (`int`, *opcional*, padrão 24000) : A taxa de amostragem na qual a forma de onda de áudio deve ser digitalizada, expressa em hertz (Hz).

padding_value (`float`, *opcional*, padrão 0.0) : O valor usado para preencher os valores de padding.

chunk_length_s (`float`, *opcional*) : Se definido, o áudio é pré-processado em blocos de comprimento `chunk_length_s` e, em seguida, codificado.

overlap (`float`, *opcional*) : Define a sobreposição entre cada bloco. É usado para calcular o `chunk_stride` usando a seguinte fórmula: `int((1.0 - self.overlap) * self.chunk_length)`.

Constrói um extrator de recursos EnCodec.

Este extrator de características herda de [SequenceFeatureExtractor](/docs/transformers/main/pt/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), que contém a maioria dos métodos principais. Os usuários devem consultar esta superclasse para obter mais informações sobre esses métodos.

A instanciação de um extrator de recursos com os padrões resultará em uma configuração semelhante à da arquitetura [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz).

#### __call__[[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)
```

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

**Parâmetros:**

raw_audio (`np.ndarray`, `list[float]`, `list[np.ndarray]`, `list[list[float]]`) : A sequência ou lote de sequências a serem processadas. Cada sequência pode ser um array numpy, uma lista de valores float, uma lista de arrays numpy ou uma lista de listas de valores float. O array numpy deve ter a forma `(num_samples,)` para áudio mono (`feature_size = 1`) ou `(2, num_samples)` para áudio estéreo (`feature_size = 2`).

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/pt/internal/file_utils#transformers.utils.PaddingStrategy), *opcional*, padrão `True`) : Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:  - `True` ou `'longest'`: Aplica padding até a sequência mais longa do lote (ou não aplica padding se apenas uma sequência for fornecida). - `'max_length'`: Aplica padding até um comprimento máximo especificado com o argumento `max_length` ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido. - `False` ou `'do_not_pad'` (padrão): Sem padding (ou seja, pode retornar um lote com sequências de comprimentos diferentes).

truncation (`bool`, *opcional*, padrão `False`) : Ativa a truncagem para cortar sequências de entrada com comprimento maior que `max_length` para `max_length`.

max_length (`int`, *opcional*) : Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).

return_tensors (`str` ou [TensorType](/docs/transformers/main/pt/internal/file_utils#transformers.TensorType), *opcional*) : Se definido, retornará tensores em vez de lista de inteiros do Python. Os valores aceitos são:  - `'pt'`: Retorna objetos `torch.Tensor` do PyTorch. - `'np'`: Retorna objetos `np.ndarray` do Numpy.

sampling_rate (`int`, *opcional*) : A taxa de amostragem na qual a entrada `audio` foi amostrada. É fortemente recomendável passar `sampling_rate` na chamada de forward para evitar erros silenciosos.

Método principal para criar recursos e preparar uma ou várias sequências para o modelo.

## EncodecModel[[transformers.EncodecModel]]

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

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

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

**Parâmetros:**

config ([EncodecConfig](/docs/transformers/main/pt/model_doc/encodec#transformers.EncodecConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

O modelo de codec neural de áudio EnCodec.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

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

[Origem](https://github.com/huggingface/transformers/blob/main/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*) : Embebedings de códigos discretos calculados usando `model.encode`.

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

padding_mask (`torch.Tensor` de forma `(channels, sequence_length)`) : Máscara de preenchimento usada para preencher o `input_values`.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

last_frame_pad_length (`int`, *opcional*) : Inteiro que representa o comprimento do padding no último frame, que é removido durante a decodificação.

Decodifica os quadros fornecidos em uma forma de onda de áudio de saída.

Observe que a saída pode ser um pouco maior que a entrada. Nesse caso, quaisquer etapas extras no final podem ser removidas.

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

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

**Parâmetros:**

input_values (`torch.Tensor` de forma `(batch_size, channels, sequence_length)`) : Valores em ponto flutuante da forma de onda de áudio de entrada.

padding_mask (`torch.Tensor` de forma `(batch_size, channels, sequence_length)`) : Máscara de preenchimento usada para preencher o `input_values`.

bandwidth (`float`, *opcional*) : A largura de banda alvo. Deve ser um dos valores de `config.target_bandwidths`. Se for `None`, usa a menor largura de banda possível. A largura de banda é representada como um milésimo do valor real, por exemplo, uma largura de banda de 6kbps é representada como bandwidth == 6.0

**Retorna:** `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 comprimento `nb_frames` de `torch.Tensor` de forma `(batch_size, 1)`, *opcional*),
- last_frame_pad_length (`int`, *opcional*).

Codifica a forma de onda de áudio de entrada em códigos discretos de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`.

- `nb_frames=1` se `self.config.chunk_length=None` (como o codificador é aplicado no áudio completo), o que é
caso do modelo de 24 kHz. Caso contrário, `nb_frames=ceil(input_length/self.config.chunk_stride)`, que é o caso do modelo de 48 kHz.
- `frame_len` é o comprimento de cada quadro, que é igual a `ceil(input_length/self.config.hop_length)` se
`self.config.chunk_length=None` (por exemplo, para o modelo de 24 kHz). Caso contrário, se `self.config.chunk_length` estiver definido, `frame_len=self.config.chunk_length/self.config.hop_length`, por exemplo, o caso do modelo de 48 kHz com `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)
```

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

**Parâmetros:**

input_values (`torch.Tensor` de forma `(batch_size, channels, sequence_length)`, *opcional*) : Entrada de áudio bruto convertida para Float e preenchida até o comprimento adequado para ser codificada usando blocos de comprimento self.chunk_length e um passo de `config.chunk_stride`.

padding_mask (`torch.BoolTensor` de forma `(batch_size, channels, sequence_length)`, *opcional*) : Máscara para evitar o cálculo de fatores de escala nos índices de tokens de preenchimento (podemos evitar o cálculo de conv nesses+). Valores da máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.    `padding_mask` deve ser sempre passado, a menos que a entrada tenha sido truncada ou não tenha sido preenchida. Isso porque, para processar os tensores de forma eficaz, o áudio de entrada deve ser preenchido para que `input_length % stride = step` com `step = chunk_length-stride`. Isso garante que todos os chunks tenham a mesma forma

bandwidth (`float`, *opcional*) : A largura de banda de destino. Deve ser um dos valores de `config.target_bandwidths`. Se for `None`, usa a menor largura de banda possível. A largura de banda é representada como um milésimo do valor real, por exemplo, uma largura de banda de 6kbps é representada como `bandwidth == 6.0`

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

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

return_dict (`bool`, *opcional*) : Se deve retornar as saídas como um dicionário.

last_frame_pad_length (`int`, *opcional*) : O comprimento do padding no último frame, se houver. Isso é usado para garantir que os frames codificados possam ser saídos como um tensor. Esse valor deve ser passado durante a decodificação para garantir que o padding seja removido dos frames codificados.

**Retorna:** `EncodecOutput` ou `tuple(torch.Tensor)`

Um `EncodecOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([EncodecConfig](/docs/transformers/main/pt/model_doc/encodec#transformers.EncodecConfig)) e das entradas.

O método forward do [EncodecModel](/docs/transformers/main/pt/model_doc/encodec#transformers.EncodecModel) substitui o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **audio_codes** (`torch.LongTensor` de forma `(nb_frames, batch_size, nb_quantizers, frame_len)`, *opcional*) -- Embebidings de códigos discretos calculados usando `model.encode`.
- **audio_values** (`torch.Tensor` de forma `(batch_size, segment_length)`, *opcional*) -- Valores de áudio decodificados, obtidos usando a parte decodificadora do Encodec.

Exemplos:

```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
```