Transformers documentation
أدوات لمعالجات الميزات
أدوات لمعالجات الميزات
تُدرج هذه الصفحة جميع دوال الأداة التي يمكن أن يستخدمها FeatureExtractor الصوتي لحساب ميزات خاصة من الصوت الخام باستخدام خوارزميات شائعة مثل Short Time Fourier Transform أو log mel spectrogram.
لا تُفيد معظم تلك العناصر إلا إذا كنت تدرس كود معالجات الصوت في المكتبة.
تحويلات الصوت
transformers.audio_utils.hertz_to_mel
< source >( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
تحويل التردد من هرتز إلى ميل.
transformers.audio_utils.mel_to_hertz
< source >( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
تحويل التردد من وحدة ميل إلى وحدة هرتز.
transformers.audio_utils.mel_filter_bank
< source >( num_frequency_bins: intnum_mel_filters: intmin_frequency: floatmax_frequency: floatsampling_rate: intnorm: str | None = Nonemel_scale: str = 'htk'triangularize_in_mel_space: bool = False ) → np.ndarray of shape (num_frequency_bins, num_mel_filters)
المعاملات
- num_frequency_bins (
int) — عدد خلايا التردد (يجب أن يكون مطابقًا لـn_fft // 2 + 1حيثn_fftهو حجم تحويل فورييه المستخدم لحساب الطيف الصوتي). - num_mel_filters (
int) — عدد مرشحات ميل التي سيتم توليدها. - 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) — إذا تم تفعيل هذا الخيار، يُطبَّق المرشح المثلثي في فضاء الميّل بدلاً من فضاء التردد. يجب ضبطه علىtrueللحصول على النتائج نفسها التي يعطيهاtorchaudioعند حساب مرشحات الميّل.
يعيد
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 (Human Factor Cepstral Coefficients) لـ Skowronski و Harris (2004) معدل أخذ عينات يبلغ 12.5 kHz ونطاق تردد صوتي يبلغ
[0, 6250]هرتز.
تم تكييف هذا الكود من torchaudio و librosa. لاحظ أن المعلمات الافتراضية لـ melscale_fbanks في torchaudio تنفّذ مرشحات "htk" بينما يستخدم librosa تنفيذ "slaney".
يجد أفضل حجم لإدخال FFT لطول نافذة معطى window_length. تستقبل هذه الدالة طول نافذة معطى، وإذا لم يكن بالفعل قوة للعدد 2، تُقرّبه إلى أعلى قوة للعدد 2.
يعمل خوارزمية FFT بأقصى سرعة عندما يكون طول الإدخال قوة للعدد اثنين، وقد يكون ذلك أكبر من حجم النافذة أو إطار التحليل. على سبيل المثال، إذا كانت النافذة 400 عينة، فإن استخدام حجم إدخال FFT قدره 512 عينة يكون أكثر مثالية من حجم FFT قدره 400 عينة. استخدام حجم FFT أكبر لا يؤثر على الترددات المكتشفة، بل يمنح ببساطة دقة تردد أعلى (أي أن خلايا التردد تكون أصغر).
transformers.audio_utils.window_function
< source >( window_length: intname: str = 'hann'periodic: bool = Trueframe_length: int | None = Nonecenter: bool = True )
المعاملات
- window_length (
int) — طول النافذة بالعينات. - name (
str، اختياري، الافتراضي"hann") — اسم دالة النافذة. - periodic (
bool، اختياري، الافتراضيTrue) — ما إذا كان النافذة دورية أم متناظرة. - frame_length (
int, اختياري) — طول إطارات التحليل بالعينات. قدّم قيمة لـframe_lengthإذا كان النافذة أصغر من طول الإطار، حتى يتم ملؤها بالصفر. - center (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان سيتم توسيط النافذة داخل مخزن FFT. يُستخدم فقط عند تقديمframe_length.
يعيد مصفوفة تحتوي على النافذة المحددة. تُستخدم هذه النافذة مع stft.
الأنواع المدعومة من النوافذ هي:
"boxcar": نافذة مستطيلة"hamming": نافذة هامينغ"hann": نافذة هان"povey": نافذة Povey
transformers.audio_utils.spectrogram
< source >( waveform: ndarraywindow: ndarrayframe_length: inthop_length: intfft_length: int | None = Nonepower: float | None = 1.0center: bool = Truepad_mode: str = 'reflect'onesided: bool = Truedither: float = 0.0preemphasis: float | None = Nonemel_filters: numpy.ndarray | None = Nonemel_floor: float = 1e-10log_mel: str | None = Nonereference: float = 1.0min_value: float = 1e-10db_range: float | None = Noneremove_dc_offset: bool = Falsedtype: dtype = <class 'numpy.float32'> )
المعاملات
- 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.
يحسب طيف التردد الزمني (Spectrogram) لموجة صوتية واحدة باستخدام تحويل فورييه قصير المدى.
يمكن لهذه الدالة إنشاء الأنواع التالية من الطيف الصوتي:
- مطياف السعة (
power = 1.0) - مطياف القدرة (
power = 2.0) - طيف صوتي ذو قيم مركبة (
power = None) - مطياف الترددات اللوغاريتمي (استخدم الحجة
log_mel) - مطياف الميّل (توفير
mel_filters) - مطياف لوج-ميل (قدّم
mel_filtersوlog_mel)
كيف يعمل هذا:
- يتم تقسيم الموجة المدخلة إلى إطارات بحجم
frame_lengthتتداخل جزئيًا بمقدار `frame_length` عينة.- عينة hop_length.
- يُضرب كل إطار في النافذة ثم يُوضع في مخزن ذاكرة بحجم
fft_length. - يُؤخذ تحويل فورييه المنفصل (DFT) لكل إطار مُنَافِذ.
- تُرتَّب النتائج في صورة طيفية.
نميّز بين ما يلي من "كتل" بيانات عيّنة، حيث قد يختلف طول كلٍّ منها:
- إطار التحليل. هذا هو حجم شرائح الوقت التي يُقسَّم إليها الموجة الصوتية المدخلة.
- النافذة. يتم ضرب كل إطار تحليل في النافذة لتجنب تسرب الطيف.
- خادم إدخال FFT. يحدد طول هذا الخادم عدد خلايا التردد في الطيف الصوتي.
في هذا التنفيذ، يُفترض أن يكون النافذة مُكمّلة بالصفر بحيث تكون بنفس حجم إطار التحليل. يمكن الحصول على نافذة مكمّلة من window_function(). قد يكون مخزن الإدخال الخاص بتحويل فورييه السريع أكبر من إطار التحليل، وعادةً ما يكون القوة التالية للرقم 2.
ملاحظة: هذه الدالة غير مُحسَّنة للسرعة بعد. ينبغي أن تكون متوافقة إلى حد كبير مع librosa.stft وtorchaudio.functional.transforms.Spectrogram، على الرغم من أنها أكثر مرونة بسبب الطرق المختلفة التي يمكن من خلالها بناء مطياف الصوت.
transformers.audio_utils.power_to_db
< source >( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-10db_range: float | None = None ) → np.ndarray
المعاملات
- 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
< source >( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-05db_range: float | None = None ) → np.ndarray
المعاملات
- spectrogram (
np.ndarray) — مطياف السعة (ميل) المُدخل. - 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) تتطابق بشكل أقرب مع ما يسمعه البشر فعلياً.