# Công cụ cho `FeatureExtractors`

Trang này liệt kê tất cả các hàm tiện ích có thể được sử dụng bởi `FeatureExtractor` âm thanh để tính toán các đặc trưng đặc biệt từ âm thanh thô bằng các thuật toán phổ biến như *Short Time Fourier Transform* hoặc *log mel spectrogram*.

Phần lớn những điều đó chỉ hữu ích nếu bạn đang nghiên cứu mã nguồn của các bộ xử lý âm thanh trong thư viện.

## Biến đổi Âm thanh[[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')
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L556)

**Tham số:**

freq (`float` hoặc `np.ndarray`) : Tần số, hoặc nhiều tần số, tính bằng hertz (Hz).

mel_scale (`str`, *tùy chọn*, mặc định là `"htk"`) : Thang tần số mel cần sử dụng, `"htk"`, `"kaldi"` hoặc `"slaney"`.

**Trả về:** `float` hoặc `np.ndarray`

Các tần số trên thang mel.

Chuyển đổi tần số từ hertz sang 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')
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L592)

**Tham số:**

mels (`float` hoặc `np.ndarray`) : Tần số, hoặc nhiều tần số, tính bằng mels.

mel_scale (`str`, *tùy chọn*, `"htk"`) : Thang tần số mel cần sử dụng, `"htk"`, `"kaldi"` hoặc `"slaney"`.

**Trả về:** `float` hoặc `np.ndarray`

Tần số tính bằng hertz.

Chuyển đổi tần số từ mels sang 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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L746)

**Tham số:**

num_frequency_bins (`int`) : Số lượng bin tần số (phải giống với `n_fft // 2 + 1` trong đó `n_fft` là kích thước của phép biến đổi Fourier được sử dụng để tính phổ tần).

num_mel_filters (`int`) : Số bộ lọc mel cần tạo.

min_frequency (`float`) : Tần số thấp nhất quan tâm, tính bằng Hz.

max_frequency (`float`) : Tần số cao nhất quan tâm, tính bằng Hz. Giá trị này không được vượt quá `sampling_rate / 2`.

sampling_rate (`int`) : Tần số lấy mẫu của dạng sóng âm thanh.

norm (`str`, *tùy chọn*) : Nếu là `"slaney"`, chia trọng số mel hình tam giác cho độ rộng của dải mel (chuẩn hóa diện tích).

mel_scale (`str`, *tùy chọn*, mặc định là `"htk"`) : Thang tần số mel cần sử dụng, `"htk"`, `"kaldi"` hoặc `"slaney"`.

triangularize_in_mel_space (`bool`, *tuỳ chọn*, mặc định là `False`) : Nếu tùy chọn này được bật, bộ lọc tam giác sẽ được áp dụng trong không gian mel thay vì không gian tần số. Nên đặt giá trị này thành `true` để có cùng kết quả như `torchaudio` khi tính toán bộ lọc mel.

**Trả về:** `np.ndarray` có hình dạng (`num_frequency_bins`, `num_mel_filters`)

Ma trận bộ lọc hình tam giác. Đây là ma trận chiếu để chuyển từ phổ âm (spectrogram) sang phổ mel (mel spectrogram).

Tạo ma trận chuyển đổi bin tần số được sử dụng để lấy phổ mel. Thành phần này được gọi là *mel filter bank*, và có nhiều cách triển khai khác nhau, khác biệt về số lượng bộ lọc, hình dạng của bộ lọc, cách bố trí khoảng cách giữa các bộ lọc, băng thông của bộ lọc và cách biến đổi phổ. Mục tiêu của các đặc trưng này là xấp xỉ nhận thức phi tuyến của con người về sự thay đổi cao độ theo tần số.

Các ngân lọc mel khác nhau đã được giới thiệu trong tài liệu. Các biến thể sau được hỗ trợ:

- MFCC FB-20: được giới thiệu vào năm 1980 bởi Davis và Mermelstein, giả định tần số lấy mẫu là 10 kHz và băng thông giọng nói là `[0, 4600]` Hz.
- MFCC FB-24 HTK: từ Cambridge HMM Toolkit (HTK) (1995) sử dụng một bộ lọc gồm 24 bộ lọc cho dải tần số âm thanh `[0, 8000]` Hz. Điều này giả định tần số lấy mẫu ≥ 16 kHz.
- MFCC FB-40: từ Auditory Toolbox cho MATLAB do Slaney viết năm 1998, giả định tần số lấy mẫu là 16 kHz và dải tần số giọng nói là `[133, 6854]` Hz. Phiên bản này cũng bao gồm chuẩn hóa diện tích.
- HFCC-E FB-29 (Hệ số phổ cepstral của yếu tố con người) của Skowronski và Harris (2004), giả định tần số lấy mẫu là 12,5 kHz và dải tần số của giọng nói là `[0, 6250]` Hz.

Mã này được điều chỉnh từ *torchaudio* và *librosa*. Lưu ý rằng các tham số mặc định của `melscale_fbanks` trong torchaudio triển khai bộ lọc `"htk"` trong khi librosa sử dụng triển khai `"slaney"`.

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

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L840)

Tìm kích thước đầu vào FFT tối ưu cho một `window_length` cho trước. Hàm này nhận một độ dài cửa sổ và, nếu chưa phải là lũy thừa của hai, sẽ làm tròn lên lũy thừa của hai tiếp theo.

Thuật toán FFT chạy nhanh nhất khi độ dài của đầu vào là một lũy thừa của hai, điều này có thể lớn hơn kích thước của cửa sổ hoặc khung phân tích. Ví dụ, nếu cửa sổ là 400 mẫu, việc sử dụng kích thước đầu vào FFT là 512 mẫu sẽ tối ưu hơn so với kích thước FFT là 400 mẫu. Việc sử dụng kích thước FFT lớn hơn không ảnh hưởng đến các tần số được phát hiện, nó đơn giản là mang lại độ phân giải tần số cao hơn (tức là các bin tần số nhỏ hơn).

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L853)

**Tham số:**

window_length (`int`) : Độ dài của cửa sổ tính bằng số mẫu.

name (`str`, *tùy chọn*, mặc định là `"hann"`) : Tên của hàm cửa sổ.

periodic (`bool`, *tùy chọn*, mặc định là `True`) : Xác định xem cửa sổ có tuần hoàn hay đối xứng.

frame_length (`int`, *optional*) : Độ dài của các khung phân tích tính bằng số mẫu. Cung cấp một giá trị cho `frame_length` nếu cửa sổ nhỏ hơn độ dài khung, để nó được đệm bằng số không.

center (`bool`, *tùy chọn*, mặc định là `True`) : Xác định có căn giữa cửa sổ bên trong bộ đệm FFT hay không. Chỉ được sử dụng khi `frame_length` được cung cấp.

**Trả về:**

`np.ndarray` có hình dạng `(window_length,)` hoặc `(frame_length,)` chứa cửa sổ.

Trả về một mảng chứa cửa sổ được chỉ định. Cửa sổ này được thiết kế để sử dụng với `stft`.

Các loại cửa sổ sau được hỗ trợ:

- `"boxcar"`: một cửa sổ hình chữ nhật
- `"hamming"`: cửa sổ Hamming
- `"hann"`: cửa sổ Hann
- `"povey"`: cửa sổ 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'>)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L917)

**Tham số:**

waveform (`np.ndarray` có shape `(length,)`) : Dạng sóng đầu vào. Đây phải là một dạng sóng đơn, thực, mono.

window (`np.ndarray` có hình dạng `(frame_length,)`) : Hàm cửa sổ cần áp dụng, bao gồm cả việc đệm zero nếu cần. Độ dài cửa sổ thực tế có thể ngắn hơn `frame_length`, nhưng chúng ta giả định rằng mảng đã được đệm zero.

frame_length (`int`) : Độ dài của các khung phân tích tính bằng số mẫu. Với librosa, giá trị này luôn bằng `fft_length` nhưng chúng tôi cũng cho phép kích thước nhỏ hơn.

hop_length (`int`) : Khoảng cách giữa các khung phân tích liên tiếp, tính bằng số mẫu.

fft_length (`int`, *optional*) : Kích thước của bộ đệm FFT tính bằng số mẫu. Giá trị này xác định số lượng bin tần số mà phổ tần sẽ có. Để đạt tốc độ tối ưu, giá trị này nên là lũy thừa của hai. Nếu là `None`, sẽ sử dụng `frame_length`.

power (`float`, *tuỳ chọn*, mặc định là 1.0) : Nếu là 1.0, trả về phổ biên độ. Nếu là 2.0, trả về phổ công suất. Nếu là `None`, trả về các số phức.

center (`bool`, *tùy chọn*, mặc định là `True`) : Có nên đệm (pad) dạng sóng để khung `t` được căn giữa quanh thời điểm `t * hop_length` hay không. Nếu `False`, khung `t` sẽ bắt đầu tại thời điểm `t * hop_length`.

pad_mode (`str`, *tùy chọn*, mặc định là `"reflect"`) : Chế độ đệm được sử dụng khi `center` là `True`. Các giá trị có thể là: `"constant"` (đệm bằng số không), `"edge"` (đệm bằng giá trị ở cạnh), `"reflect"` (đệm bằng các giá trị được phản chiếu).

onesided (`bool`, *tuỳ chọn*, mặc định là `True`) : Nếu là True, chỉ tính các tần số dương và trả về phổ tần chứa `fft_length // 2 + 1` bin tần số. Nếu là False, cũng tính các tần số âm và trả về `fft_length` bin tần số.

dither (`float`, *optional*, mặc định là 0.0) : Thêm dithering. Nói cách khác, thêm một nhiễu Gaussian nhỏ vào mỗi khung. Ví dụ, dùng 4.0 để thêm dithering với phân phối chuẩn có tâm tại 0.0 và độ lệch chuẩn 4.0, 0.0 nghĩa là không có dithering. Dithering có tác dụng tương tự như `mel_floor`. Nó làm giảm các giá trị log_mel_fbank cao cho các tín hiệu có các đoạn hard-zero, khi có VAD cutoff trong tín hiệu.

preemphasis (`float`, *tuỳ chọn*) : Hệ số cho bộ lọc thông thấp áp dụng tiền nhấn trước khi thực hiện DFT.

mel_filters (`np.ndarray` có shape `(num_freq_bins, num_mel_filters)`, *optional*) : Bộ lọc mel. Nếu được cung cấp, áp dụng bộ lọc này để tạo mel spectrogram.

mel_floor (`float`, *tuỳ chọn*, mặc định là 1e-10) : Giá trị tối thiểu của các ngân tần số mel.

log_mel (`str`, *tùy chọn*) : Cách chuyển đổi phổ âm sang thang log. Các tùy chọn khả dụng là: `None` (không chuyển đổi), `"log"` (lấy logarit tự nhiên) `"log10"` (lấy logarit cơ số 10), `"dB"` (chuyển đổi sang decibel). Chỉ có thể sử dụng khi `power` không phải là `None`.

reference (`float`, *optional*, mặc định là 1.0) : Đặt giá trị phổ tần đầu vào tương ứng với 0 dB. Ví dụ, sử dụng `np.max(spectrogram)` để đặt phần to nhất thành 0 dB. Phải lớn hơn không.

min_value (`float`, *optional*, mặc định là `1e-10`) : Phổ đồ sẽ được cắt (clip) xuống giá trị tối thiểu này trước khi chuyển đổi sang decibel, để tránh lấy `log(0)`. Đối với phổ đồ công suất, giá trị mặc định `1e-10` tương ứng với mức tối thiểu -100 dB. Đối với phổ đồ biên độ, giá trị `1e-5` tương ứng với -100 dB. Phải lớn hơn không.

db_range (`float`, *optional*) : Đặt phạm vi động tối đa tính bằng decibel. Ví dụ, nếu `db_range = 80`, thì chênh lệch giữa giá trị đỉnh và giá trị nhỏ nhất sẽ không bao giờ vượt quá 80 dB. Phải lớn hơn không.

remove_dc_offset (`bool`, *tuỳ chọn*) : Trừ giá trị trung bình khỏi waveform trên mỗi khung, được áp dụng trước khi thực hiện pre-emphasis. Tham số này nên được đặt thành `true` để có cùng kết quả như `torchaudio.compliance.kaldi.fbank` khi tính toán bộ lọc mel.

dtype (`np.dtype`, *tùy chọn*, mặc định là `np.float32`) : Kiểu dữ liệu của tensor spectrogram. Nếu `power` là None, tham số này sẽ bị bỏ qua và dtype sẽ là `np.complex64`.

**Trả về:**

`nd.array` chứa spectrogram có hình dạng `(num_frequency_bins, length)` đối với spectrogram thông thường hoặc hình dạng `(num_mel_filters, length)` đối với mel spectrogram.

Tính toán phổ đồ trên một dạng sóng bằng phép biến đổi Fourier thời gian ngắn.

Hàm này có thể tạo ra các loại phổ âm (spectrogram) sau:

- biểu đồ phổ biên độ (`power = 1.0`)
- biểu đồ phổ công suất (`power = 2.0`)
- phổ đồ phức trị (`power = None`)
- log spectrogram (sử dụng đối số `log_mel`)
- spectrogram mel (cung cấp `mel_filters`)
- spectrogram log-mel (cung cấp `mel_filters` và `log_mel`)

Cách hoạt động:

1. Đường sóng đầu vào được chia thành các khung có kích thước `frame_length` với phần chồng lấn một phần là `frame_length
   - mẫu hop_length.
2. Mỗi khung được nhân với cửa sổ và đặt vào bộ đệm có kích thước `fft_length`.
3. DFT được thực hiện trên mỗi khung đã được nhân cửa sổ.
4. Kết quả được xếp chồng thành một phổ đồ.

Chúng tôi phân biệt giữa các "khối" dữ liệu mẫu sau đây, mỗi khối có thể có độ dài khác nhau:

- Khung phân tích. Đây là kích thước của các lát thời gian mà sóng đầu vào được chia thành.
- Cửa sổ. Mỗi khung phân tích được nhân với cửa sổ để tránh rò rỉ phổ.
- Bộ đệm đầu vào FFT. Độ dài của bộ đệm này xác định số lượng bin tần số trong phổ âm.

Trong cài đặt này, cửa sổ được giả định là đã được đệm bằng số 0 để có cùng kích thước với khung phân tích. Một cửa sổ đã đệm có thể được lấy từ `window_function()`. Bộ đệm đầu vào FFT có thể lớn hơn khung phân tích, thường là lũy thừa của hai kế tiếp.

Lưu ý: Hàm này chưa được tối ưu cho tốc độ. Nó nên tương thích phần lớn với `librosa.stft` và `torchaudio.functional.transforms.Spectrogram`, mặc dù nó linh hoạt hơn do các cách khác nhau để xây dựng phổ tần.

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

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1339)

**Tham số:**

spectrogram (`np.ndarray`) : Phổ phổ (mel) công suất đầu vào. Lưu ý rằng phổ công suất có biên độ được bình phương!

reference (`float`, *optional*, mặc định là 1.0) : Đặt giá trị phổ tần đầu vào tương ứng với 0 dB. Ví dụ, sử dụng `np.max(spectrogram)` để đặt phần to nhất thành 0 dB. Phải lớn hơn không.

min_value (`float`, *optional*, mặc định là `1e-10`) : Phổ tần số sẽ được cắt (clip) về giá trị tối thiểu này trước khi chuyển đổi sang decibel, để tránh lấy `log(0)`. Giá trị mặc định `1e-10` tương ứng với mức tối thiểu là -100 dB. Phải lớn hơn không.

db_range (`float`, *optional*) : Đặt phạm vi động tối đa tính bằng decibel. Ví dụ, nếu `db_range = 80`, thì chênh lệch giữa giá trị đỉnh và giá trị nhỏ nhất sẽ không bao giờ vượt quá 80 dB. Phải lớn hơn không.

**Trả về:** `np.ndarray`

biểu đồ phổ trong đơn vị decibel

Chuyển đổi phổ công suất sang thang decibel. Hàm này tính `10 * log10(spectrogram / reference)`, sử dụng các tính chất cơ bản của logarit để đảm bảo ổn định số.

Động lực đằng sau việc áp dụng hàm log lên phổ đồ (mel) là do con người không nghe thấy độ to theo thang tuyến tính. Nhìn chung, để nhân đôi cảm nhận về âm lượng của một âm thanh, chúng ta cần đưa vào gấp 8 lần năng lượng. Điều này có nghĩa là các biến động lớn về năng lượng có thể không tạo ra sự khác biệt đáng kể về mặt âm thanh nếu âm thanh đó vốn đã to. Thao tác nén này giúp các đặc trưng của phổ đồ (mel) khớp sát hơn với những gì con người thực sự nghe thấy.

Dựa trên cài đặt của `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)
```

[Nguồn](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1439)

**Tham số:**

spectrogram (`np.ndarray`) : Phổ biên độ (mel) đầu vào.

reference (`float`, *optional*, mặc định là 1.0) : Đặt giá trị phổ tần đầu vào tương ứng với 0 dB. Ví dụ, sử dụng `np.max(spectrogram)` để đặt phần to nhất thành 0 dB. Phải lớn hơn không.

min_value (`float`, *optional*, mặc định là `1e-5`) : Phổ tần số sẽ được cắt (clip) về giá trị tối thiểu này trước khi chuyển đổi sang decibel, để tránh lấy `log(0)`. Giá trị mặc định `1e-5` tương ứng với mức tối thiểu là -100 dB. Phải lớn hơn không.

db_range (`float`, *optional*) : Đặt phạm vi động tối đa tính bằng decibel. Ví dụ, nếu `db_range = 80`, thì chênh lệch giữa giá trị đỉnh và giá trị nhỏ nhất sẽ không bao giờ vượt quá 80 dB. Phải lớn hơn không.

**Trả về:** `np.ndarray`

biểu đồ phổ trong đơn vị decibel

Chuyển đổi phổ biên độ sang thang decibel. Hàm này tính `20 * log10(spectrogram / reference)`, sử dụng các tính chất cơ bản của logarit để đảm bảo ổn định về mặt số học.

Động lực đằng sau việc áp dụng hàm log lên phổ đồ (mel) là do con người không nghe thấy độ to theo thang tuyến tính. Nhìn chung, để nhân đôi cảm nhận về âm lượng của một âm thanh, chúng ta cần đưa vào gấp 8 lần năng lượng. Điều này có nghĩa là các biến động lớn về năng lượng có thể không tạo ra sự khác biệt đáng kể về mặt âm thanh nếu âm thanh đó vốn đã to. Thao tác nén này giúp các đặc trưng của phổ đồ (mel) khớp sát hơn với những gì con người thực sự nghe thấy.