# أدوات مساعدة لـ `FeatureExtractors`

تُدرج هذه الصفحة جميع دوال الأداة التي يمكن أن يستخدمها `FeatureExtractor` الصوتي لحساب ميزات خاصة من الصوت الخام باستخدام خوارزميات شائعة مثل *Short Time Fourier Transform* أو *log mel spectrogram*.

لا تُفيد معظم تلك العناصر إلا إذا كنت تدرس كود معالجات الصوت في المكتبة.

## تحويلات الصوت[[transformers.audio_utils.hertz_to_mel]]

#### transformers.audio_utils.hertz_to_mel[[transformers.audio_utils.hertz_to_mel]]

```python
transformers.audio_utils.hertz_to_mel(freq: float | numpy.ndarray, mel_scale: str = 'htk')
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L554)

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

freq (`float` أو `np.ndarray`) : التردد، أو عدة ترددات، بالهرتز (Hz).

mel_scale (`str`، *اختياري*، القيمة الافتراضية `"htk"`) : مقياس ترددات ميل الذي يجب استخدامه، `"htk"` أو `"kaldi"` أو `"slaney"`.

**يعيد:** `float` أو `np.ndarray`

الترددات على مقياس ميل.

تحويل التردد من هرتز إلى ميل.

#### transformers.audio_utils.mel_to_hertz[[transformers.audio_utils.mel_to_hertz]]

```python
transformers.audio_utils.mel_to_hertz(mels: float | numpy.ndarray, mel_scale: str = 'htk')
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L590)

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

mels (`float` أو `np.ndarray`) : التردد، أو عدة ترددات، بوحدة الميل.

mel_scale (`str`، *اختياري*، `"htk"`) : مقياس الترددات الملّي الذي سيتم استخدامه، `"htk"` أو `"kaldi"` أو `"slaney"`.

**يعيد:** `float` أو `np.ndarray`

الترددات بالهرتز.

تحويل التردد من وحدة ميل إلى وحدة هرتز.

#### transformers.audio_utils.mel_filter_bank[[transformers.audio_utils.mel_filter_bank]]

```python
transformers.audio_utils.mel_filter_bank(num_frequency_bins: int, num_mel_filters: int, min_frequency: float, max_frequency: float, sampling_rate: int, norm: str | None = None, mel_scale: str = 'htk', triangularize_in_mel_space: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L744)

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

num_frequency_bins (`int`) : عدد خلايا التردد (يجب أن يكون مطابقًا لـ `n_fft // 2 + 1` حيث `n_fft` هو حجم تحويل فورييه المستخدم لحساب الطيف الصوتي).

num_mel_filters (`int`) : عدد مرشحات ميل (mel) التي سيتم إنشاؤها.

min_frequency (`float`) : أدنى تردد ذي أهمية بالهرتز.

max_frequency (`float`) : أعلى تردد ذي أهمية بالهرتز. يجب ألا يتجاوز `sampling_rate / 2`.

sampling_rate (`int`) : معدل أخذ العينات لموجة الصوت.

norm (`str`، *اختياري*) : إذا كان `"slaney"`، قسّم أوزان المثلثات المييلية على عرض نطاق المييل (تطبيع المساحة).

mel_scale (`str`، *اختياري*، القيمة الافتراضية `"htk"`) : مقياس ترددات ميل الذي يجب استخدامه، `"htk"` أو `"kaldi"` أو `"slaney"`.

triangularize_in_mel_space (`bool`، *اختياري*، القيمة الافتراضية `False`) : إذا تم تفعيل هذا الخيار، يُطبَّق المرشح المثلثي في فضاء mel بدلاً من فضاء التردد. يجب ضبطه على `true` للحصول على النتائج نفسها التي يعطيها `torchaudio` عند حساب مرشحات mel.

**يعيد:** `np.ndarray` من الشكل (`num_frequency_bins`, `num_mel_filters`)

مصفوفة بنك المرشحات المثلثية. هذه مصفوفة إسقاط للانتقال من الطيف الصوتي إلى طيف المِل الصوتي.

يُنشئ مصفوفة تحويل لخلية الترددات المستخدمة للحصول على طيف ميل. يُطلق على هذه المصفوفة اسم *بنك مرشحات ميل*، وتوجد تنفيذهات مختلفة تختلف في عدد المرشحات، وشكل المرشحات، وطريقة توزيع المرشحات، وعرض النطاق الترددي للمرشحات، وطريقة تشويه الطيف. تهدف هذه الميزات إلى تقريب الإدراك البشري غير الخطي للتغير في طبقة الصوت بالنسبة للتردد.

تم تقديم مجموعات مختلفة من مرشحات ميل في الأدبيات. التغيرات التالية مدعومة:

- MFCC FB-20: أُدخلت في عام 1980 على يد ديفيس وميرملشتاين، وتفترض تردد أخذ عينات يبلغ 10 كيلو هرتز ونطاق تردد صوتي قدره `[0, 4600]` هرتز.
- MFCC FB-24 HTK: من مجموعة أدوات كامبريدج لنماذج ماركوف المخفية (HTK) (1995) يستخدم بنك مرشحات يتكون من 24 مرشحًا لعرض نطاق صوتي يبلغ `[0, 8000]` هرتز. يفترض ذلك معدل أخذ عينات ≥ 16 كيلوهرتز.
- MFCC FB-40: من Auditory Toolbox لـ MATLAB الذي كتبه Slaney في عام 1998، يفترض معدل أخذ عينات يبلغ 16 kHz ونطاق ترددات الكلام `[133, 6854]` هرتز. تتضمن هذه النسخة أيضاً تطبيع المساحة.
- يفترض  HFCC-E FB-29 (معاملات السبترال لعامل الإنسان) لـ Skowronski و Harris (2004) معدل أخذ عينات يبلغ 12.5 kHz ونطاق تردد صوتي يبلغ `[0, 6250]` هرتز.

تم تكييف هذا الكود من *torchaudio* و*librosa*. لاحظ أن المعلمات الافتراضية لـ`melscale_fbanks` في torchaudio تنفّذ مرشحات `"htk"` بينما يستخدم librosa تنفيذ `"slaney"`.

#### transformers.audio_utils.optimal_fft_length[[transformers.audio_utils.optimal_fft_length]]

```python
transformers.audio_utils.optimal_fft_length(window_length: int)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L838)

يجد أفضل حجم لإدخال FFT لطول نافذة محدد `window_length`. تستقبل هذه الدالة طول نافذة معيّن، وإذا لم يكن قوة للعدد 2، تُقرّبه إلى أعلى قوة للعدد 2.

يعمل خوارزمية FFT بأسرع ما يمكن عندما يكون طول المدخلات قوة للعدد اثنين، وقد يكون هذا الطول أكبر من حجم النافذة أو إطار التحليل. على سبيل المثال، إذا كانت النافذة 400 عينة، فإن استخدام حجم مدخلات FFT قدره 512 عينة يكون أكثر مثالية من حجم FFT قدره 400 عينة. استخدام حجم FFT أكبر لا يؤثر على الترددات المكتشفة، بل يمنح ببساطة دقة تردد أعلى (أي أن خلايا التردد تكون أصغر).

#### transformers.audio_utils.window_function[[transformers.audio_utils.window_function]]

```python
transformers.audio_utils.window_function(window_length: int, name: str = 'hann', periodic: bool = True, frame_length: int | None = None, center: bool = True)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L851)

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

window_length (`int`) : طول النافذة بالعينات.

name (`str`، *اختياري*، القيمة الافتراضية `"hann"`) : اسم دالة النافذة.

periodic (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كانت النافذة دورية أو متناظرة.

frame_length (`int`, *اختياري*) : طول إطارات التحليل بالعينات. قدّم قيمة لـ`frame_length` إذا كان النافذة أصغر من طول الإطار، حتى يتم ملؤها بالأصفار.

center (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم توسيط النافذة داخل مخزن FFT. يُستخدم فقط عند تقديم `frame_length`.

**يعيد:**

`np.ndarray` من الشكل `(window_length,)` أو `(frame_length,)` يحتوي على النافذة.

يعيد مصفوفة تحتوي على النافذة المحددة. تُستخدم هذه النافذة مع `stft`.

الأنواع المدعومة من النوافذ هي:

- `"boxcar"`: نافذة مستطيلة
- `"hamming"`: نافذة هامينغ
- `"hann"`: نافذة هان
- `"povey"`: نافذة Povey

#### transformers.audio_utils.spectrogram[[transformers.audio_utils.spectrogram]]

```python
transformers.audio_utils.spectrogram(waveform: ndarray, window: ndarray, frame_length: int, hop_length: int, fft_length: int | None = None, power: float | None = 1.0, center: bool = True, pad_mode: str = 'reflect', onesided: bool = True, dither: float = 0.0, preemphasis: float | None = None, mel_filters: numpy.ndarray | None = None, mel_floor: float = 1e-10, log_mel: str | None = None, reference: float = 1.0, min_value: float = 1e-10, db_range: float | None = None, remove_dc_offset: bool = False, dtype: dtype = <class 'numpy.float32'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L915)

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

waveform (`np.ndarray` من الشكل `(length,)`) : الموجة الصوتية المدخلة. يجب أن تكون هذه موجة أحادية (mono) ذات قيم حقيقية فقط.

window (`np.ndarray` من الشكل `(frame_length,)`) : دالة النافذة التي سيتم تطبيقها، بما في ذلك الحشو بالصفر عند الحاجة. قد تكون طول النافذة الفعلي أقصر من `frame_length`، لكننا نفترض أن المصفوفة قد تم حشوها بالصفر بالفعل.

frame_length (`int`) : طول إطارات التحليل بالعينات. في مكتبة librosa يكون هذا دائمًا مساويًا لـ`fft_length`، لكننا نسمح أيضًا بأحجام أصغر.

hop_length (`int`) : الخطوة بين إطارات التحليل المتتالية، مقاسة بعدد العينات.

fft_length (`int`, *اختياري*) : حجم مخزن FFT بالعينات. يحدد هذا العدد عدد نطاقات التردد التي ستحتويها الطيف الصوتي. للحصول على أفضل سرعة، يجب أن يكون هذا الرقم قوة للعدد 2. إذا كان `None`، يتم استخدام `frame_length`.

power (`float`، *اختياري*، القيمة الافتراضية 1.0) : إذا كانت القيمة 1.0، تُرجع طيف السعة. إذا كانت 2.0، تُرجع طيف القدرة. إذا كانت `None`، تُرجع أرقامًا مركبة.

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

pad_mode (`str`، *اختياري*، القيمة الافتراضية `"reflect"`) : وضع الحشو المستخدم عندما تكون `center` هي `True`. القيم الممكنة هي: `"constant"` (الحشو بالأصفار)، `"edge"` (الحشو بقيم الحواف)، `"reflect"` (الحشو بقيم معكوسة).

onesided (`bool`، *اختياري*، القيمة الافتراضية `True`) : إذا كانت القيمة True، يتم حساب الترددات الموجبة فقط وإرجاع طيف ترددي يحتوي على `fft_length // 2 + 1` من الخلايا الترددية. إذا كانت القيمة False، يتم حساب الترددات السالبة أيضًا وإرجاع `fft_length` من الخلايا الترددية.

dither (`float`، *اختياري*، القيمة الافتراضية 0.0) : يضيف تأثير التذبذب (dithering). بمعنى آخر، يضيف ضوضاء غاوسية صغيرة إلى كل إطار. على سبيل المثال، استخدم 4.0 لإضافة تذبذب بتوزيع طبيعي متمركز حول 0.0 مع انحراف معياري قدره 4.0، بينما يعني 0.0 عدم وجود تذبذب. للتذبذب تأثير مشابه لتأثير `mel_floor`. فهو يقلل من قيم log_mel_fbank العالية للإشارات التي تحتوي على مقاطع صفرية صارمة، عندما يكون هناك قطع VAD في الإشارة.

preemphasis (`float`، *اختياري*) : معامل لمرشح تمرير منخفض يطبّق التمهيد المسبق قبل تحويل فورييه المنفصل.

mel_filters (`np.ndarray` من الشكل `(num_freq_bins, num_mel_filters)`، *اختياري*) : بنك مرشحات ميل. إذا تم تقديمه، يُطبَّق هذا البنك المرشحات لإنشاء طيف ميل.

mel_floor (`float`، *اختياري*، القيمة الافتراضية 1e-10) : القيمة الدنيا لبنوك ترددات ميل.

log_mel (`str`, *اختياري*) : كيفية تحويل الطيف الترددي إلى مقياس لوغاريتمي. الخيارات المتاحة هي: `None` (عدم التحويل)، `"log"` (أخذ اللوغاريتم الطبيعي) `"log10"` (أخذ اللوغاريتم ذو الأساس 10)، `"dB"` (التحويل إلى ديسيبل). لا يمكن استخدامه إلا عندما لا تكون `power` قيمة `None`.

reference (`float`، *اختياري*، القيمة الافتراضية 1.0) : يحدد قيمة مطياف الإشارة المدخلات التي تقابل 0 ديسيبل. على سبيل المثال، استخدم `np.max(spectrogram)` لضبط الجزء الأعلى صوتاً على 0 ديسيبل. يجب أن تكون القيمة أكبر من صفر.

min_value (`float`، *اختياري*، القيمة الافتراضية `1e-10`) : سيتم قصّ الطيف الترددي إلى هذه القيمة الدنيا قبل التحويل إلى الديسيبل، لتجنّب حساب `log(0)`. بالنسبة لطيف القدرة، فإن القيمة الافتراضية `1e-10` تقابل حدًّا أدنى قدره -100 ديسيبل. أما بالنسبة لطيف السعة، فإن القيمة `1e-5` تقابل -100 ديسيبل. يجب أن تكون أكبر من صفر.

db_range (`float`، *اختياري*) : يحدد المدى الديناميكي الأقصى بالديسيبل. على سبيل المثال، إذا كان `db_range = 80`، فلن يتجاوز الفرق بين القيمة الذروية وأصغر قيمة 80 ديسيبل. يجب أن يكون أكبر من صفر.

remove_dc_offset (`bool`، *اختياري*) : طرح المتوسط من الموجة الصوتية في كل إطار، ويُطبَّق قبل التمهيد المسبق. يجب ضبطه على `true` للحصول على النتائج نفسها التي يعطيها `torchaudio.compliance.kaldi.fbank` عند حساب مرشحات الميِل.

dtype (`np.dtype`، *اختياري*، القيمة الافتراضية `np.float32`) : نوع البيانات لمصفوفة الطيف. إذا كانت `power` تساوي None، يتم تجاهل هذا الحُجّة وسيكون نوع البيانات `np.complex64`.

**يعيد:**

`nd.array` يحتوي على طيف صوتي (spectrogram) بشكل `(num_frequency_bins, length)` لطيف صوتي عادي، أو بشكل `(num_mel_filters, length)` لطيف صوتي مل (mel spectrogram).

يحسب طيف التردد الزمني (Spectrogram) لموجة صوتية واحدة باستخدام تحويل فورييه قصير المدى.

يمكن لهذه الدالة إنشاء الأنواع التالية من الطيف الصوتي:

- مطياف السعة (`power = 1.0`)
- مطياف القدرة (`power = 2.0`)
- طيف صوتي ذو قيم مركبة (`power = None`)
- مطياف الترددات اللوغاريتمي (استخدم الحجة `log_mel`)
- مطياف الميّل (توفير `mel_filters`)
- مطياف لوج-ميل (قدّم `mel_filters` و`log_mel`)

كيف يعمل هذا:

1. يُقسَّم الموجة المدخلة إلى إطارات بحجم `frame_length` تتداخل جزئياً بمقدار `frame_length
   - عينة hop_length.
2. يُضرب كل إطار في النافذة ثم يُوضع في مخزن ذاكرة بحجم `fft_length`.
3. يُؤخذ تحويل فورييه المنفصل (DFT) لكل إطار مُنَافِذ.
4. تُرتَّب النتائج في صورة طيفية.

نميّز بين "الكتل" التالية من بيانات العينة، حيث يمكن أن يختلف طول كل منها:

- إطار التحليل. هذا هو حجم شرائح الوقت التي يُقسَّم إليها الموجة الصوتية المدخلة.
- النافذة. يتم ضرب كل إطار تحليل في النافذة لتجنب تسرب الطيف.
- خادم إدخال FFT. يحدد طول هذا الخادم عدد خلايا التردد في الطيف الصوتي.

في هذا التنفيذ، يُفترض أن يكون النافذة مُسدَدة بالصفر بحيث تكون بنفس حجم إطار التحليل. يمكن الحصول على نافذة مُسدَدة من `window_function()`. قد يكون مخزن الإدخال الخاص بتحويل فورييه السريع أكبر من إطار التحليل، وعادةً ما يكون القوة التالية للرقم 2.

ملاحظة: هذه الدالة غير مُحسَّنة للسرعة بعد. ينبغي أن تكون متوافقة إلى حد كبير مع `librosa.stft` و`torchaudio.functional.transforms.Spectrogram`، على الرغم من أنها أكثر مرونة بسبب الطرق المختلفة لبناء الطيف.

#### transformers.audio_utils.power_to_db[[transformers.audio_utils.power_to_db]]

```python
transformers.audio_utils.power_to_db(spectrogram: ndarray, reference: float = 1.0, min_value: float = 1e-10, db_range: float | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1337)

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

spectrogram (`np.ndarray`) : طيف القدرة (ميل) المُدخل. لاحظ أن طيف القدرة يكون فيه السعات مربعة!

reference (`float`، *اختياري*، القيمة الافتراضية 1.0) : يحدد قيمة مطياف الإشارة المدخلات التي تقابل 0 ديسيبل. على سبيل المثال، استخدم `np.max(spectrogram)` لضبط الجزء الأعلى صوتاً على 0 ديسيبل. يجب أن تكون القيمة أكبر من صفر.

min_value (`float`، *اختياري*، القيمة الافتراضية `1e-10`) : سيتم قصّ الطيف الترددي إلى هذه القيمة الدنيا قبل التحويل إلى الديسيبل، لتجنّب حساب `log(0)`. القيمة الافتراضية `1e-10` تقابل حدًّا أدنى قدره -100 ديسيبل. يجب أن تكون أكبر من الصفر.

db_range (`float`، *اختياري*) : يحدد المدى الديناميكي الأقصى بالديسيبل. على سبيل المثال، إذا كان `db_range = 80`، فلن يتجاوز الفرق بين القيمة الذروية وأصغر قيمة 80 ديسيبل. يجب أن يكون أكبر من صفر.

**يعيد:** `np.ndarray`

الطيف الترددي بالديسيبل

يحوّل طيف القدرة إلى مقياس الديسيبل. يحسب هذا `10 * log10(spectrogram / reference)`، مستخدماً خصائص اللوغاريتم الأساسية من أجل الاستقرار العددي.

تتمثل الدافع وراء تطبيق دالة اللوغاريتم على الطيف الترددي (mel) في أن البشر لا يدركون شدة الصوت على مقياس خطي. بشكل عام، لمضاعفة شدة الصوت المدركة، نحتاج إلى زيادة الطاقة فيه بمقدار 8 أضعاف. وهذا يعني أن التغيرات الكبيرة في الطاقة قد لا تبدو مختلفة كثيراً إذا كان الصوت مرتفع الشدة في الأساس. تجعل عملية الضغط هذه ميزات الطيف الترددي (mel) تتطابق بشكل أدق مع ما يسمعه البشر فعلياً.

بناءً على تنفيذ `librosa.power_to_db`.

#### transformers.audio_utils.amplitude_to_db[[transformers.audio_utils.amplitude_to_db]]

```python
transformers.audio_utils.amplitude_to_db(spectrogram: ndarray, reference: float = 1.0, min_value: float = 1e-05, db_range: float | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1437)

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

spectrogram (`np.ndarray`) : طيف (mel) السعة المُدخل.

reference (`float`، *اختياري*، القيمة الافتراضية 1.0) : يحدد قيمة مطياف الإشارة المدخلات التي تقابل 0 ديسيبل. على سبيل المثال، استخدم `np.max(spectrogram)` لضبط الجزء الأعلى صوتاً على 0 ديسيبل. يجب أن تكون القيمة أكبر من صفر.

min_value (`float`، *اختياري*، القيمة الافتراضية `1e-5`) : سيتم قصّ الطيف الصوتي إلى هذه القيمة الدنيا قبل التحويل إلى الديسيبل، لتجنّب حساب `log(0)`. القيمة الافتراضية `1e-5` تقابل حدًّا أدنى قدره -100 ديسيبل. يجب أن تكون أكبر من الصفر.

db_range (`float`، *اختياري*) : يحدد المدى الديناميكي الأقصى بالديسيبل. على سبيل المثال، إذا كان `db_range = 80`، فلن يتجاوز الفرق بين القيمة الذروية وأصغر قيمة 80 ديسيبل. يجب أن يكون أكبر من صفر.

**يعيد:** `np.ndarray`

الطيف الترددي بالديسيبل

يحوّل طيف السعة إلى مقياس الديسيبل. يحسب هذا `20 * log10(spectrogram / reference)`، مستخدماً خصائص اللوغاريتم الأساسية من أجل الاستقرار العددي.

تتمثل الدافع وراء تطبيق دالة اللوغاريتم على الطيف الترددي (mel) في أن البشر لا يدركون شدة الصوت على مقياس خطي. بشكل عام، لمضاعفة شدة الصوت المدركة، نحتاج إلى زيادة الطاقة فيه بمقدار 8 أضعاف. وهذا يعني أن التغيرات الكبيرة في الطاقة قد لا تبدو مختلفة كثيراً إذا كان الصوت مرتفع الشدة في الأساس. تجعل عملية الضغط هذه ميزات الطيف الترددي (mel) تتطابق بشكل أدق مع ما يسمعه البشر فعلياً.