# X-Codec

## نظرة عامة

قُدِّم نموذج X-Codec في [Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model](https://huggingface.co/papers/2408.17175) من قِبل Zhen Ye وPeiwen Sun وJiahe Lei وHongzhan Lin وXu Tan وZheqi Dai وQiuqiang Kong وJianyi Chen وJiahao Pan وQifeng Liu وYike Guo وWei Xue.

نموذج X-Codec هو مشفّر صوتي عصبي يدمج المعلومات الدلالية من النماذج ذاتية الإشراف (مثل HuBERT) إلى جانب المعلومات الصوتية التقليدية. وهذا يتيح:

- **استكمال الموسيقى**: يؤدي نمذجة أفضل للدلالات الموسيقية إلى استكمالات أكثر تماسكاً.
- **توليد الصوت من النص**: يلتقط X-Codec المحاذاة الدلالية بين أوامر النص والصوت المولّد.
- **تجزئة الصوت الواعية بالمعنى**: يُستخدم X-Codec كمجزِّئ صوتي في نموذج توليد الأغاني من الكلمات YuE.

ينص ملخص الورقة البحثية على ما يلي:

*دفع التطور الأخير في توليد الصوت بشكل كبير قدرات نماذج اللغة الكبيرة (LLMs). ركّزت الأبحاث القائمة على نماذج اللغة الصوتية بشكل أساسي على تحسين بنية نماذج اللغة الصوتية ومقياسها، فضلاً عن الاستفادة من مجموعات بيانات أكبر، وعادةً ما تُستخدم مشفّرات صوتية (acoustic codecs) مثل EnCodec لتجزئة الصوت. ومع ذلك، صُممت هذه المشفّرات في الأصل لضغط الصوت، مما قد يؤدي إلى أداء غير مثالي في سياق نماذج اللغة الصوتية. يهدف بحثنا إلى معالجة أوجه القصور في مشفّرات نماذج اللغة الصوتية الحالية، وتحديداً تحدياتها في الحفاظ على السلامة الدلالية في الصوت المولّد. فعلى سبيل المثال، غالباً ما تعاني الأساليب القائمة مثل VALL-E، التي تشترط توليد الرموز الصوتية على النصوص المنقولة نصياً، من عدم دقة المحتوى ومعدلات خطأ الكلمات (WER) المرتفعة بسبب سوء تفسير الرموز الصوتية دلالياً، مما يؤدي إلى تخطي الكلمات وأخطاء أخرى. للتغلب على هذه المشكلات، نقترح نهجاً بسيطاً وفعالاً يُدعى X-Codec. يدمج X-Codec الميزات الدلالية من مشفّر دلالي مُدرَّب مسبقاً قبل مرحلة التكميم المتجهي المتبقي (RVQ)، ويقدّم خسارة إعادة بناء دلالية بعد RVQ. من خلال تعزيز القدرة الدلالية للمشفّر، يقلّل X-Codec بشكل كبير من WER في مهام تركيب الكلام، ويمدّ هذه الفوائد إلى التطبيقات غير الكلامية، بما في ذلك توليد الموسيقى والأصوات. تُظهر تجاربنا في مهام النص إلى الكلام، واستكمال الموسيقى، والنص إلى الصوت، أن دمج المعلومات الدلالية يحسّن بشكل كبير الأداء العام لنماذج اللغة في توليد الصوت.*

بطاقات النماذج:

- [xcodec-hubert-librispeech](https://huggingface.co/hf-audio/xcodec-hubert-librispeech) (للتعرف على الكلام)
- [xcodec-wavlm-mls](https://huggingface.co/hf-audio/xcodec-wavlm-mls) (للتحدث)
- [xcodec-wavlm-more-data](https://huggingface.co/hf-audio/xcodec-wavlm-more-data) (للتحدث)
- [xcodec-hubert-general](https://huggingface.co/hf-audio/xcodec-hubert-general) (لصوت عام)
- [xcodec-hubert-general-balanced](https://huggingface.co/hf-audio/xcodec-hubert-general-balanced) (لصوت عام)

تمت مساهمة هذا النموذج من قِبل [Manal El Aidouni](https://huggingface.co/Manel). يمكن العثور على الكود الأصلي [هنا](https://github.com/zhenye234/xcodec) ونقاط التفتيش الأصلية للنماذج الخمسة المختلفة [هنا](https://github.com/zhenye234/xcodec?tab=readme-ov-file#available-models).

يمكن العثور على العروض التوضيحية في هذه [الصفحة](https://x-codec-audio.github.io/).

## مثال على الاستخدام

فيما يلي مثال سريع على كيفية ترميز وفك ترميز صوت باستخدام هذا النموذج:

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

للاستماع إلى الصوت الأصلي والصوت المُعاد بناؤه، شغّل المقطع البرمجي أدناه ثم افتح الملفين `original.wav` و`reconstruction.wav` في مشغل الموسيقى لديك للمقارنة.

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

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/configuration_xcodec.py#L28)

**المعاملات:**

target_bandwidths (`List[float]`، *اختياري*، القيمة الافتراضية `[0.5, 1, 1.5, 2, 4]`) : نطاق نطاقات التردد المختلفة (بوحدة كيلوبت/ثانية) التي يمكن للنموذج ترميز الصوت بها.

sample_rate (`int`، *اختياري*، القيمة الافتراضية `16000`) : معدل أخذ العينات الذي يجب أن تُرقَم به ملفات الصوت، ويُعبَّر عنه بالهرتز (Hz).

kernel_size (`int`، *اختياري*، القيمة الافتراضية `3`) : حجم النواة الالتفافية.

channel_ratios (`List[float]`، *اختياري*، القيمة الافتراضية `[1, 1]`) : عوامل التوسيع لعدد قنوات الإخراج في كل كتلة دلالية.

strides (`List[int]`، *اختياري*، القيمة الافتراضية `[1, 1]`) : خطوات لكل كتلة من مشفّرات الدلالات.

block_dilations (`List[int]`، *اختياري*، القيمة الافتراضية `[1, 1]`) : عوامل التمدد للوحدات المتبقية في الكتل الدلالية.

unit_kernel_size (`int`، *اختياري*، القيمة الافتراضية 3) : حجم النواة داخل كل ResidualUnit في الكتل الدلالية.

codebook_size (`int`، *اختياري*، القيمة الافتراضية `1024`) : عدد كتيّبات الأكواد المتوازية التي يستخدمها النموذج.

codebook_dim (`int`، *اختياري*) : بُعد متجه تضمين كل كتاب رموز.

initializer_range (`float`، *اختياري*، القيمة الافتراضية `0.02`) : الانحراف المعياري لـ truncated_normal_initializer المستخدم في تهيئة جميع مصفوفات الأوزان.

acoustic_model_config (`Union[Dict, DacConfig]`، *اختياري*) : نسخة من إعدادات النموذج الصوتي (DAC).

semantic_model_config (`Union[Dict, HubertConfig, WavLMConfig]`، *اختياري*) : نسخة من كائن الإعدادات الخاص بالنموذج الدلالي (HuBERT).

هذه فئة الإعدادات المخزنة لإعدادات نموذج XcodecModel. تُستخدم لاستحداث نموذج Xcodec وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ [Manel/X-Codec](https://huggingface.co/Manel/X-Codec)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:

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

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L445)

**المعاملات:**

config ([XcodecConfig](/docs/transformers/main/ar/model_doc/xcodec#transformers.XcodecConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

نموذج Xcodec، وهو ترميز صوتي عصبي.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### فك الترميز[[transformers.XcodecModel.decode]]

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

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L541)

**المعاملات:**

audio_codes (`torch.LongTensor` من الشكل `(batch_size, num_quantizers, codes_length)`) : فهارس رموز منفصلة محسوبة باستخدام `model.encode`.

return_dict (`bool`، *اختياري*) : ما إذا كان يجب إرجاع [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput)

**يعيد:**

قيم الصوت المُفكّكة ذات الشكل `(batch_size, channels, num_samples)` التي تم الحصول عليها باستخدام جزء المُفكِّك في Xcodec.

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

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

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L489)

**المعاملات:**

input_values (`torch.Tensor` من الشكل `(batch_size, channels, num_samples)`) : قيم رقمية عشرية لموجة الصوت المدخلة.

bandwidth (`float`، *اختياري*) : عرض النطاق الترددي المستهدف بوحدة (kbps) يدعم فقط القيم الموجودة في `config.target_bandwidths`. القيمة الافتراضية هي أعلى عرض نطاق ترددي متاح `4.0` kbps.

return_dict (`bool`، *اختياري*) : ما إذا كان يجب إرجاع [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput) أم لا.

**يعيد:**

`torch.LongTensor` من الشكل `(batch_size, num_quantizers, codes_length)` يحتوي على رموز الصوت المشفرة المنفصلة.

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

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L569)

**المعاملات:**

input_values (`torch.Tensor` من الشكل `(batch_size, channels, num_samples)`) : القيم العائمة الخام لموجة الصوت المدخلة.

audio_codes (`torch.LongTensor` من الشكل `(batch_size, num_quantizers, codes_length)` : فهارس رموز منفصلة محسوبة باستخدام `model.encode`.

bandwidth (`float`، *اختياري*) : عرض النطاق الترددي المستهدف بالكيلوبت في الثانية. يجب أن يكون أحد قيم `config.target_bandwidths`. القيمة الافتراضية هي أعلى عرض نطاق ترددي متاح.

bandwidth (`float`، *اختياري*) : عرض النطاق الترددي المستهدف بالكيلوبت في الثانية. يجب أن يكون أحد قيم `config.target_bandwidths`. القيمة الافتراضية هي أعلى عرض نطاق ترددي متاح.

**يعيد:** `XcodecOutput` أو مجموعة `(audio_codes, audio_values)`

- `audio_codes` من الشكل `(batch_size, num_quantizers, codes_length)`: الرموز المنفصلة المُكمّاة.
- `audio_values` من الشكل `(batch_size, channels, num_samples)`: موجة الصوت المُعاد بناؤها بناءً على الرموز.

تتجاوز طريقة [XcodecModel](/docs/transformers/main/ar/model_doc/xcodec#transformers.XcodecModel) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن `Module` بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

مثال:

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