# X-Codec2

## نظرة عامة

قُدِّم نموذج X-Codec2 في [Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis](https://huggingface.co/papers/2502.04128).

X-Codec2 هو مشفّر صوتي عصبي مصمّم لتحسين تركيب الكلام وتوليد الصوت بشكل عام في خطوط أنابيب نماذج اللغة الكبيرة (LLM). وهو يوسّع X-Codec الأصلي من خلال تحسين طريقة دمج المعلومات الدلالية والصوتية وتحويلها إلى رموز، مما يتيح تمثيلاً صوتياً فعالاً وعالياً الدقة.

حول معماريته:
- **الترميز الموحّد الدلالي-الصوتي**: يدمج X-Codec2 المخرجات من مُرمِّز دلالي (مثل Wav2Vec2-BERT) ومُرمِّز صوتي في تضمين واحد، لالتقاط كلٍّ من المعنى على مستوى عالٍ (مثل محتوى النص، والعاطفة) وتفاصيل الصوت على مستوى منخفض (مثل طبقة الصوت).
- **تكميم الميزات القياسي أحادي المرحلة (FSQ)**: على عكس تكميم VQ المتبقي متعدد الطبقات المستخدم في معظم الأساليب (مثل [DAC](./dac)، [EnCodec](./encodec)، [X-Codec](./xcodec)، [Mimi](./mimi))، يستخدم X-Codec2 طبقة واحدة من تكميم الميزات القياسي (FSQ) من أجل الاستقرار والتوافق مع نماذج LLM السببية ذاتية التراجع.
- **تصميم متوافق مع نماذج التحويل**: يتوافق بنية الرموز أحادية البعد في X-Codec2 بشكل طبيعي مع النمذجة الذاتية في نماذج اللغة الكبيرة مثل LLaMA، مما يحسّن كفاءة التدريب والتوافق مع المهام اللاحقة.

يتوفر نقطة تفتيش للنموذج في [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf).

تمت مساهمة هذا النموذج من قِبل [Eric Bezzam](https://huggingface.co/bezzam) و[Steven Zheng](https://huggingface.co/Steveeeeeeen). يمكن العثور على كود النمذجة الأصلي [هنا](https://huggingface.co/HKUSTAudio/xcodec2/blob/main/modeling_xcodec2.py)، بينما كود التدريب الخاص بهما [هنا](https://github.com/zhenye234/X-Codec-2.0).

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

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

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

### المعالجة الدفعية

تدعم هذه النسخة أيضًا إدخالًا مجمّعًا (batched input)، على عكس [الإصدار](https://huggingface.co/HKUSTAudio/xcodec2) الأصلي!

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

### التسريع باستخدام `torch.compile`

يمكنك تسريع الاستدلال باستخدام [`torch.compile`](https://pytorch.org/docs/stable/generated/torch.compile.html). ستكون الاستدعاءات الأولى أبطأ بسبب تكاليف التجميع، لكن الاستدعاءات اللاحقة ستكون أسرع.

على بطاقة A100، لاحظنا تسريعًا بنسبة ~1.35 لحجم دفعة يساوي 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))
```

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

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

hidden_size (`int`، *اختياري*، القيمة الافتراضية `1024`) : بُعد التمثيلات المخفية.

intermediate_size (`int`، *اختياري*، القيمة الافتراضية `4096`) : بُعد تمثيلات MLP.

num_hidden_layers (`int`، *اختياري*، القيمة الافتراضية `12`) : عدد الطبقات المخفية في مُفكِّك Transformer.

num_attention_heads (`int`، *اختياري*، القيمة الافتراضية `16`) : عدد رؤوس الانتباه في كل طبقة انتباه داخل مُفكِّك Transformer.

num_key_value_heads (`int`، *اختياري*، القيمة الافتراضية `16`) : هذا هو عدد رؤوس key_value التي يجب استخدامها لتنفيذ Grouped Query Attention. إذا كان `num_key_value_heads=num_attention_heads`، فسيستخدم النموذج Multi Head Attention (MHA)، وإذا كان `num_key_value_heads=1` فسيستخدم النموذج Multi Query Attention (MQA)، وإلا فسيتم استخدام GQA. عند تحويل نقطة تحقق متعددة الرؤوس إلى نقطة تحقق GQA، يجب بناء كل مجموعة من رؤوس key و value عن طريق meanpooling جميع الرؤوس الأصلية داخل تلك المجموعة. لمزيد من التفاصيل، راجع [هذا الورق](https://huggingface.co/papers/2305.13245). إذا لم يتم تحديد القيمة، فستكون القيمة الافتراضية هي `num_attention_heads`.

hidden_act (`str`، *اختياري*، القيمة الافتراضية `silu`) : دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، `"gelu"`، `"relu"`، `"silu"`، وما إلى ذلك.

max_position_embeddings (`int`، *اختياري*، القيمة الافتراضية `4096`) : الحد الأقصى لطول التسلسل الذي قد يُستخدم به هذا النموذج على الإطلاق.

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

rms_norm_eps (`float`، *اختياري*، القيمة الافتراضية `1e-06`) : قيمة الإيبسلون المستخدمة في طبقات تطبيع rms.

pad_token_id (`int`, *اختياري*) : معرّف الرمز (Token id) المستخدم للتعبئة (padding) في المفردات.

tie_word_embeddings (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب ربط ترميزات الأوزان وفقاً لخريطة `tied_weights_keys` الخاصة بالنموذج.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`، *اختياري*) : قاموس يحتوي على معاملات التهيئة الخاصة بتضمينات RoPE. يجب أن يحتوي القاموس على قيمة لـ `rope_theta`، وبشكل اختياري معاملات تُستخدم للتوسيع في حال رغبتَ في استخدام RoPE مع `max_position_embeddings` أطول.

attention_bias (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم استخدام انحياز في طبقات الإسقاط للاستعلام والمفتاح والقيمة والمخرجات أثناء الانتباه الذاتي.

attention_dropout (`Union[int, float]`، *اختياري*، القيمة الافتراضية `0.0`) : نسبة dropout لاحتمالات الانتباه.

head_dim (`int`, *اختياري*, الافتراضي هو `64`) : أبعاد رأس الانتباه. إذا كانت None، فسيكون الافتراضي hidden_size // num_attention_heads

encoder_hidden_size (`int`، *اختياري*، القيمة الافتراضية `48`) : بُعد التمثيلات المخفية.

downsampling_ratios (`list[int]`، *اختياري*، القيمة الافتراضية `[2, 2, 4, 4, 5]`) : النسب المستخدمة في تقليل حجم البيانات في المُشفِّر.

semantic_model_config (`Union[Dict, Wav2Vec2BertConfig]`, *اختياري*) : نسخة من كائن التهيئة لنموذج الدلالات (Wav2Vec2BertConfig).

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

activation_dropout (`float`، *اختياري*، القيمة الافتراضية `0.1`) : نسبة الإسقاط (dropout) للتفعيلات داخل الطبقة المتصلة بالكامل.

quantization_dim (`int`، *اختياري*، القيمة الافتراضية 2048) : بُعد دفتر رموز التكميم المتجهي.

quantization_levels (`list[int]`، *اختياري*، القيمة الافتراضية `[4, 4, 4, 4, 4, 4, 4, 4]`) : مستويات لكتاب الترميز في التكميم المتجهي.

هذه فئة الإعدادات المخزنة لإعدادات نموذج Xcodec2Model. تُستخدم لتوليد نموذج Xcodec2 وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن إنشاء فئة الإعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ [HKUSTAudio/xcodec2-hf](https://huggingface.co/HKUSTAudio/xcodec2-hf)

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

مثال:

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

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

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

feature_size (`int`، *اختياري*، القيمة الافتراضية 80) : بُعد الميزة للميزات المستخرجة.

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

padding_value (`float`، *اختياري*، القيمة الافتراضية 1.0) : القيمة المستخدمة لملء متجهات الحشو (padding) لطييف الميّل (mel spectrogram).

hop_length (`int`، *اختياري*، القيمة الافتراضية 320) : عدد عينات الصوت المُرمّزة في كل إطار. يعادل حاصل ضرب نسب تقليل العينة. مطلوب لتعبئة مدخلات المُرمِّز الصوتي.

ينشئ مستخرج ميزات Xcodec2، الذي يحسب ميزات بنك مرشحات ميل للمشفّر الدلالي والصوت المملوء للمشفّر الصوتي.

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

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

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

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

audio (`np.ndarray`، `torch.Tensor`، `list[np.ndarray]`، `list[torch.Tensor]`) : مصفوفة Numpy أو tensor من torch بأبعاد (num_channels, sequence_length). يمكن أيضًا تقديم قائمة من هذه المصفوفات أو tensors لمجموعة من المدخلات.

padding (`bool` أو `str` أو [PaddingStrategy](/docs/transformers/main/ar/internal/file_utils#transformers.utils.PaddingStrategy)، *اختياري*، القيمة الافتراضية `True`) : اختيار استراتيجية لحشو التسلسلات المُعادَة (وفقًا لجانب الحشو وفهرس الحشو الخاص بالنموذج) من بين الخيارات التالية: - `True` أو `'longest'`: الحشو حتى أطول تسلسل في الدفعة (أو عدم الحشو إذا تم تقديم تسلسل واحد فقط). - `'max_length'`: الحشو حتى الحد الأقصى للطول المحدد بالحجة `max_length` أو حتى الحد الأقصى المقبول لطول الإدخال للنموذج إذا لم يتم تقديم تلك الحجة. - `False` أو `'do_not_pad'` (الافتراضي): لا يوجد حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).

max_length (`int`، *اختياري*) : الحد الأقصى لطول القائمة المُعاد، وطول الحشو اختياريًا (انظر أعلاه).

truncation (`bool`) : يُفعّل القصّ لقطع تسلسلات الإدخال الأطول من *max_length* إلى *max_length*.

return_tensors (`str` أو [TensorType](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType)، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات بدلاً من قائمة من الأعداد الصحيحة بلغة بايثون. القيم المقبولة هي: - `'tf'`: يُرجع كائنات `tf.constant` من TensorFlow. - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من Numpy.

sampling_rate (`int`, *اختياري*) : معدل أخذ العينات الذي تم به أخذ عينات إدخال `audio`. يُوصى بشدة بتمرير `sampling_rate` عند استدعاء الأمامي لمنع الأخطاء الصامتة.

device (`str`، *اختياري*، القيمة الافتراضية `"cpu"`) : الجهاز الخاص بمصفوفات PyTorch أثناء استخراج ميزات بنك مرشحات ميل.

kwargs (*اختياري*) : قاموس المتبقية من حُجج الكلمات المفتاحية التي سيتم تمريرها إلى مُجزّئ النص أو مستخرج الميزات.

## Xcodec2Model[[transformers.Xcodec2Model]]

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

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

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

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

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

نموذج Xcodec2، وهو شيفرة صوتية عصبية.

يرث هذا النموذج من [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.Xcodec2Model.decode]]

```python
decode(audio_codes: typing.Optional[torch.Tensor] = None, latents: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

latents (`torch.Tensor` من الشكل `(batch_size, dimension, time_steps)`، *اختياري*) : تمثيل مستمر مُكمَّم للإدخال.

**يعيد:** `Xcodec2DecoderOutput` أو `tuple(torch.Tensor)`

`Xcodec2DecoderOutput` أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) تتكون من عناصر مختلفة اعتماداً على الإعداد (`None`) والمدخلات.

- **audio_values** (`torch.Tensor` من الشكل `(batch_size, 1, segment_length)`، *اختياري*) -- قيم موجة الصوت المُفكّكة في مجال الزمن، والمُحصَلة عن طريق تحويل الرموز المنفصلة مرة أخرى إلى إشارات صوتية مستمرة. يمثل هذا الصوت المُعاد بناؤه والذي يمكن تشغيله.

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

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

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

input_values (`torch.Tensor` من الشكل `(batch_size, 1, sequence_length)`) : موجة الصوت المدخلة.

input_features (`torch.Tensor` من الشكل `(batch_size, mel_bins, time_steps)`) : مطياف ميل الصوتي المدخل للتشفير الدلالي.

padding_mask (`torch.Tensor` من الشكل `(batch_size, 1, sequence_length)`) : قناع التعبئة (Padding mask) المستخدم لتعبئة `input_values`.

input_features_mask (`torch.Tensor` من الشكل `(batch_size, time_steps)`، *اختياري*) : قناع الانتباه (Attention mask) لإمداد الطيف الصوتي (spectrogram) إلى المُشفِّر الدلالي (semantic encoder). `1` للإطارات الصالحة، و`0` للتعبئة (padding).

output_latents (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب إرجاع التمثيل الكامن المستمر من المُكمِّم.

**يعيد:** `Xcodec2EncoderOutput` أو `tuple(torch.Tensor)`

`Xcodec2EncoderOutput` أو مجموعة مرتبة من `torch.Tensor` (في حال تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد (`None`) والمدخلات.

- **audio_codes** (`torch.LongTensor` من الشكل `(batch_size, 1, codes_length)`، *اختياري*) -- تمثيلات رموز منفصلة محسوبة باستخدام `model.encode`. تمثل هذه الرموز الشكل المضغوط والمكمَّم للإشارة الصوتية المدخلة، ويمكن استخدامها للتخزين أو النقل أو التوليد.
- **latents** (`torch.Tensor` من الشكل `(batch_size, dimension, time_steps)`) -- تمثيل مستمر مُكمَّم لتضمين الإدخال.
- **audio_codes_mask** (`torch.int32` of shape `(batch_size, 1, codes_length)`, *اختياري*) -- `padding_mask` مُخفَّض الدقة لتحديد رموز الصوت الصالحة في `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'>)
```

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

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

input_values (`torch.Tensor` من الشكل `(batch_size, 1, sequence_length)`) : موجة الصوت المدخلة.

input_features (`torch.Tensor` من الشكل `(batch_size, mel_bins, time_steps)`) : مطياف ميل الصوتي المدخل للتشفير الدلالي.

padding_mask (`torch.Tensor` من الشكل `(batch_size, 1, sequence_length)`) : قناع التعبئة (Padding mask) المستخدم لتعبئة `input_values`.

input_features_mask (`torch.Tensor` من الشكل `(batch_size, time_steps)`، *اختياري*) : قناع الانتباه (Attention mask) لإمداد الطيف الصوتي (spectrogram) إلى المُشفِّر الدلالي (semantic encoder). `1` للإطارات الصالحة، و`0` للتعبئة (padding).

output_latents (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان يجب إرجاع التمثيل الكامن المستمر من المُكمِّم.

**يعيد:** `Xcodec2Output` أو `tuple(torch.Tensor)`

A `Xcodec2Output` or a tuple of `torch.Tensor` (if `return_dict=False` is passed or when `config.return_dict=False`) comprising various elements depending on the configuration (`None`) and inputs.

تُعيد طريقة [Xcodec2Model](/docs/transformers/main/ar/model_doc/xcodec2#transformers.Xcodec2Model) الخاصة بالتقديم (forward) تعريف الطريقة الخاصة `__call__`.

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

- **audio_values** (`torch.Tensor` من الشكل `(batch_size, 1, sequence_length)`، *اختياري*) -- قيم موجة الصوت المُفكّكة في مجال الزمن، والمُستخرجة باستخدام جزء المُفكّك في Xcodec2. تمثّل هذه القيم إشارة الصوت المُعاد بناؤها.
- **audio_codes** (`torch.LongTensor` من الشكل `(batch_size, 1, codes_length)`، *اختياري*) -- تمثيلات رموز منفصلة محسوبة باستخدام `model.encode`. هذه هي التمثيلات الكمّية للصوت المُدخل، وتُستخدم للمعالجة أو التوليد اللاحق.
- **latents** (`torch.Tensor` من الشكل `(batch_size, dimension, time_steps)`) -- تمثيل مستمر مُكمَّم لتضمين الإدخال.
- **audio_codes_mask** (`torch.int32` of shape `(batch_size, 1, codes_length)`, *اختياري*) -- `padding_mask` مُخفَّض الدقة لتحديد رموز الصوت الصالحة في `audio_codes`.

أمثلة:

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