# X-Codec2

## Ikhtisar

Model X-Codec2 diusulkan dalam [Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis](https://huggingface.co/papers/2502.04128).

X-Codec2 adalah codec audio neural yang dirancang untuk meningkatkan sintesis ucapan dan generasi audio secara umum untuk pipeline large language model (LLM). Codec ini memperluas X-Codec asli dengan menyempurnakan cara informasi semantik dan akustik diintegrasikan serta ditokenisasi, sehingga memungkinkan representasi audio yang efisien dan berfidelitas tinggi.

Tentang arsitekturnya:
- **Tokenisasi Semantik-Akustik Terpadu**: X-Codec2 menggabungkan keluaran dari encoder semantik (misalnya, Wav2Vec2-BERT) dan encoder akustik menjadi satu embedding, sehingga menangkap makna tingkat tinggi (misalnya, konten teks, emosi) dan detail audio tingkat rendah (misalnya, timbre).
- **Kuantisasi Skalar Fitur Satu Tahap (FSQ)**: Berbeda dengan VQ residual multi-lapisan pada sebagian besar pendekatan (misalnya, [DAC](./dac), [EnCodec](./encodec), [X-Codec](./xcodec), [Mimi](./mimi)), X-Codec2 menggunakan satu lapisan Feature Scalar Quantization (FSQ) untuk stabilitas dan kompatibilitas dengan LLM kausal, autoregresif.
- **Desain yang Ramah Transformer**: Struktur token 1D dari X-Codec2 secara alami selaras dengan pemodelan autoregresif pada LLM seperti LLaMA, sehingga meningkatkan efisiensi pelatihan dan kompatibilitas hilir.

Checkpoint model tersedia di [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf).

Model ini disumbangkan oleh [Eric Bezzam](https://huggingface.co/bezzam) dan [Steven Zheng](https://huggingface.co/Steveeeeeeen). Kode pemodelan aslinya dapat ditemukan [di sini](https://huggingface.co/HKUSTAudio/xcodec2/blob/main/modeling_xcodec2.py), sedangkan kode pelatihan mereka ada [di sini](https://github.com/zhenye234/X-Codec-2.0).

## Contoh penggunaan 

Berikut adalah contoh singkat tentang cara mengkodekan dan mendekodekan audio menggunakan model ini:

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

### Pemrosesan batch

Implementasi ini juga mendukung input berbatch, berbeda dengan [rilis](https://huggingface.co/HKUSTAudio/xcodec2) aslinya!

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

### Percepatan dengan `torch.compile`

Anda dapat mempercepat inferensi dengan [`torch.compile`](https://pytorch.org/docs/stable/generated/torch.compile.html). Beberapa panggilan pertama akan lebih lambat karena overhead kompilasi, tetapi panggilan berikutnya akan lebih cepat.

Pada A100, kami mengamati percepatan sekitar 1,35 untuk ukuran batch 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))
```

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

**Parameter:**

hidden_size (`int`, *opsional*, defaultnya `1024`) : Dimensi dari representasi tersembunyi.

intermediate_size (`int`, *opsional*, defaultnya `4096`) : Dimensi dari representasi MLP.

num_hidden_layers (`int`, *opsional*, defaultnya `12`) : Jumlah lapisan tersembunyi dalam decoder Transformer.

num_attention_heads (`int`, *opsional*, defaultnya `16`) : Jumlah kepala perhatian untuk setiap lapisan perhatian dalam decoder Transformer.

num_key_value_heads (`int`, *opsional*, defaultnya `16`) : Ini adalah jumlah key_value heads yang harus digunakan untuk mengimplementasikan Grouped Query Attention. Jika `num_key_value_heads=num_attention_heads`, model akan menggunakan Multi Head Attention (MHA), jika `num_key_value_heads=1` model akan menggunakan Multi Query Attention (MQA), selain itu GQA yang digunakan. Saat mengonversi checkpoint multi-head menjadi checkpoint GQA, setiap group key dan value head harus dibangun dengan meanpooling semua head asli di dalam grup tersebut. Untuk detail lebih lanjut, lihat [paper ini](https://huggingface.co/papers/2305.13245). Jika tidak ditentukan, akan default ke `num_attention_heads`.

hidden_act (`str`, *opsional*, defaultnya `silu`) : Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, `"gelu"`, `"relu"`, `"silu"`, dan sebagainya.

max_position_embeddings (`int`, *opsional*, defaultnya `4096`) : Panjang urutan maksimum yang mungkin digunakan oleh model ini.

initializer_range (`float`, *opsional*, defaultnya `0.02`) : Deviasi standar dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.

rms_norm_eps (`float`, *opsional*, defaultnya `1e-06`) : Epsilon yang digunakan oleh lapisan normalisasi rms.

pad_token_id (`int`, *opsional*) : ID token yang digunakan untuk padding dalam kosakata.

tie_word_embeddings (`bool`, *opsional*, defaultnya `False`) : Apakah mengikat embedding bobot sesuai dengan pemetaan `tied_weights_keys` model.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *opsional*) : Dictionary yang berisi parameter konfigurasi untuk embedding RoPE. Dictionary harus berisi nilai untuk `rope_theta` dan secara opsional parameter yang digunakan untuk scaling jika Anda ingin menggunakan RoPE dengan `max_position_embeddings` yang lebih panjang.

attention_bias (`bool`, *opsional*, defaultnya `False`) : Apakah akan menggunakan bias pada lapisan proyeksi query, key, value, dan output selama self-attention.

attention_dropout (`Union[int, float]`, *opsional*, defaultnya `0.0`) : Rasio dropout untuk probabilitas perhatian.

head_dim (`int`, *opsional*, defaultnya `64`) : Dimensi kepala perhatian. Jika None, nilainya akan menjadi hidden_size // num_attention_heads

encoder_hidden_size (`int`, *opsional*, defaultnya `48`) : Dimensi dari representasi tersembunyi.

downsampling_ratios (`list[int]`, *opsional*, default `[2, 2, 4, 4, 5]`) : Rasio untuk downsampling di encoder.

semantic_model_config (`Union[Dict, Wav2Vec2BertConfig]`, *opsional*) : Sebuah instance dari objek konfigurasi untuk model semantik (Wav2Vec2BertConfig).

sampling_rate (`int`, *opsional*, defaultnya `16000`) : Laju sampling di mana file audio harus didigitalisasi, dinyatakan dalam hertz (Hz).

activation_dropout (`float`, *opsional*, default `0.1`) : Rasio dropout untuk aktivasi di dalam lapisan fully connected.

quantization_dim (`int`, *opsional*, default 2048) : Dimensi untuk codebook kuantisasi vektor.

quantization_levels (`list[int]`, *opsional*, defaultnya `[4, 4, 4, 4, 4, 4, 4, 4]`) : Level untuk codebook kuantisasi vektor.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Xcodec2Model. Kelas ini digunakan untuk membuat instans model Xcodec2 sesuai dengan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf)

Objek konfigurasi mewarisi dari [PreTrainedConfig](/docs/transformers/v5.23.0/id/main_classes/configuration#transformers.PreTrainedConfig) dan dapat digunakan untuk mengontrol keluaran model. Baca dokumentasi dari [PreTrainedConfig](/docs/transformers/v5.23.0/id/main_classes/configuration#transformers.PreTrainedConfig) untuk informasi lebih lanjut.

Contoh:

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

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

**Parameter:**

feature_size (`int`, *opsional*, defaultnya 80) : Dimensi fitur dari fitur yang diekstrak.

sampling_rate (`int`, *opsional*, default 16000) : Laju sampel di mana file audio harus didigitalisasi, dinyatakan dalam hertz (Hz).

padding_value (`float`, *opsional*, default 1.0) : Nilai yang digunakan untuk mengisi vektor padding pada spektrogram mel.

hop_length (`int`, *opsional*, default 320) : Jumlah sampel audio yang dikodekan per frame. Setara dengan hasil perkalian rasio downsampling. Diperlukan untuk padding input encoder akustik.

Membangun ekstraktor fitur Xcodec2, yang menghitung fitur bank filter mel untuk encoder semantik dan audio yang di-pad untuk encoder akustik.

Feature extractor ini mewarisi dari [SequenceFeatureExtractor](/docs/transformers/v5.23.0/id/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) yang berisi sebagian besar metode utama. Pengguna harus merujuk ke superclass ini untuk informasi lebih lanjut mengenai metode-metode tersebut.

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

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

**Parameter:**

audio (`np.ndarray`, `torch.Tensor`, `list[np.ndarray]`, `list[torch.Tensor]`) : array Numpy atau tensor torch dengan bentuk (num_channels, sequence_length). Daftar array atau tensor seperti itu juga dapat disediakan untuk batch input.

padding (`bool`, `str` atau [PaddingStrategy](/docs/transformers/v5.23.0/id/internal/file_utils#transformers.utils.PaddingStrategy), *opsional*, default `True`) : Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara: - `True` atau `'longest'`: Lakukan padding hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan). - `'max_length'`: Lakukan padding hingga panjang maksimum yang ditentukan dengan argumen `max_length` atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan. - `False` atau `'do_not_pad'` (default): Tanpa padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda-beda).

max_length (`int`, *opsional*) : Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).

truncation (`bool`) : Mengaktifkan pemotongan untuk memotong urutan input yang lebih panjang dari *max_length* menjadi *max_length*.

return_tensors (`str` atau [TensorType](/docs/transformers/v5.23.0/id/internal/file_utils#transformers.TensorType), *opsional*) : Jika diatur, akan mengembalikan tensor alih-alih daftar integer python. Nilai yang dapat diterima adalah:  - `'tf'`: Mengembalikan objek `tf.constant` TensorFlow. - `'pt'`: Mengembalikan objek `torch.Tensor` PyTorch. - `'np'`: Mengembalikan objek `np.ndarray` Numpy.

sampling_rate (`int`, *opsional*) : Laju sampel di mana input `audio` disampelkan. Sangat disarankan untuk meneruskan `sampling_rate` pada panggilan forward untuk mencegah kesalahan yang tidak terdeteksi.

device (`str`, *opsional*, defaultnya `"cpu"`) : Perangkat untuk tensor PyTorch selama ekstraksi fitur mel-filter bank.

kwargs (*opsional*) : Sisa kamus argumen kata kunci yang akan diteruskan ke tokenizer atau feature extractor.

## Xcodec2Model[[transformers.Xcodec2Model]]

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

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

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

**Parameter:**

config ([Xcodec2Config](/docs/transformers/v5.23.0/id/model_doc/xcodec2#transformers.Xcodec2Config)) : Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode [from_pretrained()](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel.from_pretrained) untuk memuat bobot model.

Model codec audio neural Xcodec2.

Model ini mewarisi dari [PreTrainedModel](/docs/transformers/v5.23.0/id/main_classes/model#transformers.PreTrainedModel). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka ini untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran input embeddings, memangkas heads, dll.)

Model ini juga merupakan subclass dari [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

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

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

**Parameter:**

audio_codes (`torch.LongTensor` dengan bentuk `(batch_size, 1, codes_length)`) : Indeks kode diskrit yang dihitung menggunakan `model.encode`.

latents (`torch.Tensor` dengan bentuk `(batch_size, dimension, time_steps)`, *opsional*) : Representasi kontinu terkuantisasi dari input.

**Mengembalikan:** `Xcodec2DecoderOutput` atau `tuple(torch.Tensor)`

`Xcodec2DecoderOutput` atau tuple dari `torch.Tensor` (jika `return_dict=False` dilewatkan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi (`None`) dan input.

- **audio_values** (`torch.Tensor` dengan bentuk `(batch_size, 1, segment_length)`, *opsional*) -- Nilai waveform audio yang telah didekodekan dalam domain waktu, diperoleh dengan mengonversi kode diskrit kembali menjadi sinyal audio kontinu. Ini merepresentasikan audio yang direkonstruksi dan dapat diputar kembali.

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

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

**Parameter:**

input_values (`torch.Tensor` dengan bentuk `(batch_size, 1, sequence_length)`) : Gelombang audio input.

input_features (`torch.Tensor` dengan bentuk `(batch_size, mel_bins, time_steps)`) : Spektrum mel audio input untuk pengkodean semantik.

padding_mask (`torch.Tensor` dengan bentuk `(batch_size, 1, sequence_length)`) : Padding mask yang digunakan untuk mengisi `input_values`.

input_features_mask (`torch.Tensor` dengan bentuk `(batch_size, time_steps)`, *opsional*) : Mask perhatian untuk input spektrogram ke encoder semantik. `1` untuk frame valid, `0` untuk padding.

output_latents (`bool`, *opsional*, defaultnya `False`) : Apakah akan mengembalikan representasi laten kontinu dari kuantizer.

**Mengembalikan:** `Xcodec2EncoderOutput` atau `tuple(torch.Tensor)`

A `Xcodec2EncoderOutput` atau tuple dari `torch.Tensor` (jika `return_dict=False` dilewatkan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi (`None`) dan input.

- **audio_codes** (`torch.LongTensor` dengan bentuk `(batch_size, 1, codes_length)`, *opsional*) -- Embedding kode diskrit yang dihitung menggunakan `model.encode`. Kode-kode ini mewakili bentuk terkompresi dan terkuantisasi dari sinyal audio input yang dapat digunakan untuk penyimpanan, transmisi, atau generasi.
- **latents** (`torch.Tensor` dengan bentuk `(batch_size, dimension, time_steps)`) -- Representasi kontinu terkuantisasi dari embedding input.
- **audio_codes_mask** (`torch.int32` dengan bentuk `(batch_size, 1, codes_length)`, *opsional*) -- `padding_mask` yang telah di-downsample untuk menunjukkan kode audio yang valid di dalam `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'>)
```

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

**Parameter:**

input_values (`torch.Tensor` dengan bentuk `(batch_size, 1, sequence_length)`) : Gelombang audio input.

input_features (`torch.Tensor` dengan bentuk `(batch_size, mel_bins, time_steps)`) : Spektrum mel audio input untuk pengkodean semantik.

padding_mask (`torch.Tensor` dengan bentuk `(batch_size, 1, sequence_length)`) : Padding mask yang digunakan untuk mengisi `input_values`.

input_features_mask (`torch.Tensor` dengan bentuk `(batch_size, time_steps)`, *opsional*) : Mask perhatian untuk input spektrogram ke encoder semantik. `1` untuk frame valid, `0` untuk padding.

output_latents (`bool`, *opsional*, defaultnya `False`) : Apakah akan mengembalikan representasi laten kontinu dari kuantizer.

**Mengembalikan:** `Xcodec2Output` atau `tuple(torch.Tensor)`

A `Xcodec2Output` atau tuple dari `torch.Tensor` (jika `return_dict=False` diteruskan atau ketika `config.return_dict=False`) yang terdiri dari berbagai elemen tergantung pada konfigurasi (`None`) dan input.

Metode forward dari [Xcodec2Model](/docs/transformers/v5.23.0/id/model_doc/xcodec2#transformers.Xcodec2Model) menimpa metode khusus `__call__`.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance `Module` setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

- **audio_values** (`torch.Tensor` dengan bentuk `(batch_size, 1, sequence_length)`, *opsional*) -- Nilai waveform audio yang telah didekodekan dalam domain waktu, diperoleh menggunakan bagian decoder dari Xcodec2. Nilai-nilai ini merepresentasikan sinyal audio yang direkonstruksi.
- **audio_codes** (`torch.LongTensor` dengan bentuk `(batch_size, 1, codes_length)`, *opsional*) -- Embedding kode diskrit yang dihitung menggunakan `model.encode`. Ini adalah representasi kuantisasi dari audio input yang digunakan untuk pemrosesan atau generasi lebih lanjut.
- **latents** (`torch.Tensor` dengan bentuk `(batch_size, dimension, time_steps)`) -- Representasi kontinu terkuantisasi dari embedding input.
- **audio_codes_mask** (`torch.int32` dengan bentuk `(batch_size, 1, codes_length)`, *opsional*) -- `padding_mask` yang telah di-downsample untuk menunjukkan kode audio yang valid di dalam `audio_codes`.

Contoh:

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

