# X-Codec2

## Tổng quan

Mô hình X-Codec2 được đề xuất trong [Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis](https://huggingface.co/papers/2502.04128).

X-Codec2 là một codec âm thanh dựa trên mạng nơ-ron, được thiết kế để cải thiện tổng hợp giọng nói và tạo âm thanh nói chung cho các pipeline của mô hình ngôn ngữ lớn (LLM). Nó mở rộng X-Codec gốc bằng cách tinh chỉnh cách tích hợp và mã hóa token thông tin ngữ nghĩa và âm học, cho phép biểu diễn âm thanh hiệu quả và có độ trung thực cao.

Về kiến trúc của nó:
- **Token hóa ngữ nghĩa - âm học thống nhất**: X-Codec2 kết hợp đầu ra từ bộ mã hóa ngữ nghĩa (ví dụ: Wav2Vec2-BERT) và bộ mã hóa âm học thành một vector nhúng duy nhất, nắm bắt cả ý nghĩa cấp cao (ví dụ: nội dung văn bản, cảm xúc) và chi tiết âm thanh cấp thấp (ví dụ: âm sắc).
- **Lượng tử hóa vô hướng đặc trưng một giai đoạn (FSQ)**: Khác với VQ dư thừa nhiều lớp trong hầu hết các phương pháp (ví dụ: [DAC](./dac), [EnCodec](./encodec), [X-Codec](./xcodec), [Mimi](./mimi)), X-Codec2 sử dụng một lớp duy nhất của Lượng tử hóa vô hướng đặc trưng (FSQ) để đảm bảo tính ổn định và khả năng tương thích với các LLM tự hồi quy, nhân quả.
- **Thiết kế thân thiện với Transformer**: Cấu trúc token 1D của X-Codec2 tự nhiên phù hợp với mô hình hóa tự hồi quy trong các LLM như LLaMA, cải thiện hiệu quả huấn luyện và khả năng tương thích cho các tác vụ tiếp theo.

Một checkpoint của mô hình có sẵn tại [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf).

Mô hình này được đóng góp bởi [Eric Bezzam](https://huggingface.co/bezzam) và [Steven Zheng](https://huggingface.co/Steveeeeeeen). Mã mô hình hóa gốc có thể được tìm thấy [tại đây](https://huggingface.co/HKUSTAudio/xcodec2/blob/main/modeling_xcodec2.py), trong khi mã huấn luyện của họ nằm [tại đây](https://github.com/zhenye234/X-Codec-2.0).

## Ví dụ sử dụng 

Dưới đây là một ví dụ nhanh về cách mã hóa và giải mã âm thanh bằng mô hình này:

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

### Xử lý theo lô

Cài đặt này cũng hỗ trợ đầu vào dạng lô (batched input), khác với [bản phát hành](https://huggingface.co/HKUSTAudio/xcodec2) ban đầu!

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

### Tăng tốc với `torch.compile`

Bạn có thể tăng tốc suy luận bằng [`torch.compile`](https://pytorch.org/docs/stable/generated/torch.compile.html). Vài lần gọi đầu tiên sẽ chậm hơn do chi phí biên dịch, nhưng các lần gọi sau đó sẽ nhanh hơn.

Trên A100, chúng tôi quan sát được tốc độ tăng ~1.35 với kích thước lô là 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))
```

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

**Tham số:**

hidden_size (`int`, *tuỳ chọn*, mặc định là `1024`) : Kích thước của các biểu diễn ẩn.

intermediate_size (`int`, *tuỳ chọn*, mặc định là `4096`) : Kích thước của các biểu diễn MLP.

num_hidden_layers (`int`, *tuỳ chọn*, mặc định là `12`) : Số lượng lớp ẩn trong bộ giải mã Transformer.

num_attention_heads (`int`, *tuỳ chọn*, mặc định là `16`) : Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ giải mã Transformer.

num_key_value_heads (`int`, *tuỳ chọn*, mặc định là `16`) : Đây là số lượng đầu key_value cần được sử dụng để triển khai Grouped Query Attention. Nếu `num_key_value_heads=num_attention_heads`, mô hình sẽ sử dụng Multi Head Attention (MHA), nếu `num_key_value_heads=1` mô hình sẽ sử dụng Multi Query Attention (MQA), ngược lại GQA sẽ được sử dụng. Khi chuyển đổi một checkpoint multi-head sang checkpoint GQA, mỗi nhóm đầu key và value nên được xây dựng bằng cách meanpooling tất cả các đầu gốc trong nhóm đó. Để biết thêm chi tiết, hãy xem [bài báo này](https://huggingface.co/papers/2305.13245). Nếu không được chỉ định, giá trị mặc định sẽ là `num_attention_heads`.

hidden_act (`str`, *tùy chọn*, mặc định là `silu`) : Hàm kích hoạt phi tuyến tính (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ, `"gelu"`, `"relu"`, `"silu"`, v.v.

max_position_embeddings (`int`, *tuỳ chọn*, mặc định là `4096`) : Độ dài chuỗi tối đa mà mô hình này có thể được sử dụng.

initializer_range (`float`, *optional*, mặc định là `0.02`) : Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số.

rms_norm_eps (`float`, *tuỳ chọn*, mặc định là `1e-06`) : Epsilon được sử dụng bởi các lớp chuẩn hóa rms.

pad_token_id (`int`, *tùy chọn*) : Id của token được sử dụng để đệm (padding) trong từ vựng.

tie_word_embeddings (`bool`, *tùy chọn*, mặc định là `False`) : Có nên gắn kết các nhúng trọng số theo ánh xạ `tied_weights_keys` của mô hình hay không.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *optional*) : Từ điển chứa các tham số cấu hình cho các embedding RoPE. Từ điển phải chứa một giá trị cho `rope_theta` và tùy chọn các tham số được sử dụng để mở rộng trong trường hợp bạn muốn sử dụng RoPE với `max_position_embeddings` dài hơn.

attention_bias (`bool`, *tùy chọn*, mặc định là `False`) : Có sử dụng bias trong các lớp chiếu query, key, value và output trong quá trình tự chú ý hay không.

attention_dropout (`Union[int, float]`, *tùy chọn*, mặc định là `0.0`) : Tỷ lệ dropout cho các xác suất chú ý.

head_dim (`int`, *tùy chọn*, mặc định là `64`) : Kích thước chiều của đầu chú ý. Nếu là None, giá trị mặc định sẽ là hidden_size // num_attention_heads

encoder_hidden_size (`int`, *optional*, mặc định là `48`) : Kích thước của các biểu diễn ẩn.

downsampling_ratios (`list[int]`, *tuỳ chọn*, mặc định là `[2, 2, 4, 4, 5]`) : Tỷ lệ hạ mẫu trong bộ mã hóa.

semantic_model_config (`Union[Dict, Wav2Vec2BertConfig]`, *tùy chọn*) : Một instance của đối tượng cấu hình cho mô hình ngữ nghĩa (Wav2Vec2BertConfig).

sampling_rate (`int`, *optional*, mặc định là `16000`) : Tốc độ lấy mẫu (sampling rate) mà các tệp âm thanh nên được số hóa, được biểu diễn bằng hertz (Hz).

activation_dropout (`float`, *tuỳ chọn*, mặc định là `0.1`) : Tỷ lệ dropout cho các kích hoạt bên trong lớp liên kết đầy đủ.

quantization_dim (`int`, *optional*, mặc định là 2048) : Kích thước cho codebook của vector quantization.

quantization_levels (`list[int]`, *tuỳ chọn*, mặc định là `[4, 4, 4, 4, 4, 4, 4, 4]`) : Các mức cho codebook lượng tử hóa vector.

Đây là lớp cấu hình để lưu trữ cấu hình của một Xcodec2Model. Nó được sử dụng để khởi tạo một mô hình Xcodec2 theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf)

Các đối tượng cấu hình kế thừa từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ [PreTrainedConfig](/docs/transformers/main/vi/main_classes/configuration#transformers.PreTrainedConfig) để biết thêm thông tin.

Ví dụ:

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

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

**Tham số:**

feature_size (`int`, *tuỳ chọn*, mặc định là 80) : Kích thước chiều của các đặc trưng đã trích xuất.

sampling_rate (`int`, *optional*, mặc định là 16000) : Tần số lấy mẫu (sample rate) mà các tệp âm thanh nên được số hóa, được biểu diễn bằng hertz (Hz).

padding_value (`float`, *tuỳ chọn*, mặc định là 1.0) : Giá trị được sử dụng để điền vào các vector đệm cho phổ mel.

hop_length (`int`, *optional*, mặc định là 320) : Số lượng mẫu âm thanh được mã hóa cho mỗi khung. Tương đương với tích của các tỷ lệ hạ mẫu. Cần thiết để đệm đầu vào cho bộ mã hóa âm học.

Tạo một bộ trích xuất đặc trưng Xcodec2, tính toán các đặc trưng mel-filter bank cho bộ mã hóa ngữ nghĩa và âm thanh đã đệm cho bộ mã hóa âm học.

Feature extractor này kế thừa từ [SequenceFeatureExtractor](/docs/transformers/main/vi/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), bao gồm hầu hết các phương thức chính. Người dùng nên tham khảo lớp cha này để biết thêm thông tin về các phương thức đó.

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

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

**Tham số:**

audio (`np.ndarray`, `torch.Tensor`, `list[np.ndarray]`, `list[torch.Tensor]`) : Mảng Numpy hoặc tensor torch có shape (num_channels, sequence_length). Có thể cung cấp một danh sách các mảng hoặc tensor như vậy cho một batch đầu vào.

padding (`bool`, `str` hoặc [PaddingStrategy](/docs/transformers/main/vi/internal/file_utils#transformers.utils.PaddingStrategy), *tuỳ chọn*, mặc định là `True`) : Chọn một chiến lược để đệm các chuỗi được trả về (theo phía đệm và chỉ số đệm của mô hình) trong số:  - `True` hoặc `'longest'`: Đệm đến chuỗi dài nhất trong lô (hoặc không đệm nếu chỉ có một chuỗi được cung cấp). - `'max_length'`: Đệm đến độ dài tối đa được chỉ định bằng tham số `max_length` hoặc đến độ dài đầu vào tối đa chấp nhận được cho mô hình nếu tham số đó không được cung cấp. - `False` hoặc `'do_not_pad'` (mặc định): Không đệm (tức là có thể xuất ra một lô với các chuỗi có độ dài khác nhau).

max_length (`int`, *optional*) : Độ dài tối đa của danh sách được trả về và tùy chọn độ dài padding (xem bên trên).

truncation (`bool`) : Kích hoạt việc cắt ngắn để giảm các chuỗi đầu vào dài hơn *max_length* xuống còn *max_length*.

return_tensors (`str` hoặc [TensorType](/docs/transformers/main/vi/internal/file_utils#transformers.TensorType), *optional*) : Nếu được đặt, sẽ trả về các tensor thay vì danh sách các số nguyên python. Các giá trị chấp nhận được là:  - `'tf'`: Trả về các đối tượng `tf.constant` của TensorFlow. - `'pt'`: Trả về các đối tượng `torch.Tensor` của PyTorch. - `'np'`: Trả về các đối tượng `np.ndarray` của Numpy.

sampling_rate (`int`, *optional*) : Tần số lấy mẫu mà đầu vào `audio` được lấy mẫu. Rất khuyến nghị truyền `sampling_rate` tại cuộc gọi forward để ngăn các lỗi âm thầm.

device (`str`, *tùy chọn*, mặc định là `"cpu"`) : Thiết bị cho các tensor PyTorch trong quá trình trích xuất đặc trưng mel-filter bank.

kwargs (*tùy chọn*) : Từ điển các đối số từ khóa còn lại sẽ được truyền cho tokenizer hoặc feature extractor.

## Xcodec2Model[[transformers.Xcodec2Model]]

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

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

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

**Tham số:**

config ([Xcodec2Config](/docs/transformers/main/vi/model_doc/xcodec2#transformers.Xcodec2Config)) : Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình sẽ không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức [from_pretrained()](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel.from_pretrained) để tải trọng số mô hình.

Mô hình mã hóa âm thanh neural Xcodec2.

Mô hình này kế thừa từ [PreTrainedModel](/docs/transformers/main/vi/main_classes/model#transformers.PreTrainedModel). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu ra, v.v.)

Mô hình này cũng là một lớp con của [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.

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

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

**Tham số:**

audio_codes (`torch.LongTensor` có hình dạng `(batch_size, 1, codes_length)`) : Các chỉ số mã rời rạc được tính toán bằng `model.encode`.

latents (`torch.Tensor` có hình dạng `(batch_size, dimension, time_steps)`, *tùy chọn*) : Đại diện liên tục đã lượng tử hóa của đầu vào.

**Trả về:** `Xcodec2DecoderOutput` hoặc `tuple(torch.Tensor)`

Một `Xcodec2DecoderOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình (`None`) và đầu vào.

- **audio_values** (`torch.Tensor` có hình dạng `(batch_size, 1, segment_length)`, *tùy chọn*) -- Các giá trị dạng sóng âm thanh đã giải mã trong miền thời gian, thu được bằng cách chuyển đổi các mã rời rạc trở lại thành tín hiệu âm thanh liên tục. Đây là âm thanh được tái tạo và có thể phát lại.

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

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

**Tham số:**

input_values (`torch.Tensor` có hình dạng `(batch_size, 1, sequence_length)`) : Dạng sóng âm thanh đầu vào.

input_features (`torch.Tensor` có hình dạng `(batch_size, mel_bins, time_steps)`) : Phổ mel âm thanh đầu vào để mã hóa ngữ nghĩa.

padding_mask (`torch.Tensor` có hình dạng `(batch_size, 1, sequence_length)`) : Mặt nạ đệm (padding mask) được sử dụng để đệm `input_values`.

input_features_mask (`torch.Tensor` có shape `(batch_size, time_steps)`, *tùy chọn*) : Mặt nạ chú ý (attention mask) cho đầu vào spectrogram của bộ mã hóa ngữ nghĩa. `1` cho các khung hợp lệ, `0` cho phần đệm (padding).

output_latents (`bool`, *tùy chọn*, mặc định là `False`) : Có nên trả về biểu diễn ẩn liên tục từ bộ lượng tử hóa hay không.

**Trả về:** `Xcodec2EncoderOutput` hoặc `tuple(torch.Tensor)`

Một `Xcodec2EncoderOutput` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình (`None`) và đầu vào.

- **audio_codes** (`torch.LongTensor` có hình dạng `(batch_size, 1, codes_length)`, *tùy chọn*) -- Các embedding mã rời rạc được tính toán bằng `model.encode`. Chúng đại diện cho dạng nén, lượng tử hóa của tín hiệu âm thanh đầu vào, có thể được sử dụng cho lưu trữ, truyền tải hoặc tạo sinh.
- **latents** (`torch.Tensor` có hình dạng `(batch_size, dimension, time_steps)`) -- Biểu diễn liên tục đã lượng tử hóa của embedding đầu vào.
- **audio_codes_mask** (`torch.int32` có shape `(batch_size, 1, codes_length)`, *tùy chọn*) -- `padding_mask` đã downsample để chỉ định các audio code hợp lệ trong `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'>)
```

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

**Tham số:**

input_values (`torch.Tensor` có hình dạng `(batch_size, 1, sequence_length)`) : Dạng sóng âm thanh đầu vào.

input_features (`torch.Tensor` có hình dạng `(batch_size, mel_bins, time_steps)`) : Phổ mel âm thanh đầu vào để mã hóa ngữ nghĩa.

padding_mask (`torch.Tensor` có hình dạng `(batch_size, 1, sequence_length)`) : Mặt nạ đệm (padding mask) được sử dụng để đệm `input_values`.

input_features_mask (`torch.Tensor` có shape `(batch_size, time_steps)`, *tùy chọn*) : Mặt nạ chú ý (attention mask) cho đầu vào spectrogram của bộ mã hóa ngữ nghĩa. `1` cho các khung hợp lệ, `0` cho phần đệm (padding).

output_latents (`bool`, *tùy chọn*, mặc định là `False`) : Có nên trả về biểu diễn ẩn liên tục từ bộ lượng tử hóa hay không.

**Trả về:** `Xcodec2Output` hoặc `tuple(torch.Tensor)`

Một `Xcodec2Output` hoặc một tuple của `torch.Tensor` (nếu `return_dict=False` được truyền hoặc khi `config.return_dict=False`) bao gồm các phần tử khác nhau tùy thuộc vào cấu hình (`None`) và đầu vào.

Phương thức forward của [Xcodec2Model](/docs/transformers/main/vi/model_doc/xcodec2#transformers.Xcodec2Model) ghi đè phương thức đặc biệt `__call__`.

Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, bạn nên gọi instance của `Module` sau đó thay vì gọi hàm này, vì instance `Module` sẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ bỏ qua chúng một cách im lặng.

- **audio_values** (`torch.Tensor` có hình dạng `(batch_size, 1, sequence_length)`, *tùy chọn*) -- Các giá trị dạng sóng âm thanh đã giải mã trong miền thời gian, được lấy bằng phần decoder của Xcodec2. Những giá trị này đại diện cho tín hiệu âm thanh đã được tái tạo.
- **audio_codes** (`torch.LongTensor` có hình dạng `(batch_size, 1, codes_length)`, *tùy chọn*) -- Các embedding mã rời rạc được tính toán bằng `model.encode`. Đây là các biểu diễn lượng tử hóa của âm thanh đầu vào, được sử dụng cho các bước xử lý hoặc tạo tiếp theo.
- **latents** (`torch.Tensor` có hình dạng `(batch_size, dimension, time_steps)`) -- Biểu diễn liên tục đã lượng tử hóa của embedding đầu vào.
- **audio_codes_mask** (`torch.int32` có shape `(batch_size, 1, codes_length)`, *tùy chọn*) -- `padding_mask` đã downsample để chỉ định các audio code hợp lệ trong `audio_codes`.

Ví dụ:

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