# DAC

## نظرة عامة

قُدِّم نموذج DAC في [Descript Audio Codec: High-Fidelity Audio Compression with Improved RVQGAN](https://huggingface.co/papers/2306.06546) بواسطة Rithesh Kumar وPrem Seetharaman وAlejandro Luebs وIshaan Kumar وKundan Kumar.

يُعدّ نموذج Descript Audio Codec (DAC) أداةً قوية لضغط بيانات الصوت، مما يجعله كفاءةً عاليةً في التخزين والنقل. فعن طريق ضغط صوت بتردد 44.1 KHz إلى رموز (tokens) باستخدام عرض نطاق لا يتجاوز 8kbps، يتيح نموذج DAC معالجةً صوتيةً عالية الجودة مع تقليل بصمة البيانات بشكل كبير. وهذا مفيدٌ بشكل خاص في السيناريوهات التي يكون فيها عرض النطاق محدودًا أو مساحة التخزين ثمينة، كما هو الحال في تطبيقات البث المباشر، والاجتماعات عن بُعد، وأرشفة مجموعات البيانات الصوتية الكبيرة.

المستخلص من الورقة البحثية هو كالتالي:

*تم استخدام نماذج اللغة بنجاح لنمذجة الإشارات الطبيعية، مثل الصور والكلام والموسيقى. يُعدّ نموذج الضغط العصبي عالي الجودة مكوّنًا رئيسيًا في هذه النماذج، إذ يمكنه ضغط الإشارات الطبيعية عالية الأبعاد إلى رموز منفصلة ذات أبعاد أقل. وفي هذا السياق، نطرح خوارزمية ضغط صوتي عصبي عالمية عالية الدقة تحقق ضغطًا بنسبة ~90x للصوت بتردد 44.1 KHz إلى رموز بعرض نطاق يبلغ 8kbps فقط. نحقق ذلك من خلال دمج التطورات في توليد الصوت عالي الدقة مع تقنيات تكميم متجهي أفضل من مجال الصور، إلى جانب تحسينات على خسائر الخصومة وإعادة البناء. نضغط جميع المجالات (الكلام، البيئة، الموسيقى، إلخ) باستخدام نموذج عالمي واحد، مما يجعله قابلًا للتطبيق على نطاق واسع في النمذجة التوليدية لجميع الأصوات. نقارن بخوارزميات الضغط الصوتي المنافسة، ونجد أن منهجيتنا تتفوق عليها بشكل كبير. نوفر اختبارات استنفاد شاملة لكل خيار تصميمي، بالإضافة إلى أكواد مفتوحة المصدر وأوزان النماذج المدربة. نأمل أن تُمهّد أعمالنا الطريق للجيل القادم من نمذجة الصوت عالي الدقة.*

تمت مساهمة هذا النموذج من قِبل [Kamil Akesbi](https://huggingface.co/kamilakesbi). يمكن العثور على الكود الأصلي [هنا](https://github.com/descriptinc/descript-audio-codec/tree/main?tab=readme-ov-file).

## هيكل النموذج

يتكوّن نموذج Descript Audio Codec (DAC) من ثلاث مراحل متميزة:

1. نموذج المُشفِّر: يقوم هذا الممرّض بضغط الصوت المُدخل، مما يقلّل حجمه مع الاحتفاظ بالمعلومات الأساسية.
2. نموذج مُكمِّم المتجهات المتبقية (RVQ): يعمل بالتوازي مع المُشفِّر، حيث يُكمِّم الرموز الكامنة للصوت، مما يُحسّن الضغط ويضمن إعادة بناء عالية الجودة.
3. نموذج المُفكِّك: يعيد هذا المرحلية النهائية بناء الصوت من شكله المضغوط، مستعيدًا إياه إلى حالة تشبه المدخل الأصلي بشكل وثيق.

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

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

```python
from datasets import Audio, load_dataset

from transformers import AutoProcessor, DacModel

librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

model = DacModel.from_pretrained("descript/dac_16khz", device_map="auto")
processor = AutoProcessor.from_pretrained("descript/dac_16khz")
librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
audio_sample = librispeech_dummy[-1]["audio"]["array"]
inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt").to(model.device)

encoder_outputs = model.encode(inputs["input_values"])
# Get the intermediate audio codes
audio_codes = encoder_outputs.audio_codes
# Reconstruct the audio from its quantized representation
audio_values = model.decode(encoder_outputs.quantized_representation)
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_values
```

## DacConfig[[transformers.DacConfig]]

#### transformers.DacConfig[[transformers.DacConfig]]

```python
transformers.DacConfig(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, encoder_hidden_size: int = 64, downsampling_ratios: list[int] | tuple[int, ...] = (2, 4, 8, 8), decoder_hidden_size: int = 1536, n_codebooks: int = 9, codebook_size: int = 1024, codebook_dim: int = 8, quantizer_dropout: float | int = 0.0, commitment_loss_weight: float = 0.25, codebook_loss_weight: float = 1.0, sampling_rate: int = 16000)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/configuration_dac.py#L27)

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

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

downsampling_ratios (`list[int]`، *اختياري*، القيمة الافتراضية `[2, 4, 8, 8]`) : النسب المستخدمة في عملية تقليل العينات (downsampling) داخل المُشفِّر (encoder). تُستخدم هذه النسب بالترتيب العكسي في عملية زيادة العينات (upsampling) داخل المُفكِّك (decoder).

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

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

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

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

quantizer_dropout (`bool`، *اختياري*، القيمة الافتراضية 0) : ما إذا كان سيتم تطبيق dropout على المُكمِّم (quantizer).

commitment_loss_weight (`float`، *اختياري*، القيمة الافتراضية 0.25) : وزن حد خسارة الالتزام في دالة خسارة VQVAE.

codebook_loss_weight (`float`، *اختياري*، القيمة الافتراضية 1.0) : وزن حد خسارة الكتاب الرمزي في دالة خسارة VQVAE.

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

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

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

مثال:

```python
>>> from transformers import DacModel, DacConfig

>>> # Initializing a "descript/dac_16khz" style configuration
>>> configuration = DacConfig()

>>> # Initializing a model (with random weights) from the "descript/dac_16khz" style configuration
>>> model = DacModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## DacFeatureExtractor[[transformers.DacFeatureExtractor]]

#### transformers.DacFeatureExtractor[[transformers.DacFeatureExtractor]]

```python
transformers.DacFeatureExtractor(feature_size: int = 1, sampling_rate: int = 16000, padding_value: float = 0.0, hop_length: int = 512, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/feature_extraction_dac.py#L26)

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

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

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

padding_value (`float`، *اختياري*، القيمة الافتراضية 0.0) : القيمة المستخدمة للتعبئة.

hop_length (`int`، *اختياري*، القيمة الافتراضية 512) : طول التداخل بين النوافذ المتتالية.

ينشئ مستخرج ميزات Dac.

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

#### __call__[[transformers.DacFeatureExtractor.__call__]]

```python
__call__(raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str | transformers.utils.generic.PaddingStrategy | None = None, truncation: bool | None = False, max_length: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/feature_extraction_dac.py#L57)

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

raw_audio (`np.ndarray`، `list[float]`، `list[np.ndarray]`، `list[list[float]]`) : التسلسل أو الدفعة من التسلسلات المراد معالجتها. يمكن أن يكون كل تسلسل مصفوفة numpy، أو قائمة من قيم float، أو قائمة من مصفوفات numpy، أو قائمة من قوائم قيم float. يجب أن تكون المصفوفة numpy من الشكل `(num_samples,)` للصوت أحادي القناة (`feature_size = 1`)، أو `(2, num_samples)` للصوت ثنائي القناة (`feature_size = 2`).

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

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

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

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

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

الطريقة الرئيسية لتحويل السلسلة أو السلاسل إلى ميزات وتجهيزها للنموذج.

## DacModel[[transformers.DacModel]]

#### transformers.DacModel[[transformers.DacModel]]

```python
transformers.DacModel(config: DacConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/modeling_dac.py#L563)

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

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

نموذج DAC (Descript Audio Codec).

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

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

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

```python
decode(quantized_representation: typing.Optional[torch.Tensor] = None, audio_codes: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/modeling_dac.py#L609)

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

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

audio_codes (`torch.Tensor` من الشكل `(batch_size, num_codebooks, time_steps)`، *اختياري*) : فهارس كُتُب الرموز لكل كتاب رموز، وتمثل التمثيل المنفصل المُكمَّم للإدخال. يجب تقديم هذا المعامل إذا كنت ترغب في فك الترميز مباشرةً من رموز الصوت (سيؤدي ذلك إلى تجاوز quantized_representation).

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع `DacDecoderOutput` بدلاً من tuple عادي.

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

`DacDecoderOutput` أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([DacConfig](/docs/transformers/v5.23.0/ar/model_doc/dac#transformers.DacConfig)) والمدخلات.

- **audio_values** (`torch.Tensor` من الشكل `(batch_size, input_length)`، *اختياري*) -- قيم الصوت المُفكّكة، المُستخرجة باستخدام جزء المُفكّك في Dac.

#### encode[[transformers.DacModel.encode]]

```python
encode(input_values: Tensor, n_quantizers: int | None = None, return_dict: bool | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/modeling_dac.py#L582)

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

input_values (`torch.Tensor of shape `(batch_size, 1, time_steps)`) : بيانات الصوت المدخلة للتشفير،

n_quantizers (`int`, *اختياري*) : عدد مُكمّسات (quantizers) التي سيتم استخدامها. إذا كانت القيمة None، فسيتم استخدام جميع المُكمّسات. القيمة الافتراضية هي None.

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

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

`DacEncoderOutput` أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([DacConfig](/docs/transformers/v5.23.0/ar/model_doc/dac#transformers.DacConfig)) والمدخلات.

- **loss** (`torch.Tensor`، *اختياري*) -- الخسارة من نموذج المُشفِّر، وتتكون من المزيج الموزون لخسارتَي الالتزام وكتاب الرموز.
- **quantized_representation** (`torch.Tensor` of shape `(batch_size, dimension, time_steps)`, *اختياري*) -- تمثيل مستمر مُكمَّم للإدخال.
- **audio_codes** (`torch.Tensor` من الشكل `(batch_size, num_codebooks, time_steps)`، *اختياري*) -- فهارس كودبوك لكل كودبوك (تمثيل منفصل مُكمَّم للإدخال).
- **projected_latents** (`torch.Tensor` of shape `(batch_size, num_codebooks * dimension, time_steps)`, *اختياري*) -- الكامنات المُسقطَة (تمثيل مستمر للإدخال قبل التكميم).

#### forward[[transformers.DacModel.forward]]

```python
forward(input_values: Tensor, n_quantizers: int | None = None, return_dict: bool | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/dac/modeling_dac.py#L642)

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

input_values (`torch.Tensor` من الشكل `(batch_size, 1, time_steps)`) : بيانات الصوت المراد ترميزها.

n_quantizers (`int`, *اختياري*) : عدد مُكمّسات (quantizers) التي يجب استخدامها. إذا كانت `None`، تُستخدم جميع المُكمّسات. القيمة الافتراضية هي `None`.

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

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

`DacOutput` أو مجموعة (tuple) من `torch.Tensor` (في حال تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) تتكون من عناصر مختلفة اعتماداً على الإعدادات ([DacConfig](/docs/transformers/v5.23.0/ar/model_doc/dac#transformers.DacConfig)) والمدخلات.

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

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

- **loss** (`torch.Tensor`، *اختياري*) -- الخسارة من نموذج المُشفِّر، وتتكون من المزيج الموزون لخسارتَي الالتزام وكتاب الرموز.
- **audio_values** (`torch.Tensor` من الشكل `(batch_size, input_length)`) -- بيانات الصوت المُعاد بناؤها.
- **quantized_representation** (`torch.Tensor` من الشكل `(batch_size, dimension, time_steps)`) -- تمثيل مستمر مُكمَّم للإدخال.
- **audio_codes** (`torch.LongTensor` من الشكل `(batch_size, num_codebooks, time_steps)`) -- فهارس كودبوك لكل كودبوك (تمثيل منفصل مُكمَّم للإدخال).
- **projected_latents** (`torch.Tensor` من الشكل `(batch_size, num_codebooks * dimension, time_steps)`) -- الكامنات المُسقطَة (تمثيل مستمر للإدخال قبل التكميم).

أمثلة:

```python
>>> from datasets import load_dataset, Audio
>>> from transformers import DacModel, AutoProcessor
>>> librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

>>> model = DacModel.from_pretrained("descript/dac_16khz")
>>> processor = AutoProcessor.from_pretrained("descript/dac_16khz")
>>> librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
>>> audio_sample = librispeech_dummy[-1]["audio"]["array"]
>>> inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt")

>>> encoder_outputs = model.encode(inputs["input_values"])
>>> # Get the intermediate audio codes
>>> audio_codes = encoder_outputs.audio_codes
>>> # Reconstruct the audio from its quantized representation
>>> audio_values = model.decode(encoder_outputs.quantized_representation)
>>> # or the equivalent with a forward pass
>>> audio_values = model(inputs["input_values"]).audio_values
```

