# X-Codec2

## Aperçu

Le modèle X-Codec2 a été proposé dans [Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis](https://huggingface.co/papers/2502.04128).

X-Codec2 est un codec audio neuronal conçu pour améliorer la synthèse vocale et la génération audio générale dans les pipelines de grands modèles de langage (LLM). Il étend le X-Codec d'origine en affinant la manière dont les informations sémantiques et acoustiques sont intégrées et tokenisées, permettant ainsi une représentation audio efficace et de haute fidélité.

Concernant son architecture :
- **Tokenisation sémantique-acoustique unifiée** : X-Codec2 fusionne les sorties d'un encodeur sémantique (par ex. Wav2Vec2-BERT) et d'un encodeur acoustique en un unique embedding, capturant à la fois le sens de haut niveau (par ex. contenu textuel, émotion) et les détails audio de bas niveau (par ex. timbre).
- **Quantification scalaire de caractéristiques en une seule étape (FSQ)** : Contrairement à la VQ résiduelle multicouche utilisée dans la plupart des approches (par exemple, [DAC](./dac), [EnCodec](./encodec), [X-Codec](./xcodec), [Mimi](./mimi)), X-Codec2 utilise une seule couche de quantification scalaire de caractéristiques (FSQ) pour assurer la stabilité et la compatibilité avec les LLM causaux et autorégressifs.
- **Conception adaptée aux Transformers** : la structure de jetons 1D de X-Codec2 s'aligne naturellement sur la modélisation autorégressive des LLM comme LLaMA, ce qui améliore l'efficacité de l'entraînement et la compatibilité en aval.

Un point de contrôle du modèle est disponible sur [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf).

Ce modèle a été contribué par [Eric Bezzam](https://huggingface.co/bezzam) et [Steven Zheng](https://huggingface.co/Steveeeeeeen). Le code de modélisation original peut être trouvé [ici](https://huggingface.co/HKUSTAudio/xcodec2/blob/main/modeling_xcodec2.py), tandis que leur code d’entraînement est [ici](https://github.com/zhenye234/X-Codec-2.0).

## 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, AutoModel

model_id = "HKUSTAudio/xcodec2-hf"
model = AutoModel.from_pretrained(model_id, device_map="auto")
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 = dataset[0]["audio"]["array"]
inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(
    model.device, model.dtype
)
print("Input waveform shape:", inputs["input_values"].shape)
# Input waveform shape: torch.Size([1, 1, 93760])

# encoder and decoder
audio_codes = model.encode(**inputs).audio_codes
print("Audio codes shape:", audio_codes.shape)
# Audio codes shape: torch.Size([1, 1, 293])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# Audio values shape: torch.Size([1, 1, 93760])

# Equivalently, you can do encoding and decoding in one step
model_output = model(**inputs)
audio_codes = model_output.audio_codes
audio_values = model_output.audio_values
```

### Traitement par lots

Cette prise en charge également les entrées par lot, contrairement à la [version initiale](https://huggingface.co/HKUSTAudio/xcodec2) !

```python
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 2
model_id = "HKUSTAudio/xcodec2-hf"
model = AutoModel.from_pretrained(model_id, device_map="auto")
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))
audios = [dataset[i]["audio"]["array"] for i in range(batch_size)]
inputs = feature_extractor(audio=audios, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(
    model.device, model.dtype
)
print("Input waveform shape:", inputs["input_values"].shape)
# Input waveform shape: torch.Size([2, 1, 93760])

# encoder and decoder
encoder_output = model.encode(**inputs)
audio_codes = encoder_output.audio_codes
print("Audio codes shape:", audio_codes.shape)
# Audio codes shape: torch.Size([2, 1, 293])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# Audio values shape: torch.Size([2, 1, 93760])

# Equivalently, you can do encoding and decoding in one step
model_output = model(**inputs)
audio_codes = model_output.audio_codes
audio_values = model_output.audio_values
```

### Accélération avec `torch.compile`

Vous pouvez accélérer l'inférence avec [`torch.compile`](https://pytorch.org/docs/stable/generated/torch.compile.html). Les premiers appels seront plus lents en raison du surcoût de compilation, mais les appels suivants seront plus rapides.

Sur une A100, nous avons observé une accélération d'environ 1,35 pour une taille de lot de 4 ([script](https://gist.github.com/ebezzam/3b79481b5d48d8e35c4ecc582aee0cb3#file-benchmark_torch_compile-py)).

```python
import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 4
model_id = "HKUSTAudio/xcodec2-hf"
model = AutoModel.from_pretrained(model_id, device_map="auto")
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))
audios = [dataset[i]["audio"]["array"] for i in range(batch_size)]
inputs = feature_extractor(
    audio=audios, sampling_rate=feature_extractor.sampling_rate, padding=True, return_tensors="pt"
).to(model.device, model.dtype)

compiled_model = torch.compile(model, fullgraph=True)

# Warmup (includes compilation on first call)
for _ in range(10):
    with torch.inference_mode():
        _ = compiled_model(**inputs)

with torch.inference_mode():
    output = compiled_model(**inputs)
print("Audio values shape:", output.audio_values.shape)
```

## Xcodec2Config[[transformers.Xcodec2Config]]

#### transformers.Xcodec2Config[[transformers.Xcodec2Config]]

```python
transformers.Xcodec2Config(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, hidden_size: int = 1024, intermediate_size: int = 4096, num_hidden_layers: int = 12, num_attention_heads: int = 16, num_key_value_heads: int = 16, hidden_act: str = 'silu', max_position_embeddings: int = 4096, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, pad_token_id: int | None = None, tie_word_embeddings: bool = False, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, attention_dropout: int | float | None = 0.0, head_dim: int = 64, encoder_hidden_size: int = 48, downsampling_ratios: list[int] | tuple[int, ...] = (2, 2, 4, 4, 5), semantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, sampling_rate: int = 16000, activation_dropout: float = 0.1, quantization_dim: int = 2048, quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4))
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/configuration_xcodec2.py#L33)

**Paramètres :**

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

intermediate_size (`int`, *facultatif*, valeur par défaut `4096`) : Dimension des représentations MLP.

num_hidden_layers (`int`, *facultatif*, par défaut `12`) : Nombre de couches cachées dans le décodeur Transformer.

num_attention_heads (`int`, *facultatif*, valeur par défaut `16`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

num_key_value_heads (`int`, *facultatif*, valeur par défaut `16`) : C'est le nombre de têtes key_value à utiliser pour implémenter l'attention Grouped Query. Si `num_key_value_heads=num_attention_heads`, le modèle utilisera l'attention Multi Head (MHA) ; si `num_key_value_heads=1`, il utilisera l'attention Multi Query (MQA) ; sinon, c'est la GQA qui est utilisée. Lors de la conversion d'un checkpoint multi-têtes vers un checkpoint GQA, chaque tête clé et valeur de groupe doit être construite en effectuant un meanpooling de toutes les têtes d'origine appartenant à ce groupe. Pour plus de détails, consultez [cet article](https://huggingface.co/papers/2305.13245). S'il n'est pas spécifié, la valeur par défaut est `num_attention_heads`.

hidden_act (`str`, *facultatif*, par défaut `silu`) : La fonction d'activation non linéaire (fonction ou chaîne de caractères) dans le décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

max_position_embeddings (`int`, *facultatif*, valeur par défaut `4096`) : La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé.

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.

rms_norm_eps (`float`, *facultatif*, valeur par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation rms.

pad_token_id (`int`, *facultatif*) : Identifiant de jeton utilisé pour le bourrage dans le vocabulaire.

tie_word_embeddings (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut lier les embeddings de poids selon la correspondance `tied_weights_keys` du modèle.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *facultatif*) : Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pour `rope_theta` et, le cas échéant, les paramètres utilisés pour le mise à l'échelle si vous souhaitez utiliser RoPE avec des `max_position_embeddings` plus longs.

attention_bias (`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut utiliser un biais dans les couches de projection de requête, de clé, de valeur et de sortie lors de l'auto-attention.

attention_dropout (`Union[int, float]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout appliqué aux probabilités d'attention.

head_dim (`int`, *facultatif*, par défaut `64`) : La dimension des têtes d'attention. Si None, elle est par défaut égale à hidden_size // num_attention_heads

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

downsampling_ratios (`list[int]`, *facultatif*, par défaut `[2, 2, 4, 4, 5]`) : Ratios de sous-échantillonnage dans l'encodeur.

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

sampling_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).

activation_dropout (`float`, *facultatif*, valeur par défaut `0.1`) : Le taux de dropout pour les activations à l'intérieur de la couche entièrement connectée.

quantization_dim (`int`, *facultatif*, valeur par défaut 2048) : Dimension du codebook de quantification vectorielle.

quantization_levels (`list[int]`, *facultatif*, par défaut `[4, 4, 4, 4, 4, 4, 4, 4]`) : Niveaux du codebook de quantification vectorielle.

Ceci est la classe de configuration destinée à stocker la configuration d'un Xcodec2Model. Elle est utilisée pour instancier un modèle Xcodec2 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 [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf)

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 Xcodec2Config, Xcodec2Model

>>> # Initializing configuration
>>> configuration = Xcodec2Config()

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

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

## Xcodec2FeatureExtractor[[transformers.Xcodec2FeatureExtractor]]

#### transformers.Xcodec2FeatureExtractor[[transformers.Xcodec2FeatureExtractor]]

```python
transformers.Xcodec2FeatureExtractor(feature_size = 80, sampling_rate = 16000, padding_value = 1.0, hop_length = 320, **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/feature_extraction_xcodec2.py#L37)

**Paramètres :**

feature_size (`int`, *facultatif*, valeur par défaut 80) : La dimension des caractéristiques des fonctionnalités extraites.

sampling_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).

padding_value (`float`, *facultatif*, valeur par défaut 1.0) : La valeur utilisée pour remplir les vecteurs de bourrage du spectrogramme mel.

hop_length (`int`, *facultatif*, valeur par défaut : 320) : Nombre d'échantillons audio encodés par trame. Équivaut au produit des ratios de sous-échantillonnage. Requis pour le bourrage de l'entrée de l'encodeur acoustique.

Construit un extracteur de caractéristiques Xcodec2, qui calcule les caractéristiques de la banque de filtres mel pour l'encodeur sémantique et l'audio rembourré pour l'encodeur acoustique.

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.

#### __appel__[[transformers.Xcodec2FeatureExtractor.__call__]]

```python
__call__(audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']], padding: bool | str | transformers.utils.generic.PaddingStrategy = True, max_length: int | None = None, truncation: bool = False, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None, device: str = 'cpu', **kwargs)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/feature_extraction_xcodec2.py#L85)

**Paramètres :**

audio (`np.ndarray`, `torch.Tensor`, `list[np.ndarray]`, `list[torch.Tensor]`) : tableau Numpy ou tenseur torch de forme (num_channels, sequence_length). Une liste de tels tableaux ou tenseurs peut également être fournie pour un lot d'entrées.

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

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

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

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 : - `'tf'` : Renvoie des objets `tf.constant` TensorFlow. - `'pt'` : Renvoie des objets `torch.Tensor` PyTorch. - `'np'` : Renvoie des objets `np.ndarray` 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.

device (`str`, *facultatif*, valeur par défaut `"cpu"`) : Appareil pour les tenseurs PyTorch lors de l'extraction des caractéristiques de la banque de filtres mel.

kwargs (*facultatif*) : Dictionnaire restant des arguments par mot-clé qui seront transmis au tokenizer ou à l'extracteur de caractéristiques.

## Xcodec2Model[[transformers.Xcodec2Model]]

#### transformers.Xcodec2Model[[transformers.Xcodec2Model]]

```python
transformers.Xcodec2Model(config: Xcodec2Config)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/modeling_xcodec2.py#L939)

**Paramètres :**

config ([Xcodec2Config](/docs/transformers/main/fr/model_doc/xcodec2#transformers.Xcodec2Config)) : 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.

Modèle de codec audio neuronal Xcodec2.

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.Xcodec2Model.decode]]

```python
decode(audio_codes: typing.Optional[torch.Tensor] = None, latents: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/modeling_xcodec2.py#L1012)

**Paramètres :**

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

latents (`torch.Tensor` de forme `(batch_size, dimension, time_steps)`, *facultatif*) : Représentation continue quantifiée de l'entrée.

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

Un `Xcodec2DecoderOutput` 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 (`None`) et les entrées.

- **audio_values** (`torch.Tensor` de forme `(batch_size, 1, segment_length)`, *facultatif*) -- Valeurs de la forme d'onde audio décodée dans le domaine temporel, obtenues en convertissant les codes discrets en signaux audio continus. Cela représente l'audio reconstruit qui peut être lu.

#### encode[[transformers.Xcodec2Model.encode]]

```python
encode(input_values: Tensor, input_features: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, output_latents: bool = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/modeling_xcodec2.py#L958)

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, 1, sequence_length)`) : Forme d'onde audio en entrée.

input_features (`torch.Tensor` de forme `(batch_size, mel_bins, time_steps)`) : Spectrogramme mélo de l'audio d'entrée pour l'encodage sémantique.

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

input_features_mask (`torch.Tensor` de forme `(batch_size, time_steps)`, *facultatif*) : Masque d'attention pour l'entrée spectrogramme de l'encodeur sémantique. `1` pour les trames valides, `0` pour le bourrage.

output_latents (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut retourner la représentation latente continue issue du quantiseur.

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

Un `Xcodec2EncoderOutput` 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 (`None`) et les entrées.

- **audio_codes** (`torch.LongTensor` de forme `(batch_size, 1, codes_length)`, *facultatif*) -- Incrustations de codes discrets calculées à l'aide de `model.encode`. Elles représentent la forme compressée et quantifiée du signal audio d'entrée, utilisable pour le stockage, la transmission ou la génération.
- **latents** (`torch.Tensor` de forme `(batch_size, dimension, time_steps)`) -- Représentation continue quantifiée de l'embedding de l'entrée.
- **audio_codes_mask** (`torch.int32` de forme `(batch_size, 1, codes_length)`, *facultatif*) -- `padding_mask` sous-échantillonné indiquant les codes audio valides dans `audio_codes`.

#### forward[[transformers.Xcodec2Model.forward]]

```python
forward(input_values: Tensor, input_features: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, output_latents: bool = False, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec2/modeling_xcodec2.py#L1037)

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, 1, sequence_length)`) : Forme d'onde audio en entrée.

input_features (`torch.Tensor` de forme `(batch_size, mel_bins, time_steps)`) : Spectrogramme mélo de l'audio d'entrée pour l'encodage sémantique.

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

input_features_mask (`torch.Tensor` de forme `(batch_size, time_steps)`, *facultatif*) : Masque d'attention pour l'entrée spectrogramme de l'encodeur sémantique. `1` pour les trames valides, `0` pour le bourrage.

output_latents (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut retourner la représentation latente continue issue du quantiseur.

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

Un `Xcodec2Output` 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 (`None`) et les entrées.

La méthode forward de [Xcodec2Model](/docs/transformers/main/fr/model_doc/xcodec2#transformers.Xcodec2Model) 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_values** (`torch.Tensor` de forme `(batch_size, 1, sequence_length)`, *facultatif*) -- Valeurs de la forme d'onde audio décodée dans le domaine temporel, obtenues à l'aide de la partie décodeur de Xcodec2. Elles représentent le signal audio reconstruit.
- **audio_codes** (`torch.LongTensor` de forme `(batch_size, 1, codes_length)`, *facultatif*) -- Incrustations de codes discrets calculées à l'aide de `model.encode`. Il s'agit des représentations quantifiées de l'audio d'entrée, utilisées pour un traitement ou une génération ultérieurs.
- **latents** (`torch.Tensor` de forme `(batch_size, dimension, time_steps)`) -- Représentation continue quantifiée de l'embedding de l'entrée.
- **audio_codes_mask** (`torch.int32` de forme `(batch_size, 1, codes_length)`, *facultatif*) -- `padding_mask` sous-échantillonné indiquant les codes audio valides dans `audio_codes`.

Exemples :

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

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]

>>> model_id = "HKUSTAudio/xcodec2-hf"
>>> model = Xcodec2Model.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

>>> inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt")

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