# 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]]

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L580)

**Parameter:**

freq (`float` atau `np.ndarray`) : Frekuensi, atau beberapa frekuensi, dalam hertz (Hz).

mel_scale (`str`, *opsional*, defaultnya `"htk"`) : Skala frekuensi mel yang akan digunakan, yaitu `"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[[transformers.audio_utils.mel_to_hertz]]

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L616)

**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[[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, dtype: str | numpy.dtype = <class 'numpy.float64'>)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L770)

**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*, defaultnya `"htk"`) : Skala frekuensi mel yang akan digunakan, yaitu `"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.

dtype (`str` atau `np.dtype`, *opsional*, defaultnya `np.float64`) : Tipe data dari filter yang dikembalikan. Filter segitiga dihitung dalam float64 dan di-cast ke `dtype` sebelum normalisasi `"slaney"`. Dengan `norm="slaney"`, `mel_scale="slaney"` dan `dtype=np.float32`, hasilnya bit-exact dengan `librosa.filters.mel(..., norm="slaney")` (ditranspose).

**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 memperoleh spektrogram mel. Ini disebut *mel filter bank*, dan berbagai implementasi tersedia, yang berbeda dalam jumlah filter, bentuk filter, cara penempatan filter, bandwidth filter, dan cara spektrum diwarpa. Tujuan dari fitur-fitur ini adalah untuk mengaproksimasi persepsi manusia yang non-linear terhadap variasi pitch sehubungan dengan 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 bandwidth ucapan `[0, 4600]` Hz.
- MFCC FB-24 HTK: dari Cambridge HMM Toolkit (HTK) (1995) menggunakan filter bank berisi 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 pengambilan sampel 12,5 kHz dan pita frekuensi ucapan `[0, 6250]` Hz.

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

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

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L869)

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 dari dua, yang mungkin lebih besar dari ukuran jendela atau bingkai analisis. Misalnya, jika jendelanya adalah 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[[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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L882)

**Parameter:**

window_length (`int`) : Panjang jendela dalam sampel.

name (`str`, *opsional*, default `"hann"`) : Nama fungsi jendela.

periodic (`bool`, *opsional*, default `True`) : Apakah jendela bersifat periodik atau simetris.

frame_length (`int`, *opsional*) : Panjang bingkai analisis dalam sampel. Berikan nilai untuk `frame_length` jika jendela lebih kecil dari panjang bingkai, sehingga akan dilakukan zero-padding.

center (`bool`, *opsional*, default `True`) : Apakah jendela akan dipusatkan di dalam buffer FFT. Hanya digunakan ketika `frame_length` disediakan.

**Mengembalikan:**

`np.ndarray` dengan bentuk `(window_length,)` atau `(frame_length,)` yang berisi jendela.

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L946)

**Parameter:**

waveform (`np.ndarray` dengan bentuk `(length,)`) : Gelombang masukan. Ini harus berupa gelombang 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, nilai ini selalu sama dengan `fft_length`, tetapi kami juga mengizinkan ukuran yang lebih kecil.

hop_length (`int`) : Jarak (stride) antara bingkai analisis yang berurutan dalam satuan 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`, digunakan `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 waveform akan di-pad agar frame `t` terpusat pada 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 yang dicerminkan).

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 simpangan baku 4.0, sedangkan 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 terdapat VAD cutoff 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 disediakan, 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 dikonversi), `"log"` (ambil logaritma natural), `"log10"` (ambil logaritma basis-10), `"dB"` (konversi ke desibel). Hanya dapat digunakan ketika `power` bukan `None`.

reference (`float`, *opsional*, default 1.0) : Menetapkan nilai spektrogram masukan yang sesuai dengan 0 dB. Sebagai contoh, gunakan `np.max(spectrogram)` untuk menetapkan bagian paling keras ke 0 dB. Nilai ini 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, nilai default `1e-10` berkorespondensi dengan minimum -100 dB. Untuk spektrogram amplitudo, nilai `1e-5` berkorespondensi dengan -100 dB. Harus lebih besar dari nol.

db_range (`float`, *opsional*) : Menetapkan rentang dinamis maksimum dalam desibel. Sebagai contoh, 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*) : Mengurangi mean dari waveform pada setiap frame, diterapkan sebelum pre-emphasis. Nilai ini harus diset ke `true` untuk 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`.

**Mengembalikan:**

`nd.array` yang berisi spektrogram dengan bentuk `(num_frequency_bins, length)` untuk spektrogram biasa atau bentuk `(num_mel_filters, length)` untuk spektrogram mel.

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 masukan dipecah menjadi frame berukuran `frame_length` yang sebagian tumpang tindih sebesar `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 membuat pembedaan antara "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 berbeda untuk membangun spektrogram.

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

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L1368)

**Parameter:**

spectrogram (`np.ndarray`) : Spekrogram daya (mel) input. Perhatikan bahwa spekrogram daya memiliki amplitudo yang dikuadratkan!

reference (`float`, *opsional*, default 1.0) : Menetapkan nilai spektrogram masukan yang sesuai dengan 0 dB. Sebagai contoh, gunakan `np.max(spectrogram)` untuk menetapkan bagian paling keras ke 0 dB. Nilai ini harus lebih besar dari nol.

min_value (`float`, *opsional*, default `1e-10`) : Spektrogram akan dipotong ke nilai minimum ini sebelum dikonversi ke desibel, untuk menghindari pengambilan `log(0)`. Nilai default `1e-10` setara dengan minimum -100 dB. Harus lebih besar dari nol.

db_range (`float`, *opsional*) : Menetapkan rentang dinamis maksimum dalam desibel. Sebagai contoh, 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 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.

Berdasarkan implementasi dari `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)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.24.0/src/transformers/audio_utils.py#L1468)

**Parameter:**

spectrogram (`np.ndarray`) : Spektrum amplitudo (mel) input.

reference (`float`, *opsional*, default 1.0) : Menetapkan nilai spektrogram masukan yang sesuai dengan 0 dB. Sebagai contoh, gunakan `np.max(spectrogram)` untuk menetapkan bagian paling keras ke 0 dB. Nilai ini 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` setara dengan minimum -100 dB. Harus lebih besar dari nol.

db_range (`float`, *opsional*) : Menetapkan rentang dinamis maksimum dalam desibel. Sebagai contoh, 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 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.

