Transformers documentation
Công cụ cho FeatureExtractors
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
< source >( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
Chuyển đổi tần số từ hertz sang mels.
transformers.audio_utils.mel_to_hertz
< source >( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
Chuyển đổi tần số từ mels sang hertz.
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)
Tham số
- num_frequency_bins (
int) — Số lượng bin tần số (phải giống vớin_fft // 2 + 1trong đón_fftlà 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ố lượng 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ố quan tâm cao nhất, 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 bề 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, tùy 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ố. Giá trị này nên được đặt thànhtrueđể có cùng kết quả nhưtorchaudiokhi 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. Đây được gọi là bank bộ lọc mel, 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 tính nă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 bộ lọc gồm 24 bộ lọc cho băng thông giọng nói
[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 (Human Factor Cepstral Coefficients) 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".
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
< source >( window_length: intname: str = 'hann'periodic: bool = Trueframe_length: int | None = Nonecenter: bool = True )
Tham số
- window_length (
int) — Chiều 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, tùy chọn) — Chiều 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ị choframe_lengthnếu cửa sổ nhỏ hơn chiều dài khung, để nó được đệm bằng số không. - center (
bool, tùy chọn, mặc định làTrue) — Có căn giữa cửa sổ bên trong bộ đệm FFT hay không. Chỉ được sử dụng khiframe_lengthđược cung cấp.
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
< 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'> )
Tham số
- waveform (
np.ndarraycó hình dạng(length,)) — Đoạn âm thanh đầu vào. Đây phải là một đoạn âm thanh đơn, thực, kênh đơn (mono). - window (
np.ndarraycó 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ơnframe_length, nhưng chúng ta giả định rằng mảng đã được đệm zero. - frame_length (
int) — Chiều 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ằngfft_lengthnhưng chúng tôi cũng cho phép các kích thước nhỏ hơn. - hop_length (
int) — Bước nhảy giữa các khung phân tích liên tiếp, tính bằng số mẫu. - fft_length (
int, tùy chọn) — Kích thước của bộ đệm FFT tính bằng số mẫu. Giá trị này quyết định số lượng bin tần số mà phổ âm (spectrogram) 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ụngframe_length. - power (
float, tùy 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 waveform để khungtđược căn giữa quanh thời điểmt * hop_lengthhay không. NếuFalse, khungtsẽ bắt đầu tại thời điểmt * hop_length. - pad_mode (
str, tùy chọn, mặc định là"reflect") — Chế độ đệm được sử dụng khicenterlàTrue. Các giá trị có thể là:"constant"(đệm bằng số 0),"edge"(đệm bằng giá trị ở cạnh),"reflect"(đệm bằng giá trị phản chiếu). - onesided (
bool, tùy chọn, mặc định làTrue) — Nếu True, chỉ tính các tần số dương và trả về spectrogram chứafft_length // 2 + 1bin tần số. Nếu False, cũng tính các tần số âm và trả vềfft_lengthbin tần số. - dither (
float, optional, defaults to 0.0) — Adds dithering. In other words, adds a small Gaussian noise to each frame. E.g. use 4.0 to add dithering with a normal distribution centered around 0.0 with standard deviation 4.0, 0.0 means no dithering. Dithering has similar effect asmel_floor. It reduces the high log_mel_fbank values for signals with hard-zero sections, when VAD cutoff is present in the signal. - preemphasis (
float, tùy chọn) — Hệ số cho bộ lọc thông thấp áp dụng tiền nhấn mạnh trước khi thực hiện DFT. - mel_filters (
np.ndarraycó hình dạng(num_freq_bins, num_mel_filters), tùy chọn) — Ngân bộ lọc mel. Nếu được cung cấp, sẽ áp dụng ngân bộ lọc này để tạo ra phổ mel. - mel_floor (
float, tùy 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 spectrogram sang thang log. Các tùy chọn có thể 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ể dùng khipowerkhông phảiNone. - reference (
float, tuỳ chọn, 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ụngnp.max(spectrogram)để đặt phần to nhất thành 0 dB. Phải lớn hơn không. - min_value (
float, tuỳ chọn, mặc định là1e-10) — Biểu đồ phổ sẽ bị cắt (clip) xuống giá trị tối thiểu này trước khi chuyển đổi sang decibel, để tránh việc lấylog(0). Đối với biểu đồ phổ công suất, giá trị mặc định1e-10tương ứng với mức tối thiểu -100 dB. Đối với biểu đồ phổ biên độ, giá trị1e-5tương ứng với -100 dB. Giá trị này phải lớn hơn không. - db_range (
float, tùy chọn) — Đặt phạm vi động tối đa tính bằng decibel. Ví dụ, nếudb_range = 80, thì sự 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, tùy chọn) — Trừ giá trị trung bình khỏi waveform trên mỗi frame, được áp dụng trước pre-emphasis. Tham số này nên được đặt thànhtrueđể có cùng kết quả nhưtorchaudio.compliance.kaldi.fbankkhi 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ếupowerlà None, tham số này sẽ bị bỏ qua và dtype sẽ lànp.complex64.
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_filtersvàlog_mel)
Cách hoạt động:
- Tín hiệu đầu vào được chia thành các khung có kích thước
frame_lengthchồng lấn một phần nhau, với bước nhảy là `hop_length` mẫu.- mẫu hop_length.
- Mỗi khung được nhân với cửa sổ và đặt vào bộ đệm có kích thước
fft_length. - DFT được thực hiện trên mỗi khung đã được nhân cửa sổ.
- 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 spectrogram.
transformers.audio_utils.power_to_db
< source >( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-10db_range: float | None = None ) → np.ndarray
Tham số
- spectrogram (
np.ndarray) — Biểu đồ phổ công suất (mel) đầu vào. Lưu ý rằng biểu đồ phổ công suất có biên độ được bình phương! - reference (
float, tuỳ chọn, 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ụngnp.max(spectrogram)để đặt phần to nhất thành 0 dB. Phải lớn hơn không. - min_value (
float, tuỳ chọn, mặc định là1e-10) — Biểu đồ phổ sẽ bị cắt (clip) xuống giá trị tối thiểu này trước khi chuyển đổi sang decibel, để tránh việc lấylog(0). Giá trị mặc định1e-10tương ứng với mức tối thiểu là -100 dB. Phải lớn hơn không. - db_range (
float, tùy chọn) — Đặt phạm vi động tối đa tính bằng decibel. Ví dụ, nếudb_range = 80, thì sự 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à vì con người không nghe độ 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 được.
Dựa trên cài đặt của 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
Tham số
- spectrogram (
np.ndarray) — Biểu đồ phổ biên độ (mel) đầu vào. - reference (
float, tuỳ chọn, 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ụngnp.max(spectrogram)để đặt phần to nhất thành 0 dB. Phải lớn hơn không. - min_value (
float, tuỳ chọn, mặc định là1e-5) — Biểu đồ phổ sẽ bị cắt (clip) xuống giá trị tối thiểu này trước khi chuyển đổi sang decibel, để tránh việc lấylog(0). Giá trị mặc định1e-5tương ứng với mức tối thiểu là -100 dB. Phải lớn hơn không. - db_range (
float, tùy chọn) — Đặt phạm vi động tối đa tính bằng decibel. Ví dụ, nếudb_range = 80, thì sự 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à vì con người không nghe độ 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 được.