# X-Codec

## Tổng quan

Mô hình X-Codec được đề xuất trong [Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model](https://huggingface.co/papers/2408.17175) của Zhen Ye, Peiwen Sun, Jiahe Lei, Hongzhan Lin, Xu Tan, Zheqi Dai, Qiuqiang Kong, Jianyi Chen, Jiahao Pan, Qifeng Liu, Yike Guo, Wei Xue.

Mô hình X-Codec là một bộ mã hóa âm thanh neural tích hợp thông tin ngữ nghĩa từ các mô hình tự giám sát (ví dụ: HuBERT) cùng với thông tin âm học truyền thống. Điều này cho phép:

- **Tiếp nối âm nhạc**: Mô hình hóa ngữ nghĩa âm nhạc tốt hơn tạo ra các phần tiếp nối nhất quán hơn.
- **Tổng hợp văn bản thành âm thanh**: X-Codec nắm bắt sự tương thích ngữ nghĩa giữa các câu lệnh văn bản và âm thanh được tạo ra.
- **Token hóa âm thanh nhận thức ngữ nghĩa**: X-Codec được sử dụng như một bộ token hóa âm thanh trong mô hình tạo bài hát từ lời bài hát YuE.

Tóm tắt của bài báo nêu rõ như sau:

*Những tiến bộ gần đây trong lĩnh vực tạo âm thanh đã được thúc đẩy đáng kể nhờ khả năng của các Mô hình Ngôn ngữ Lớn (LLM). Nghiên cứu hiện có về LLM âm thanh chủ yếu tập trung vào việc nâng cao kiến trúc và quy mô của các mô hình ngôn ngữ âm thanh, cũng như tận dụng các bộ dữ liệu lớn hơn; nhìn chung, các bộ mã hóa âm thanh (acoustic codecs), chẳng hạn như EnCodec, được sử dụng để mã hóa token âm thanh. Tuy nhiên, các bộ mã hóa này ban đầu được thiết kế cho nén âm thanh, điều này có thể dẫn đến hiệu suất không tối ưu trong bối cảnh LLM âm thanh. Nghiên cứu của chúng tôi nhằm giải quyết những hạn chế của các bộ mã hóa LLM âm thanh hiện tại, đặc biệt là thách thức trong việc duy trì tính toàn vẹn ngữ nghĩa của âm thanh được tạo ra. Ví dụ, các phương pháp hiện có như VALL-E, vốn điều kiện hóa việc tạo token âm thanh dựa trên bản chuyển tự văn bản, thường gặp phải các sai lệch về nội dung và tỷ lệ lỗi từ (WER) cao do diễn giải sai ngữ nghĩa của các token âm thanh, dẫn đến hiện tượng bỏ sót từ và lỗi. Để khắc phục những vấn đề này, chúng tôi đề xuất một phương pháp đơn giản nhưng hiệu quả có tên là X-Codec. X-Codec tích hợp các đặc trưng ngữ nghĩa từ một bộ mã hóa ngữ nghĩa được huấn luyện trước vào trước giai đoạn Lượng tử hóa Vector Dư (RVQ) và đưa vào một tổn thất tái tạo ngữ nghĩa sau RVQ. Bằng cách nâng cao khả năng ngữ nghĩa của bộ mã hóa, X-Codec giảm đáng kể WER trong các tác vụ tổng hợp giọng nói và mở rộng những lợi ích này sang các ứng dụng phi giọng nói, bao gồm tạo nhạc và tạo âm thanh. Các thí nghiệm của chúng tôi trong các tác vụ text-to-speech, tiếp nối nhạc và text-to-sound cho thấy việc tích hợp thông tin ngữ nghĩa cải thiện đáng kể hiệu suất tổng thể của các mô hình ngôn ngữ trong tạo âm thanh.*

Thẻ mô hình:

- [xcodec-hubert-librispeech](https://huggingface.co/hf-audio/xcodec-hubert-librispeech) (cho giọng nói)
- [xcodec-wavlm-mls](https://huggingface.co/hf-audio/xcodec-wavlm-mls) (cho giọng nói)
- [xcodec-wavlm-more-data](https://huggingface.co/hf-audio/xcodec-wavlm-more-data) (cho giọng nói)
- [xcodec-hubert-general](https://huggingface.co/hf-audio/xcodec-hubert-general) (cho âm thanh chung)
- [xcodec-hubert-general-balanced](https://huggingface.co/hf-audio/xcodec-hubert-general-balanced) (cho âm thanh chung)

Mô hình này được đóng góp bởi [Manal El Aidouni](https://huggingface.co/Manel). Mã gốc có thể được tìm thấy [tại đây](https://github.com/zhenye234/xcodec) và các checkpoint gốc cho năm mô hình khác nhau [tại đây](https://github.com/zhenye234/xcodec?tab=readme-ov-file#available-models).

Các bản demo có thể được tìm thấy trên [trang](https://x-codec-audio.github.io/) này.

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

Để nghe âm thanh gốc và âm thanh tái tạo, hãy chạy đoạn mã bên dưới rồi mở các tệp `original.wav` và `reconstruction.wav` đã được tạo trong trình phát nhạc của bạn để so sánh.

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/configuration_xcodec.py#L28)

**Tham số:**

target_bandwidths (`List[float]`, *tuỳ chọn*, mặc định là `[0.5, 1, 1.5, 2, 4]`) : Khoảng các băng thông khác nhau (tính bằng kbps) mà mô hình có thể dùng để mã hóa âm thanh.

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

kernel_size (`int`, *optional*, mặc định là `3`) : Kích thước của nhân tích chập.

channel_ratios (`List[float]`, *tùy chọn*, mặc định là `[1, 1]`) : Các hệ số mở rộng cho số kênh đầu ra trong mỗi khối ngữ nghĩa.

strides (`List[int]`, *tùy chọn*, mặc định là `[1, 1]`) : Strides cho mỗi khối semantic encoder.

block_dilations (`List[int]`, *tùy chọn*, mặc định là `[1, 1]`) : Các hệ số giãn nở cho các đơn vị dư trong các khối ngữ nghĩa.

unit_kernel_size (`int`, *tuỳ chọn*, mặc định là 3) : Kích thước kernel bên trong mỗi ResidualUnit trong các khối ngữ nghĩa.

codebook_size (`int`, *tuỳ chọn*, mặc định là `1024`) : Số lượng codebook song song được mô hình sử dụng.

codebook_dim (`int`, *tuỳ chọn*) : Số chiều của mỗi vector nhúng trong codebook.

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

acoustic_model_config (`Union[Dict, DacConfig]`, *tùy chọn*) : Một instance của cấu hình cho mô hình âm thanh (DAC).

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

Đây là lớp cấu hình để lưu trữ cấu hình của một XcodecModel. Nó được sử dụng để khởi tạo một mô hình Xcodec 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 [Manel/X-Codec](https://huggingface.co/Manel/X-Codec)

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L445)

**Tham số:**

config ([XcodecConfig](/docs/transformers/main/vi/model_doc/xcodec#transformers.XcodecConfig)) : 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 Xcodec.

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L541)

**Tham số:**

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

return_dict (`bool`, *tùy chọn*) : Có trả về một [ModelOutput](/docs/transformers/main/vi/main_classes/output#transformers.utils.ModelOutput) hay không

**Trả về:**

Giá trị âm thanh đã giải mã có hình dạng `(batch_size, channels, num_samples)` thu được bằng cách sử dụng phần giải mã của Xcodec.

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L489)

**Tham số:**

input_values (`torch.Tensor` có hình dạng `(batch_size, channels, num_samples)`) : Các giá trị Float của dạng sóng âm thanh đầu vào.

bandwidth (`float`, *optional*) : Băng thông mục tiêu (kbps) chỉ hỗ trợ các giá trị trong `config.target_bandwidths`. Mặc định là băng thông cao nhất khả dụng `4.0` kbps.

return_dict (`bool`, *tùy chọn*) : Có trả về một [ModelOutput](/docs/transformers/main/vi/main_classes/output#transformers.utils.ModelOutput) hay không.

**Trả về:**

`torch.LongTensor` có hình dạng `(batch_size, num_quantizers, codes_length)` chứa các mã âm thanh mã hóa rời rạc.

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L569)

**Tham số:**

input_values (`torch.Tensor` có hình dạng `(batch_size, channels, num_samples)`) : Các giá trị float thô của dạng sóng âm thanh đầu vào.

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

bandwidth (`float`, *optional*) : Băng thông mục tiêu tính bằng kbps. Phải là một trong các giá trị của `config.target_bandwidths`. Mặc định là băng thông cao nhất có sẵn.

bandwidth (`float`, *optional*) : Băng thông mục tiêu tính bằng kbps. Phải là một trong các giá trị của `config.target_bandwidths`. Mặc định là băng thông cao nhất có sẵn.

**Trả về:** `XcodecOutput` hoặc tuple `(audio_codes, audio_values)`

- `audio_codes` có hình dạng `(batch_size, num_quantizers, codes_length)`: các mã rời rạc đã lượng tử hóa.
- `audio_values` có hình dạng `(batch_size, channels, num_samples)`: dạng sóng âm thanh được tái tạo từ các mã.

Phương thức forward của [XcodecModel](/docs/transformers/main/vi/model_doc/xcodec#transformers.XcodecModel) 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.

Ví dụ:

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