# X-Codec

## Aperçu

Le modèle X-Codec a été proposé dans [Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model](https://huggingface.co/papers/2408.17175) par Zhen Ye, Peiwen Sun, Jiahe Lei, Hongzhan Lin, Xu Tan, Zheqi Dai, Qiuqiang Kong, Jianyi Chen, Jiahao Pan, Qifeng Liu, Yike Guo, Wei Xue.

Le modèle X-Codec est un codec audio neuronal qui intègre des informations sémantiques issues de modèles auto-supervisés (par exemple, HuBERT) en plus des informations acoustiques traditionnelles. Cela permet :

- **Poursuite musicale** : une meilleure modélisation des sémantiques musicales produit des poursuites plus cohérentes.
- **Synthèse texte-son** : X-Codec capture l'alignement sémantique entre les invites texte et l'audio généré.
- **Tokenisation audio tenant compte du sémantique** : X-Codec est utilisé comme tokeniseur audio dans le modèle de génération de chansons à partir de paroles de YuE.

L'abstract de l'article énonce ce qui suit :

*Les récentes avancées en génération audio ont été considérablement portées par les capacités des grands modèles de langage (LLM). Les recherches existantes sur les LLM audio se sont principalement concentrées sur l’amélioration de l’architecture et de l’échelle des modèles de langage audio, ainsi que sur l’exploitation de jeux de données plus volumineux. De manière générale, des codecs acoustiques, tels qu’EnCodec, sont utilisés pour la tokenisation audio. Toutefois, ces codecs ont été initialement conçus pour la compression audio, ce qui peut entraîner des performances sous-optimales dans le contexte des LLM audio. Notre recherche vise à remédier aux limites des codecs actuels pour LLM audio, en particulier leurs difficultés à préserver l’intégrité sémantique de l’audio généré. Par exemple, les méthodes existantes comme VALL-E, qui conditionnent la génération de tokens acoustiques sur des transcriptions textuelles, souffrent souvent d’imprécisions de contenu et de taux d’erreur de mot (WER) élevés en raison d’interprétations sémantiques erronées des tokens acoustiques, ce qui provoque des omissions de mots et des erreurs. Pour surmonter ces problèmes, nous proposons une approche simple mais efficace appelée X-Codec. X-Codec intègre des caractéristiques sémantiques issues d’un encodeur sémantique pré-entraîné avant l’étape de quantification vectorielle résiduelle (RVQ) et introduit une perte de reconstruction sémantique après la RVQ. En renforçant la capacité sémantique du codec, X-Codec réduit considérablement le WER dans les tâches de synthèse vocale et étend ces avantages à des applications non vocales, notamment la génération de musique et de sons. Nos expériences sur les tâches de texte-vers-parole, de continuation musicale et de texte-vers-son démontrent que l’intégration d’informations sémantiques améliore substantiellement les performances globales des modèles de langage en génération audio.*

Fiches de modèle :

- [xcodec-hubert-librispeech](https://huggingface.co/hf-audio/xcodec-hubert-librispeech) (pour la parole)
- [xcodec-wavlm-mls](https://huggingface.co/hf-audio/xcodec-wavlm-mls) (pour la parole)
- [xcodec-wavlm-more-data](https://huggingface.co/hf-audio/xcodec-wavlm-more-data) (pour la parole)
- [xcodec-hubert-general](https://huggingface.co/hf-audio/xcodec-hubert-general) (pour l'audio général)
- [xcodec-hubert-general-balanced](https://huggingface.co/hf-audio/xcodec-hubert-general-balanced) (pour l'audio général)

Ce modèle a été contribué par [Manal El Aidouni](https://huggingface.co/Manel). Le code d'origine peut être trouvé [ici](https://github.com/zhenye234/xcodec) et les points de contrôle d'origine pour les cinq modèles différents [ici](https://github.com/zhenye234/xcodec?tab=readme-ov-file#available-models).

Les démonstrations sont disponibles sur cette [page](https://x-codec-audio.github.io/).

## 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 AutoFeatureExtractor, XcodecModel

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

# load model and feature extractor
model_id = "hf-audio/xcodec-hubert-librispeech"
model = XcodecModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

# load audio sample
dummy_dataset = dummy_dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audio_sample = dummy_dataset[-1]["audio"]["array"]
inputs = feature_extractor(raw_audio=audio_sample, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(model.device)

# encode and decode
encoder_outputs = model.encode(inputs["input_values"])
decoder_outputs = model.decode(encoder_outputs.audio_codes)
audio_values = decoder_outputs.audio_values

# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_values
```

Pour écouter l’audio original et reconstruit, exécutez l’extrait de code ci-dessous, puis ouvrez les fichiers `original.wav` et `reconstruction.wav` générés dans votre lecteur musical pour les comparer.

```python
import soundfile as sf

original = audio_sample
reconstruction = audio_values[0].cpu().detach().numpy()
sampling_rate = feature_extractor.sampling_rate

sf.write("original.wav", original, sampling_rate)
sf.write("reconstruction.wav", reconstruction.T, sampling_rate)
```

## XcodecConfig[[transformers.XcodecConfig]]

#### transformers.XcodecConfig[[transformers.XcodecConfig]]

```python
transformers.XcodecConfig(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[int | float] | tuple[int | float, ...] = (0.5, 1, 1.5, 2, 4), sample_rate: int = 16000, kernel_size: int = 3, channel_ratios: list[int] | tuple[int, ...] = (1, 1), strides: list[int] | tuple[int, ...] = (1, 1), block_dilations: list[int] | tuple[int, ...] = (1, 1), unit_kernel_size: int = 3, codebook_size: int = 1024, codebook_dim: int | None = None, initializer_range: float = 0.02, acoustic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, semantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xcodec/configuration_xcodec.py#L28)

**Paramètres :**

target_bandwidths (`List[float]`, *facultatif*, valeur par défaut `[0.5, 1, 1.5, 2, 4]`) : La plage des différentes largeurs de bande (en kbps) avec lesquelles le modèle peut encoder l'audio.

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

kernel_size (`int`, *facultatif*, par défaut `3`) : La taille du noyau de convolution.

channel_ratios (`List[float]`, *facultatif*, par défaut `[1, 1]`) : Facteurs d'expansion pour le nombre de canaux de sortie dans chaque bloc sémantique.

strides (`List[int]`, *facultatif*, par défaut `[1, 1]`) : Pas pour chaque bloc d'encodeur sémantique.

block_dilations (`List[int]`, *facultatif*, valeur par défaut `[1, 1]`) : Facteurs de dilatation pour les unités résiduelles dans les blocs sémantiques.

unit_kernel_size (`int`, *facultatif*, valeur par défaut : 3) : Taille du noyau à l'intérieur de chaque ResidualUnit des blocs sémantiques.

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.

initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

acoustic_model_config (`Union[Dict, DacConfig]`, *facultatif*) : Une instance de la configuration du modèle acoustique (DAC).

semantic_model_config (`Union[Dict, HubertConfig, WavLMConfig]`, *facultatif*) : Une instance de l'objet de configuration du modèle sémantique (HuBERT).

Ceci est la classe de configuration destinée à stocker la configuration d'un XcodecModel. Elle est utilisée pour instancier un modèle Xcodec 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 [Manel/X-Codec](https://huggingface.co/Manel/X-Codec)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/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/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

```python
>>> from transformers import XcodecModel, XcodecConfig

>>> # Initializing configuration
>>> configuration = XcodecConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = XcodecModel(configuration)

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

## XcodecModel[[transformers.XcodecModel]]

#### transformers.XcodecModel[[transformers.XcodecModel]]

```python
transformers.XcodecModel(config: XcodecConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xcodec/modeling_xcodec.py#L445)

**Paramètres :**

config ([XcodecConfig](/docs/transformers/v5.23.0/fr/model_doc/xcodec#transformers.XcodecConfig)) : 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/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle de codec audio neuronal Xcodec.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/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.XcodecModel.decode]]

```python
decode(audio_codes: Tensor, return_dict: bool | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xcodec/modeling_xcodec.py#L541)

**Paramètres :**

audio_codes (`torch.LongTensor` de forme `(batch_size, num_quantizers, codes_length)`) : Indices de codes discrets calculés à l'aide de `model.encode`.

return_dict (`bool`, *facultatif*) : Indique s'il faut ou non retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput)

**Retourne :**

Valeurs audio décodées de forme `(batch_size, channels, num_samples)` obtenues à l'aide de la partie décodeur de Xcodec.

#### encode[[transformers.XcodecModel.encode]]

```python
encode(input_values: Tensor, bandwidth: float | None = None, return_dict: bool | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xcodec/modeling_xcodec.py#L489)

**Paramètres :**

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

bandwidth (`float`, *facultatif*) : La bande passante cible en (kbps) n'accepte que les valeurs définies dans `config.target_bandwidths`. Par défaut, la bande passante maximale disponible, soit `4.0` kbps, est utilisée.

return_dict (`bool`, *facultatif*) : Indique s'il faut renvoyer un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) ou non.

**Retourne :**

`torch.LongTensor` de forme `(batch_size, num_quantizers, codes_length)` contenant les codes audio encodés discrets.

#### forward[[transformers.XcodecModel.forward]]

```python
forward(input_values: Tensor, audio_codes: typing.Optional[torch.Tensor] = None, bandwidth: float | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/xcodec/modeling_xcodec.py#L569)

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, channels, num_samples)`) : Les valeurs flottantes brutes de la forme d'onde audio d'entrée.

audio_codes (`torch.LongTensor` de forme `(batch_size, num_quantizers, codes_length)` : indices de codes discrets calculés à l'aide de `model.encode`.

bandwidth (`float`, *facultatif*) : Bande passante cible en kbps. Doit être l'une des valeurs de `config.target_bandwidths`. Par défaut, la bande passante disponible la plus élevée est utilisée.

bandwidth (`float`, *facultatif*) : Bande passante cible en kbps. Doit être l'une des valeurs de `config.target_bandwidths`. Par défaut, la bande passante disponible la plus élevée est utilisée.

**Retourne :** `XcodecOutput` ou le tuple `(audio_codes, audio_values)`

- `audio_codes` de forme `(batch_size, num_quantizers, codes_length)` : les codes discrets quantifiés.
- `audio_values` de forme `(batch_size, channels, num_samples)` : la forme d’onde audio reconstruite à partir des codes.

La méthode forward du modèle [XcodecModel](/docs/transformers/v5.23.0/fr/model_doc/xcodec#transformers.XcodecModel) 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.

Exemple :

```python
>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, XcodecModel

>>> model_id = "hf-audio/xcodec-hubert-librispeech"
>>> model = XcodecModel.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
>>> audio_sample = dataset[0]['audio']['array']

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

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

