# EnCodec

## Aperçu

Le modèle de codec neuronal EnCodec a été proposé dans [High Fidelity Neural Audio Compression](https://huggingface.co/papers/2210.13438) par Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

L'abstract de l'article est le suivant :

*Nous présentons un codec audio en temps réel, haute fidélité et de pointe, exploitant des réseaux de neurones. Il repose sur une architecture encodeur-décodeur en flux avec un espace latent quantifié, entraînée de manière bout en bout. Nous simplifions et accélérons l’entraînement en utilisant un seul adversaire multispectrogramme qui réduit efficacement les artefacts et produit des échantillons de haute qualité. Nous introduisons un mécanisme de rééquilibrage des pertes novateur pour stabiliser l’entraînement : le poids d’une perte définit désormais la fraction du gradient global qu’elle doit représenter, découplant ainsi le choix de ce hyperparamètre de l’échelle typique de la perte. Enfin, nous étudions comment des modèles Transformer légers peuvent être utilisés pour compresser davantage la représentation obtenue, jusqu’à 40 %, tout en restant plus rapide que le temps réel. Nous fournissons une description détaillée des choix de conception clés du modèle proposé, notamment : l’objectif d’entraînement, les modifications architecturales et une étude de diverses fonctions de perte perceptuelle. Nous présentons une évaluation subjective exhaustive (tests MUSHRA) ainsi qu’une étude d’ablation pour une gamme de bandes passantes et de domaines audio, incluant la parole, la parole bruyante et réverbérée, et la musique. Notre approche surpasse les méthodes de référence dans tous les paramètres évalués, en considérant à la fois l’audio monophonique à 24 kHz et l’audio stéréophonique à 48 kHz.*

Ce modèle a été contribué par [Matthijs](https://huggingface.co/Matthijs), [Patrick Von Platen](https://huggingface.co/patrickvonplaten) et [Arthur Zucker](https://huggingface.co/ArthurZ). Le code d'origine peut être trouvé [ici](https://github.com/facebookresearch/encodec).

## Exemple d'utilisation

Voici un exemple rapide de l’encodage et du décodage d’un audio à l’aide de ce modèle :

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

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

**Paramètres :**

target_bandwidths (`list[float]`, *facultatif*, par défaut `[1.5, 3.0, 6.0, 12.0, 24.0]`) : La plage des différentes largeurs de bande avec lesquelles le modèle peut encoder l'audio.

sampling_rate (`int`, *facultatif*, valeur par défaut `24000`) : Le taux d'échantillonnage auquel les fichiers audio doivent être numérisés, exprimé en hertz (Hz).

audio_channels (`int`, *facultatif*, par défaut `1`) : Le nombre de canaux d'entrée.

normalize (`bool`, *facultatif*, par défaut `False`) : Indique si l'audio doit être normalisé lors de son passage.

chunk_length_s (`float`, *facultatif*) : Si défini, l'audio est prétraité en segments de longueur `chunk_length_s` puis encodé.

overlap (`float`, *facultatif*) : Définit le chevauchement entre chaque bloc. Il est utilisé pour calculer le `chunk_stride` à l'aide de la formule suivante : `int((1.0 - self.overlap) * self.chunk_length)`.

hidden_size (`int`, *facultatif*, par défaut `128`) : Dimension des représentations cachées.

num_filters (`int`, *facultatif*, valeur par défaut 32) : Nombre de noyaux de convolution de la première couche de sous-échantillonnage `EncodecConv1d`.

num_residual_layers (`int`,  *facultatif*, par défaut 1) : Nombre de couches résiduelles.

upsampling_ratios (`Sequence[int]` , *facultatif*, valeur par défaut `[8, 5, 4, 2]`) : Ratios de taille et de pas du noyau. L'encodeur utilise des ratios de sous-échantillonnage au lieu de ratios de sur-échantillonnage, il utilisera donc les ratios dans l'ordre inverse de ceux spécifiés ici, qui doivent correspondre à l'ordre du décodeur.

norm_type (`str`, *facultatif*, par défaut `"weight_norm"`) : Méthode de normalisation. Doit être dans `["weight_norm", "time_group_norm"]`

kernel_size (`int`, *facultatif*, valeur par défaut : 7) : Taille du noyau pour la convolution initiale.

last_kernel_size (`int`, *facultatif*, valeur par défaut : 7) : Taille du noyau pour la dernière couche de convolution.

residual_kernel_size (`int`, *facultatif*, valeur par défaut 3) : Taille du noyau pour les couches résiduelles.

dilation_growth_rate (`int`, *facultatif*, valeur par défaut 2) : Amplitude de l'augmentation de la dilatation à chaque couche.

use_causal_conv (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut utiliser une convolution entièrement causale.

pad_mode (`str`, *facultatif*, par défaut `"reflect"`) : Mode de bourrage pour les convolutions.

compress (`int`, *facultatif*, valeur par défaut : 2) : Dimension réduite dans les branches résiduelles (démarrant de Demucs v3).

num_lstm_layers (`int`, *facultatif*, valeur par défaut : 2) : Nombre de couches LSTM à la fin de l'encodeur.

trim_right_ratio (`float`, *facultatif*, valeur par défaut 1.0) : Ratio de rognage à droite de la convolution transposée dans la configuration `use_causal_conv = True`. S'il est égal à 1.0, cela signifie que tout le rognage est effectué à droite.

codebook_size (`int`, *facultatif*, valeur par défaut `1024`) : Le nombre de codebooks parallèles utilisés par le modèle.

codebook_dim (`int`, *facultatif*) : Dimension de chaque vecteur d'incorporation du codebook.

use_conv_shortcut (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut utiliser une couche convolutive comme connexion « skip » dans le bloc `EncodecResnetBlock`. Si la valeur est False, une fonction identité est utilisée, ce qui donne une connexion résiduelle générique.

Ceci est la classe de configuration destinée à stocker la configuration d'un EncodecModel. Elle est utilisée pour instancier un modèle Encodec en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/main/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

feature_size (`int`, *facultatif*, valeur par défaut : 1) : La dimension des caractéristiques des fonctionnalités extraites. Utilisez 1 pour le mono et 2 pour le stéréo.

sampling_rate (`int`, *facultatif*, valeur par défaut 24000) : Le taux d'échantillonnage auquel la forme d'onde audio doit être numérisée, exprimé en hertz (Hz).

padding_value (`float`, *facultatif*, valeur par défaut 0.0) : La valeur utilisée pour remplir les valeurs de bourrage.

chunk_length_s (`float`, *facultatif*) : Si défini, l'audio est prétraité en segments de longueur `chunk_length_s` puis encodé.

overlap (`float`, *facultatif*) : Définit le chevauchement entre chaque bloc. Il est utilisé pour calculer le `chunk_stride` à l'aide de la formule suivante : `int((1.0 - self.overlap) * self.chunk_length)`.

Construit un extracteur de fonctionnalités EnCodec.

Cet extracteur de caractéristiques hérite de [SequenceFeatureExtractor](/docs/transformers/main/fr/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), qui contient la plupart des méthodes principales. Les utilisateurs doivent se reporter à cette superclasse pour plus d'informations sur ces méthodes.

L'instantiation d'un extracteur de caractéristiques avec les valeurs par défaut produira une configuration similaire à celle de l'architecture [facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz).

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

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

**Paramètres :**

raw_audio (`np.ndarray`, `list[float]`, `list[np.ndarray]`, `list[list[float]]`) : La séquence ou le lot de séquences à traiter. Chaque séquence peut être un tableau numpy, une liste de valeurs flottantes, une liste de tableaux numpy ou une liste de listes de valeurs flottantes. Le tableau numpy doit avoir la forme `(num_samples,)` pour l'audio mono (`feature_size = 1`), ou `(2, num_samples)` pour l'audio stéréo (`feature_size = 2`).

padding (`bool`, `str` ou [PaddingStrategy](/docs/transformers/main/fr/internal/file_utils#transformers.utils.PaddingStrategy), *facultatif*, valeur par défaut `True`) : Sélectionne une stratégie pour mettre en place le padding des séquences renvoyées (selon le côté de padding et l'index de padding du modèle) parmi :  - `True` ou `'longest'` : Padding jusqu'à la séquence la plus longue du lot (ou aucun padding si une seule séquence est fournie). - `'max_length'` : Padding jusqu'à une longueur maximale spécifiée avec l'argument `max_length` ou jusqu'à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni. - `False` ou `'do_not_pad'` (par défaut) : Aucun padding (c'est-à-dire, peut renvoyer un lot avec des séquences de longueurs différentes).

truncation (`bool`, *facultatif*, valeur par défaut `False`) : Active la troncature pour couper les séquences d'entrée plus longues que `max_length` à `max_length`.

max_length (`int`, *facultatif*) : Longueur maximale de la liste renvoyée et, le cas échéant, longueur du bourrage (voir ci-dessus).

return_tensors (`str` ou [TensorType](/docs/transformers/main/fr/internal/file_utils#transformers.TensorType), *facultatif*) : Si défini, renverra des tenseurs au lieu d'une liste d'entiers Python. Les valeurs acceptables sont :  - `'pt'` : Renvoie des objets `torch.Tensor` de PyTorch. - `'np'` : Renvoie des objets `np.ndarray` de Numpy.

sampling_rate (`int`, *facultatif*) : Le taux d'échantillonnage auquel l'entrée `audio` a été échantillonnée. Il est fortement recommandé de passer `sampling_rate` lors de l'appel forward afin d'éviter les erreurs silencieuses.

Méthode principale pour vectoriser et préparer une ou plusieurs séquences pour le modèle.

## EncodecModel[[transformers.EncodecModel]]

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

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

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

**Paramètres :**

config ([EncodecConfig](/docs/transformers/main/fr/model_doc/encodec#transformers.EncodecConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle de codec audio neuronal EnCodec.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/main/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

**Paramètres :**

audio_codes (`torch.LongTensor` de forme `(nb_frames, batch_size, nb_quantizers, frame_len)`, *facultatif*) : Incrustations de codes discrets calculées à l'aide de `model.encode`.

audio_scales (liste de longueur `nb_frames` de `torch.Tensor` de forme `(batch_size, 1)`, *facultatif*) : Facteur d'échelle pour chaque entrée `audio_codes`.

padding_mask (`torch.Tensor` de forme `(channels, sequence_length)`) : Masque de bourrage utilisé pour bourrer les `input_values`.

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/main/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

last_frame_pad_length (`int`, *facultatif*) : Entier représentant la longueur du bourrage dans la dernière image, qui est supprimé lors du décodage.

Décode les images données en une forme d'onde audio de sortie.

Notez que la sortie peut être légèrement plus grande que l’entrée. Dans ce cas, les étapes supplémentaires à la fin peuvent être supprimées.

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

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

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, channels, sequence_length)`) : Valeurs flottantes de la forme d'onde audio d'entrée.

padding_mask (`torch.Tensor` de forme `(batch_size, channels, sequence_length)`) : Masque de bourrage utilisé pour bourrer `input_values`.

bandwidth (`float`, *facultatif*) : La bande passante cible. Doit être l'une des valeurs de `config.target_bandwidths`. Si `None`, utilise la bande passante la plus petite possible. La bande passante est représentée en millièmes de sa valeur réelle, par exemple, une bande passante de 6 kbps est représentée par bandwidth == 6.0

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

- audio_codes (`torch.LongTensor` de forme `(nb_frames, batch_size, nb_quantizers, frame_len)`, *facultatif*),
- audio_scales (liste de longueur `nb_frames` de `torch.Tensor` de forme `(batch_size, 1)`, *facultatif*),
- last_frame_pad_length (`int`, *facultatif*).

Encode la forme d'onde audio d'entrée en codes discrets de forme `(nb_frames, batch_size, nb_quantizers, frame_len)`.

- `nb_frames=1` si `self.config.chunk_length=None` (l'encodeur étant appliqué sur l'audio complet), ce qui est
cas du modèle 24 kHz. Sinon, `nb_frames=ceil(input_length/self.config.chunk_stride)`, ce qui est le cas du modèle 48 kHz.
- `frame_len` est la longueur de chaque trame, qui est égale à `ceil(input_length/self.config.hop_length)` si
`self.config.chunk_length=None` (par exemple, pour le modèle 24 kHz). Sinon, si `self.config.chunk_length` est défini, `frame_len=self.config.chunk_length/self.config.hop_length`, par exemple le cas du modèle 48 kHz avec `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)
```

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

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, channels, sequence_length)`, *facultatif*) : Entrée audio brute convertie en Float et complétée à la longueur appropriée afin d'être encodée à l'aide de blocs de longueur self.chunk_length et d'un pas de `config.chunk_stride`.

padding_mask (`torch.BoolTensor` de forme `(batch_size, channels, sequence_length)`, *facultatif*) : Masque pour éviter de calculer les facteurs d'échelle sur les indices des jetons de bourrage (peut-on éviter de calculer la convolution sur ces jetons ?). Les valeurs du masque sont sélectionnées dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. `padding_mask` doit toujours être transmis, sauf si l'entrée a été tronquée ou n'a pas été bourrée. En effet, afin de traiter les tenseurs efficacement, l'audio d'entrée doit être bourré de sorte que `input_length % stride = step` avec `step = chunk_length-stride`. Cela garantit que tous les segments ont la même forme

bandwidth (`float`, *facultatif*) : La bande passante cible. Doit être l'une des valeurs de `config.target_bandwidths`. Si `None`, utilise la bande passante la plus petite possible. La bande passante est représentée en millièmes de sa valeur réelle, par exemple, une bande passante de 6 kbps est représentée par `bandwidth == 6.0`

audio_codes (`torch.LongTensor` de forme `(nb_frames, batch_size, nb_quantizers, frame_len)`, *facultatif*) : Incrustations de codes discrets calculées à l'aide de `model.encode`.

audio_scales (`list` de longueur `nb_frames` de `torch.Tensor` de forme `(batch_size, 1)`, *facultatif*) : Facteur d'échelle pour chaque entrée `audio_codes`.

return_dict (`bool`, *facultatif*) : Indique s'il faut renvoyer les sorties sous forme de dictionnaire.

last_frame_pad_length (`int`, *facultatif*) : La longueur du bourrage dans la dernière image, le cas échéant. Cette valeur est utilisée pour garantir que les images encodées peuvent être sorties sous forme de tenseur. Elle doit être transmise lors du décodage afin de s'assurer que le bourrage est retiré des images encodées.

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

Un `EncodecOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([EncodecConfig](/docs/transformers/main/fr/model_doc/encodec#transformers.EncodecConfig)) et les entrées.

La méthode forward du modèle [EncodecModel](/docs/transformers/main/fr/model_doc/encodec#transformers.EncodecModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **audio_codes** (`torch.LongTensor` de forme `(nb_frames, batch_size, nb_quantizers, frame_len)`, *facultatif*) -- Incrustations de codes discrets calculées à l'aide de `model.encode`.
- **audio_values** (`torch.Tensor` de forme `(batch_size, segment_length)`, *facultatif*) -- Valeurs audio décodées, obtenues à l'aide de la partie décodeur d'Encodec.

Exemples :

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