# X-Codec

## Genel Bakış

X-Codec modeli, Zhen Ye, Peiwen Sun, Jiahe Lei, Hongzhan Lin, Xu Tan, Zheqi Dai, Qiuqiang Kong, Jianyi Chen, Jiahao Pan, Qifeng Liu, Yike Guo ve Wei Xue tarafından [Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model](https://huggingface.co/papers/2408.17175) makalesinde önerilmiştir.

X-Codec modeli, kendinden denetimli modellerden (ör. HuBERT) gelen semantik bilgileri geleneksel akustik bilgilerle birleştiren sinirsel bir ses kodlayıcısıdır. Bu sayede:

- **Müzik devamı**: Müziksel anlambilimin daha iyi modellenmesi, daha tutarlı devamlar sağlar.
- **Ses Sentezi**: X-Codec, metin istemleri ile üretilen ses arasındaki anlamsal uyumu yakalar.
- **Anlama duyarlı ses tokenizasyonu**: X-Codec, YuE sözlerden şarkı üretim modelinde ses tokenizatörü olarak kullanılır.

Makalenin özeti şunları belirtmektedir:

*Ses üretimi alanındaki son gelişmeler, Büyük Dil Modellerinin (LLM) yetenekleri tarafından önemli ölçüde desteklenmiştir. Ses LLM'leri üzerine yapılan mevcut araştırmalar, ağırlıklı olarak ses dil modellerinin mimarisini ve ölçeğini iyileştirmeye, daha büyük veri kümelerinden yararlanmaya odaklanmıştır ve genel olarak EnCodec gibi akustik codec'ler ses tokenizasyonu için kullanılmaktadır. Ancak bu codec'ler başlangıçta ses sıkıştırma için tasarlandığından, ses LLM bağlamında suboptimal performansa yol açabilir. Araştırmamız, mevcut ses LLM codec'lerinin eksikliklerini, özellikle üretilen seslerde semantik bütünlüğü korumadaki zorluklarını ele almayı hedeflemektedir. Örneğin, akustik token üretimini metin transkripsiyonlarına koşullandıran VALL-E gibi mevcut yöntemler, akustik tokenlerin semantik yanlış yorumlanması nedeniyle içerik doğruluğu sorunları ve yüksek kelime hata oranlarına (WER) maruz kalır; bu durum kelime atlama ve hatalara neden olur. Bu sorunları aşmak için X-Codec adlı basit ama etkili bir yaklaşım öneriyoruz. X-Codec, Residual Vector Quantization (RVQ) aşamasından önce önceden eğitilmiş bir semantik kodlayıcıdan semantik özellikleri dahil eder ve RVQ'den sonra bir semantik yeniden yapılandırma kaybı (loss) tanıtır. Codec'in semantik yeteneğini artırarak X-Codec, konuşma sentez görevlerinde WER'i önemli ölçüde azaltır ve bu faydaları müzik ve ses üretimi gibi konuşma dışı uygulamalara da taşır. Metinden konuşmaya, müzik devamı ve metinden sese görevlerindeki deneyimlerimiz, semantik bilginin entegrasyonunun ses üretiminde dil modellerinin genel performansını önemli ölçüde iyileştirdiğini göstermektedir.*

Model kartları:

- [xcodec-hubert-librispeech](https://huggingface.co/hf-audio/xcodec-hubert-librispeech) (konuşma için)
- [xcodec-wavlm-mls](https://huggingface.co/hf-audio/xcodec-wavlm-mls) (konuşma için)
- için [xcodec-wavlm-more-data](https://huggingface.co/hf-audio/xcodec-wavlm-more-data)
- [xcodec-hubert-general](https://huggingface.co/hf-audio/xcodec-hubert-general) (genel ses için)
- [xcodec-hubert-general-balanced](https://huggingface.co/hf-audio/xcodec-hubert-general-balanced) (genel ses için)

Bu model [Manal El Aidouni](https://huggingface.co/Manel) tarafından katkıda bulunmuştur. Orijinal kod [burada](https://github.com/zhenye234/xcodec) ve beş farklı modelin orijinal denetim noktaları [burada](https://github.com/zhenye234/xcodec?tab=readme-ov-file#available-models) bulunabilir.

Demolar bu [sayfada](https://x-codec-audio.github.io/) bulunabilir.

## Kullanım örneği

Bu modelle bir ses dosyasını kodlama ve çözmeye dair hızlı bir örnek:

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

Orijinal ve yeniden oluşturulan sesi dinlemek için aşağıdaki kod parçasını çalıştırın ve ardından karşılaştırma yapmak için oluşturulan `original.wav` ve `reconstruction.wav` dosyalarını müzik çalarınızda açın.

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

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

**Parametreler:**

target_bandwidths (`List[float]`, *isteğe bağlı*, varsayılan `[0.5, 1, 1.5, 2, 4]`) : Modelin ses kodlayabileceği farklı bant genişliklerinin (kbps cinsinden) aralığı.

sample_rate (`int`, *isteğe bağlı*, varsayılan `16000`) : Ses dosyalarının dijitalleştirileceği örneklem hızı, hertz (Hz) cinsinden ifade edilir.

kernel_size (`int`, *isteğe bağlı*, varsayılan `3`) : Konvolüsyon çekirdeğinin boyutu.

channel_ratios (`List[float]`, *isteğe bağlı*, varsayılan `[1, 1]`) : Her anlamsal blokta çıktı kanal sayısının genişleme çarpanları.

strides (`List[int]`, *isteğe bağlı*, varsayılan `[1, 1]`) : Her anlamsal kodlayıcı bloğu için kaydırma değerleri.

block_dilations (`List[int]`, *opsiyonel*, varsayılan `[1, 1]`) : Semantik bloklardaki artımsal birimler için genişleme katsayıları.

unit_kernel_size (`int`, *opsiyonel*, varsayılan 3) : Semantik bloklardaki her ResidualUnit içindeki çekirdek boyutu.

codebook_size (`int`, *isteğe bağlı*, varsayılan `1024`) : Modelin kullandığı paralel kod kitaplarının sayısı.

codebook_dim (`int`, *isteğe bağlı*) : Her kod kitabı gömme vektörünün boyutluluğu.

initializer_range (`float`, *opsiyonel*, varsayılan `0.02`) : Tüm ağırlık matrislerini başlatmak için kullanılan truncated_normal_initializer'ın standart sapması.

acoustic_model_config (`Union[Dict, DacConfig]`, *isteğe bağlı*) : Akustik (DAC) modeli için yapılandırma örneği.

semantic_model_config (`Union[Dict, HubertConfig, WavLMConfig]`, *isteğe bağlı*) : Semantik (HuBERT) modeli için yapılandırma nesnesinin bir örneği.

Bu, bir XcodecModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Xcodec modelini örneklemek ve model mimarisini tanımlamak için kullanılır. Varsayılanlarla bir yapılandırma örneği oluşturmak, [Manel/X-Codec](https://huggingface.co/Manel/X-Codec) ile benzer bir yapılandırmaya yol açar.

Yapılandırma nesneleri [PreTrainedConfig](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig) sınıfından türetilir ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için [PreTrainedConfig](/docs/transformers/v5.23.0/tr/main_classes/configuration#transformers.PreTrainedConfig) belgesini okuyun.

Örnek:

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

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

**Parametreler:**

config ([XcodecConfig](/docs/transformers/v5.23.0/tr/model_doc/xcodec#transformers.XcodecConfig)) : Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için [from_pretrained()](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel.from_pretrained) yöntemine göz atın.

Xcodec sinirsel ses kodlayıcı modeli.

Bu model [PreTrainedModel](/docs/transformers/v5.23.0/tr/main_classes/model#transformers.PreTrainedModel) sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden ayarlama, başları budama vb.) için üst sınıf belgelendirmesine bakın.

Bu model aynı zamanda bir PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.

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

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

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

**Parametreler:**

audio_codes (`torch.LongTensor`, şekli `(batch_size, num_quantizers, codes_length)`) : `model.encode` kullanılarak hesaplanan ayrık kod dizinleri.

return_dict (`bool`, *isteğe bağlı*) : Bir [ModelOutput](/docs/transformers/v5.23.0/tr/main_classes/output#transformers.utils.ModelOutput) döndürülecek mi

**Dönüş:**

Xcodec'in decoder kısmı kullanılarak elde edilen, `(batch_size, channels, num_samples)` biçiminde çözülmüş ses değerleri.

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

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

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

**Parametreler:**

input_values (`torch.Tensor`, şekli `(batch_size, channels, num_samples)`) : Girdi ses dalgasının ondalık değerleri.

bandwidth (`float`, *isteğe bağlı*) : Hedef bant genişliği (kbps), yalnızca `config.target_bandwidths` içindeki değerleri destekler. Varsayılan olarak en yüksek kullanılabilir bant genişliği olan `4.0` kbps'dir.

return_dict (`bool`, *isteğe bağlı*) : [ModelOutput](/docs/transformers/v5.23.0/tr/main_classes/output#transformers.utils.ModelOutput) döndürülecek mi?

**Dönüş:**

`torch.LongTensor`, şekli `(batch_size, num_quantizers, codes_length)` olan ve ayrık kodlanmış ses kodlarını içeren.

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

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

**Parametreler:**

input_values (`torch.Tensor`, şekli `(batch_size, channels, num_samples)`) : Girdi ses dalgasının ham ondalık değerleri.

audio_codes (`torch.LongTensor` , şekli `(batch_size, num_quantizers, codes_length)` : `model.encode` kullanılarak hesaplanan ayrık kod dizinleri.

bandwidth (`float`, *isteğe bağlı*) : kbps cinsinden hedef bant genişliği. `config.target_bandwidths` değerlerinden biri olmalıdır. Varsayılan olarak kullanılabilir en yüksek bant genişliği kullanılır.

bandwidth (`float`, *isteğe bağlı*) : kbps cinsinden hedef bant genişliği. `config.target_bandwidths` değerlerinden biri olmalıdır. Varsayılan olarak kullanılabilir en yüksek bant genişliği kullanılır.

**Dönüş:** `XcodecOutput` veya `(audio_codes, audio_values)` demeti

- `audio_codes`, şekli `(batch_size, num_quantizers, codes_length)`: kuantize edilmiş ayrık kodlar.
- `audio_values`, şekli `(batch_size, channels, num_samples)`: kodlara göre yeniden oluşturulan ses dalgası.

[XcodecModel](/docs/transformers/v5.23.0/tr/model_doc/xcodec#transformers.XcodecModel) forward metodu, `__call__` özel metodunu geçersiz kılar.

İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine `Module` örneğini çağırmak gerekir; çünkü ilki ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.

Örnek:

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