Hugging Face's logo

Transformers documentation

Utilitas untuk FeatureExtractors

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Utilitas untuk FeatureExtractors

Halaman ini mencantumkan semua fungsi utilitas yang dapat digunakan oleh FeatureExtractor audio untuk menghitung fitur khusus dari audio mentah menggunakan algoritma umum seperti Short Time Fourier Transform atau log mel spectrogram.

Sebagian besar dari itu hanya berguna jika Anda sedang mempelajari kode pemroses audio di pustaka tersebut.

Transformasi Audio

transformers.audio_utils.hertz_to_mel

< >

( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray

Parameter

  • freq (float atau np.ndarray) — Frekuensi, atau beberapa frekuensi, dalam hertz (Hz).
  • mel_scale (str, opsional, default "htk") — Skala frekuensi mel yang akan digunakan, "htk", "kaldi" atau "slaney".

Mengembalikan

float atau np.ndarray

Frekuensi pada skala mel.

Konversi frekuensi dari hertz ke mels.

transformers.audio_utils.mel_to_hertz

< >

( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray

Parameter

  • mels (float atau np.ndarray) — Frekuensi, atau beberapa frekuensi, dalam mels.
  • mel_scale (str, opsional, "htk") — Skala frekuensi mel yang akan digunakan, "htk", "kaldi" atau "slaney".

Mengembalikan

float atau np.ndarray

Frekuensi dalam hertz.

Mengonversi frekuensi dari mels ke hertz.

transformers.audio_utils.mel_filter_bank

< >

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

Parameter

  • num_frequency_bins (int) — Jumlah bin frekuensi (harus sama dengan n_fft // 2 + 1 di mana n_fft adalah ukuran Fourier Transform yang digunakan untuk menghitung spektrogram).
  • num_mel_filters (int) — Jumlah filter mel yang akan dibuat.
  • min_frequency (float) — Frekuensi terendah yang menjadi perhatian dalam Hz.
  • max_frequency (float) — Frekuensi tertinggi yang menjadi perhatian dalam Hz. Nilai ini tidak boleh melebihi sampling_rate / 2.
  • sampling_rate (int) — Laju sampel dari waveform audio.
  • norm (str, opsional) — Jika "slaney", bagi bobot mel segitiga dengan lebar pita mel (normalisasi area).
  • mel_scale (str, opsional, default "htk") — Skala frekuensi mel yang akan digunakan, "htk", "kaldi" atau "slaney".
  • triangularize_in_mel_space (bool, opsional, default False) — Jika opsi ini diaktifkan, filter segitiga diterapkan di ruang mel alih-alih ruang frekuensi. Nilai ini harus disetel ke true untuk mendapatkan hasil yang sama dengan torchaudio saat menghitung filter mel.

Mengembalikan

np.ndarray dengan bentuk (num_frequency_bins, num_mel_filters)

Matriks bank filter segitiga. Ini adalah matriks proyeksi untuk mengubah spektrogram menjadi spektrogram mel.

Membuat matriks konversi bin frekuensi yang digunakan untuk mendapatkan spektrogram mel. Ini disebut mel filter bank, dan berbagai implementasi tersedia, yang berbeda dalam jumlah filter, bentuk filter, cara filter dijajarkan, bandwidth filter, dan cara spektrum diwarpa. Tujuan dari fitur-fitur ini adalah untuk mendekati persepsi manusia yang non-linear terhadap variasi pitch terhadap frekuensi.

Berbagai bank filter mel diperkenalkan dalam literatur. Variasi berikut didukung:

  • MFCC FB-20: diperkenalkan pada tahun 1980 oleh Davis dan Mermelstein, metode ini mengasumsikan frekuensi sampling 10 kHz dan lebar pita suara [0, 4600] Hz.
  • MFCC FB-24 HTK: dari Cambridge HMM Toolkit (HTK) (1995) menggunakan filter bank dengan 24 filter untuk bandwidth ucapan [0, 8000] Hz. Ini mengasumsikan sampling rate ≥ 16 kHz.
  • MFCC FB-40: dari Auditory Toolbox untuk MATLAB yang ditulis oleh Slaney pada tahun 1998, mengasumsikan laju sampling 16 kHz dan pita frekuensi ucapan [133, 6854] Hz. Versi ini juga mencakup normalisasi area.
  • HFCC-E FB-29 (Human Factor Cepstral Coefficients) dari Skowronski dan Harris (2004), mengasumsikan laju sampling 12,5 kHz dan pita frekuensi ucapan [0, 6250] Hz.

Kode ini diadaptasi dari torchaudio dan librosa. Perhatikan bahwa parameter default dari melscale_fbanks torchaudio mengimplementasikan filter "htk" sedangkan librosa menggunakan implementasi "slaney".

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

Menemukan ukuran input FFT terbaik untuk window_length tertentu. Fungsi ini mengambil panjang jendela tertentu dan, jika belum berupa pangkat dua, membulatkannya ke atas ke pangkat dua berikutnya.

Algoritma FFT bekerja paling cepat ketika panjang input merupakan pangkat dua, yang mungkin lebih besar dari ukuran jendela atau bingkai analisis. Misalnya, jika jendelanya 400 sampel, menggunakan ukuran input FFT 512 sampel lebih optimal daripada ukuran FFT 400 sampel. Menggunakan ukuran FFT yang lebih besar tidak memengaruhi frekuensi yang terdeteksi, melainkan hanya memberikan resolusi frekuensi yang lebih tinggi (yaitu, bin frekuensinya lebih kecil).

transformers.audio_utils.window_function

< >

( window_length: intname: str = 'hann'periodic: bool = Trueframe_length: int | None = Nonecenter: bool = True )

Parameter

  • window_length (int) — Panjang jendela dalam sampel.
  • name (str, opsional, defaultnya "hann") — Nama dari fungsi jendela.
  • periodic (bool, opsional, default True) — Apakah jendela bersifat periodik atau simetris.
  • frame_length (int, opsional) — Panjang frame analisis dalam sampel. Berikan nilai untuk frame_length jika window lebih kecil daripada panjang frame, sehingga akan dilakukan zero-padding.
  • center (bool, opsional, default True) — Apakah akan memusatkan jendela di dalam buffer FFT. Hanya digunakan ketika frame_length diberikan.

Mengembalikan array yang berisi jendela yang ditentukan. Jendela ini dimaksudkan untuk digunakan dengan stft.

Jenis jendela berikut didukung:

  • "boxcar": jendela persegi panjang
  • "hamming": jendela Hamming
  • "hann": jendela Hann
  • "povey": jendela Povey

transformers.audio_utils.spectrogram

< >

( 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'> )

Parameter

  • waveform (np.ndarray dengan bentuk (length,)) — Gelombang suara masukan. Ini harus berupa gelombang suara mono bernilai real tunggal.
  • window (np.ndarray dengan bentuk (frame_length,)) — Fungsi windowing yang akan diterapkan, termasuk zero-padding jika diperlukan. Panjang window aktual mungkin lebih pendek dari frame_length, tetapi kami mengasumsikan array sudah di-zero-pad.
  • frame_length (int) — Panjang bingkai analisis dalam sampel. Dengan librosa ini selalu sama dengan fft_length tetapi kami juga mengizinkan ukuran yang lebih kecil.
  • hop_length (int) — Langkah antara bingkai analisis yang berurutan dalam sampel.
  • fft_length (int, opsional) — Ukuran buffer FFT dalam sampel. Ini menentukan berapa banyak bin frekuensi yang akan dimiliki spektrogram. Untuk kecepatan optimal, nilai ini sebaiknya berupa pangkat dua. Jika None, gunakan frame_length.
  • power (float, opsional, default 1.0) — Jika 1.0, mengembalikan spektrogram amplitudo. Jika 2.0, mengembalikan spektrogram daya. Jika None, mengembalikan bilangan kompleks.
  • center (bool, opsional, default True) — Apakah akan melakukan padding pada waveform sehingga frame t berada di tengah waktu t * hop_length. Jika False, frame t akan dimulai pada waktu t * hop_length.
  • pad_mode (str, opsional, defaultnya "reflect") — Mode padding yang digunakan ketika center adalah True. Nilai yang mungkin adalah: "constant" (padding dengan nol), "edge" (padding dengan nilai tepi), "reflect" (padding dengan nilai cermin).
  • onesided (bool, opsional, default True) — Jika True, hanya menghitung frekuensi positif dan mengembalikan spektrogram yang berisi fft_length // 2 + 1 bin frekuensi. Jika False, juga menghitung frekuensi negatif dan mengembalikan fft_length bin frekuensi.
  • dither (float, opsional, default 0.0) — Menambahkan dithering. Dengan kata lain, menambahkan noise Gaussian kecil ke setiap frame. Misalnya, gunakan 4.0 untuk menambahkan dithering dengan distribusi normal yang berpusat di 0.0 dengan deviasi standar 4.0, 0.0 berarti tidak ada dithering. Dithering memiliki efek serupa dengan mel_floor. Ini mengurangi nilai log_mel_fbank yang tinggi untuk sinyal dengan bagian hard-zero, ketika VAD cutoff hadir dalam sinyal.
  • preemphasis (float, opsional) — Koefisien untuk filter low-pass yang menerapkan pre-emphasis sebelum DFT.
  • mel_filters (np.ndarray dengan bentuk (num_freq_bins, num_mel_filters), opsional) — Bank filter mel. Jika diberikan, bank filter ini diterapkan untuk membuat spektrogram mel.
  • mel_floor (float, opsional, default 1e-10) — Nilai minimum dari bank frekuensi mel.
  • log_mel (str, opsional) — Cara mengonversi spektrogram ke skala log. Opsi yang tersedia: None (tidak mengonversi), "log" (mengambil logaritma natural) "log10" (mengambil logaritma basis-10), "dB" (mengonversi ke desibel). Hanya dapat digunakan ketika power bukan None.
  • reference (float, opsional, default 1.0) — Menetapkan nilai spektrogram input yang sesuai dengan 0 dB. Misalnya, gunakan np.max(spectrogram) untuk menetapkan bagian paling keras ke 0 dB. Harus lebih besar dari nol.
  • min_value (float, opsional, default 1e-10) — Spektrogram akan dipotong (clipped) ke nilai minimum ini sebelum dikonversi ke desibel, untuk menghindari pengambilan log(0). Untuk spektrogram daya, default 1e-10 sesuai dengan minimum -100 dB. Untuk spektrogram amplitudo, nilai 1e-5 sesuai dengan -100 dB. Harus lebih besar dari nol.
  • db_range (float, opsional) — Menetapkan rentang dinamis maksimum dalam desibel. Misalnya, jika db_range = 80, selisih antara nilai puncak dan nilai terkecil tidak akan pernah melebihi 80 dB. Harus lebih besar dari nol.
  • remove_dc_offset (bool, opsional) — Kurangi rata-rata dari waveform pada setiap frame, diterapkan sebelum pre-emphasis. Nilai ini harus diset ke true agar mendapatkan hasil yang sama dengan torchaudio.compliance.kaldi.fbank saat menghitung filter mel.
  • dtype (np.dtype, opsional, default np.float32) — Tipe data dari tensor spektrogram. Jika power adalah None, argumen ini diabaikan dan dtype akan menjadi np.complex64.

Menghitung spektrogram dari satu gelombang suara menggunakan Short-Time Fourier Transform.

Fungsi ini dapat membuat jenis spektrogram berikut:

  • spektrum amplitudo (power = 1.0)
  • spektrum daya (power = 2.0)
  • spektrogram bernilai kompleks (power = None)
  • spektrogram log (gunakan argumen log_mel)
  • spekrogram mel (berikan mel_filters)
  • spektrogram log-mel (berikan mel_filters dan log_mel)

Cara kerjanya:

  1. Gelombang input dipecah menjadi frame berukuran frame_length yang tumpang tindih sebagian sebanyak `frame_length
    • sampel `hop_length`.
  2. Setiap frame dikalikan dengan jendela dan ditempatkan ke dalam buffer berukuran fft_length.
  3. DFT diambil dari setiap frame yang telah di-window.
  4. Hasilnya ditumpuk menjadi spektrogram.

Kami membedakan blok data sampel berikut, di mana masing-masing dapat memiliki panjang yang berbeda:

  • Bingkai analisis. Ini adalah ukuran potongan waktu yang digunakan untuk membagi gelombang input.
  • Jendela. Setiap bingkai analisis dikalikan dengan jendela untuk menghindari kebocoran spektral.
  • Buffer input FFT. Panjang buffer ini menentukan berapa banyak bin frekuensi yang ada dalam spektrogram.

Pada implementasi ini, jendela diasumsikan telah di-*zero-pad* agar memiliki ukuran yang sama dengan bingkai analisis. Jendela yang telah di-*pad* dapat diperoleh dari window_function(). Buffer masukan FFT dapat lebih besar dari bingkai analisis, biasanya pangkat dua berikutnya.

Catatan: Fungsi ini belum dioptimalkan untuk kecepatan. Fungsi ini seharusnya sebagian besar kompatibel dengan librosa.stft dan torchaudio.functional.transforms.Spectrogram, meskipun lebih fleksibel karena berbagai cara spekrogram dapat dibangun.

transformers.audio_utils.power_to_db

< >

( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-10db_range: float | None = None ) → np.ndarray

Parameter

  • spectrogram (np.ndarray) — Spectrogram daya (mel) masukan. Perhatikan bahwa spectrogram daya memiliki amplitudo yang dikuadratkan!
  • reference (float, opsional, default 1.0) — Menetapkan nilai spektrogram input yang sesuai dengan 0 dB. Misalnya, gunakan np.max(spectrogram) untuk menetapkan bagian paling keras ke 0 dB. Harus lebih besar dari nol.
  • min_value (float, opsional, default 1e-10) — Spektrogram akan dipotong (clipped) ke nilai minimum ini sebelum dikonversi ke desibel, untuk menghindari pengambilan log(0). Nilai default 1e-10 sesuai dengan minimum -100 dB. Harus lebih besar dari nol.
  • db_range (float, opsional) — Menetapkan rentang dinamis maksimum dalam desibel. Misalnya, jika db_range = 80, selisih antara nilai puncak dan nilai terkecil tidak akan pernah melebihi 80 dB. Harus lebih besar dari nol.

Mengembalikan

np.ndarray

spektrogram dalam desibel

Mengonversi spektrogram daya ke skala desibel. Ini menghitung 10 * log10(spectrogram / reference), menggunakan sifat-sifat dasar logaritma untuk stabilitas numerik.

Motivasi di balik penerapan fungsi log pada spektrogram (mel) adalah bahwa manusia tidak mendengar kerasnya suara pada skala linear. Secara umum, untuk menggandakan persepsi volume suara, kita perlu memasukkan 8 kali lebih banyak energi ke dalamnya. Ini berarti bahwa variasi besar dalam energi mungkin tidak terdengar sangat berbeda jika suaranya sudah keras sejak awal. Operasi kompresi ini membuat fitur spektrogram (mel) lebih sesuai dengan apa yang sebenarnya didengar oleh manusia.

Berdasarkan implementasi dari librosa.power_to_db.

transformers.audio_utils.amplitude_to_db

< >

( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-05db_range: float | None = None ) → np.ndarray

Parameter

  • spectrogram (np.ndarray) — Spektrogram amplitudo (mel) masukan.
  • reference (float, opsional, default 1.0) — Menetapkan nilai spektrogram input yang sesuai dengan 0 dB. Misalnya, gunakan np.max(spectrogram) untuk menetapkan bagian paling keras ke 0 dB. Harus lebih besar dari nol.
  • min_value (float, opsional, default 1e-5) — Spektrogram akan dipotong (clipped) ke nilai minimum ini sebelum dikonversi ke desibel, untuk menghindari pengambilan log(0). Nilai default 1e-5 sesuai dengan minimum -100 dB. Harus lebih besar dari nol.
  • db_range (float, opsional) — Menetapkan rentang dinamis maksimum dalam desibel. Misalnya, jika db_range = 80, selisih antara nilai puncak dan nilai terkecil tidak akan pernah melebihi 80 dB. Harus lebih besar dari nol.

Mengembalikan

np.ndarray

spektrogram dalam desibel

Mengonversi spektrogram amplitudo ke skala desibel. Ini menghitung 20 * log10(spectrogram / reference), menggunakan sifat-sifat logaritma dasar untuk stabilitas numerik.

Motivasi di balik penerapan fungsi log pada spektrogram (mel) adalah bahwa manusia tidak mendengar kerasnya suara pada skala linear. Secara umum, untuk menggandakan persepsi volume suara, kita perlu memasukkan 8 kali lebih banyak energi ke dalamnya. Ini berarti bahwa variasi besar dalam energi mungkin tidak terdengar sangat berbeda jika suaranya sudah keras sejak awal. Operasi kompresi ini membuat fitur spektrogram (mel) lebih sesuai dengan apa yang sebenarnya didengar oleh manusia.

Update on GitHub

←Utilitas untuk pemroses gambar Utilitas umum→