Hugging Face's logo

Transformers documentation

FeatureExtractors için Yardımcı Araçlar

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

and get access to the augmented documentation experience

to get started

FeatureExtractors için Yardımcı Araçlar

Bu sayfa, ham ses verisinden Short Time Fourier Transform veya log mel spectrogram gibi yaygın algoritmalar kullanarak özel özellikler hesaplamak için ses FeatureExtractor tarafından kullanılabilecek tüm yardımcı işlevleri listeler.

Bunların çoğu, kütüphanedeki ses işleyicilerinin kodunu inceliyorsanız faydalıdır.

Ses Dönüşümleri

transformers.audio_utils.hertz_to_mel

< >

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

Parametreler

  • freq (float veya np.ndarray) — Hertz (Hz) cinsinden frekans veya birden fazla frekans.
  • mel_scale (str, isteğe bağlı, varsayılan "htk") — Kullanılacak mel frekans ölçeği, "htk", "kaldi" veya "slaney".

Dönüş değeri

float veya np.ndarray

Mel ölçeğindeki frekanslar.

Frekansı hertz'ten mel'e dönüştürür.

transformers.audio_utils.mel_to_hertz

< >

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

Parametreler

  • mels (float veya np.ndarray) — Mel cinsinden frekans veya birden fazla frekans.
  • mel_scale (str, isteğe bağlı, "htk") — Kullanılacak mel frekans ölçeği, "htk", "kaldi" veya "slaney".

Dönüş değeri

float veya np.ndarray

Hertz cinsinden frekanslar.

Frekansı mellerden hertze dönüştürür.

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)

Parametreler

  • num_frequency_bins (int) — Frekans kutusu sayısı (spektrogramu hesaplamak için kullanılan Fourier Dönüşümü'nün boyutu olan n_fft için n_fft // 2 + 1 ile aynı olmalıdır).
  • num_mel_filters (int) — Oluşturulacak mel filtre sayısı.
  • min_frequency (float) — Hz cinsinden ilgi duyulan en düşük frekans.
  • max_frequency (float) — Hz cinsinden en yüksek ilgi duyulan frekans. Bu değer sampling_rate / 2 değerini aşmamalıdır.
  • sampling_rate (int) — Ses dalgasının örneklem hızı.
  • norm (str, isteğe bağlı) — "slaney" ise, üçgen mel ağırlıkları mel bandının genişliğine bölünür (alan normalizasyonu).
  • mel_scale (str, isteğe bağlı, varsayılan "htk") — Kullanılacak mel frekans ölçeği, "htk", "kaldi" veya "slaney".
  • triangularize_in_mel_space (bool, isteğe bağlı, varsayılan False) — Bu seçenek etkinleştirilirse, üçgen filtre frekans alanı yerine mel alanında uygulanır. Mel filtreleri hesaplanırken torchaudio ile aynı sonuçları almak için bu değerin true olarak ayarlanması gerekir.

Dönüş değeri

(num_frequency_bins, num_mel_filters) biçiminde np.ndarray

Üçgen filtre bankası matrisi. Bu, bir spektrogramdan mel spektrograma geçmek için kullanılan bir projeksiyon matrisidir.

Mel spektrogramu elde etmek için kullanılan bir frekans bandı dönüşüm matrisi oluşturur. Buna mel filtre bankası denir ve filtre sayısı, filtrelerin şekli, filtrelerin aralıklanma biçimi, filtrelerin bant genişliği ve spektrumun eğrilendirilme yöntemi bakımından farklılık gösteren çeşitli uygulamalar mevcuttur. Bu özelliklerin amacı, frekansa göre ton yüksekliğindeki değişimin insan algısındaki doğrusal olmayan yapısını yaklaşık olarak modellemektir.

Edebiyatta farklı mel filtre bankaları tanıtılmıştır. Aşağıdaki varyasyonlar desteklenmektedir:

  • MFCC FB-20: 1980'de Davis ve Mermelstein tarafından tanıtılmıştır; 10 kHz örneklemleme frekansı ve [0, 4600] Hz ses bant genişliği varsayar.
  • MFCC FB-24 HTK: Cambridge HMM Toolkit (HTK) (1995), [0, 8000] Hz ses bant genişliği için 24 filtrelik bir filtre bankası kullanır. Bu, örneklem hızının ≥ 16 kHz olduğunu varsayar.
  • MFCC FB-40: 1998'de Slaney tarafından yazılan MATLAB Auditory Toolbox'tan alınmıştır, 16 kHz örneklem hızı ve [133, 6854] Hz konuşma bant genişliği varsayar. Bu sürüm ayrıca alan normalizasyonunu da içerir.
  • Skowronski ve Harris (2004)'in HFCC-E FB-29 (Human Factor Cepstral Coefficients) yöntemi, 12,5 kHz örnekleme hızı ve [0, 6250] Hz konuşma bant genişliği varsayar.

Bu kod torchaudio ve librosa kaynaklarından uyarlanmıştır. Not: torchaudio'nun melscale_fbanks varsayılan parametreleri "htk" filtrelerini uygularken librosa "slaney" uygulamasını kullanır.

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

Belirtilen window_length için en iyi FFT giriş boyutunu bulur. Bu fonksiyon, verilen pencere uzunluğunu alır ve eğer zaten iki'nin bir kuvveti değilse, bir üst kuvvete yuvarlar.

FFT algoritması, girdinin uzunluğu ikiyin bir kuvveti olduğunda en hızlı çalışır; bu değer pencere veya analiz çerçevesinin boyutundan büyük olabilir. Örneğin, pencere 400 örnek ise, 400 örneklik bir FFT boyutuna kıyasla 512 örneklik bir FFT girdi boyutu kullanmak daha optimaldir. Daha büyük bir FFT boyutu kullanmak, algılanan frekansları etkilemez; yalnızca daha yüksek bir frekans çözünürlüğü sağlar (yani frekans kutuları daha küçüktür).

transformers.audio_utils.window_function

< >

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

Parametreler

  • window_length (int) — Örnekteki pencere uzunluğu.
  • name (str, isteğe bağlı, varsayılan "hann") — Pencere işlevinin adı.
  • periodic (bool, isteğe bağlı, varsayılan True) — Pencerenin periyodik mi yoksa simetrik mi olduğu.
  • frame_length (int, isteğe bağlı) — Örnek cinsinden analiz çerçevelerinin uzunluğu. Pencere, çerçeve uzunluğundan küçükse, sıfır dolgusu yapılabilmesi için frame_length için bir değer belirtin.
  • center (bool, isteğe bağlı, varsayılan True) — Pencerenin FFT tamponunun içinde ortalanıp ortalanmayacağı. Yalnızca frame_length sağlandığında kullanılır.

Belirtilen pencereyi içeren bir dizi döndürür. Bu pencere, stft ile kullanılmak üzere tasarlanmıştır.

Desteklenen pencere türleri şunlardır:

  • "boxcar": dikdörtgen pencere
  • "hamming": Hamming penceresi
  • "hann": Hann penceresi
  • "povey": Povey penceresi

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

Parametreler

  • waveform (np.ndarray, şekli (length,)) — Giriş dalga formu. Bu, tek bir gerçek değerli, mono dalga formu olmalıdır.
  • window (np.ndarray, şekli (frame_length,)) — Uygulanacak pencereleme fonksiyonu, gerekirse sıfır dolgusunu da içerir. Gerçek pencere uzunluğu frame_length'ten kısa olabilir, ancak dizinin zaten sıfır doldurulduğu varsayılır.
  • frame_length (int) — Örnek cinsinden analiz çerçevelerinin uzunluğu. librosa ile bu her zaman fft_length'e eşittir ancak daha küçük boyutlara da izin veriyoruz.
  • hop_length (int) — Ardışık analiz çerçeveleri arasındaki örnek cinsinden adım.
  • fft_length (int, isteğe bağlı) — Örnekleme cinsinden FFT tamponunun boyutu. Bu, spektrogramın kaç frekans kutucuğu (bin) içereceğini belirler. Optimal hız için bu değerin ikiyin bir kuvveti olması gerekir. None ise frame_length kullanılır.
  • power (float, isteğe bağlı, varsayılan 1.0) — 1.0 ise genlik spektrogramını döndürür. 2.0 ise güç spektrogramını döndürür. None ise karmaşık sayıları döndürür.
  • center (bool, isteğe bağlı, varsayılan True) — Dalga formunun, t çerçevesinin t * hop_length zamanı etrafında ortalanacak şekilde dolgu (padding) alıp almayacağını belirtir. False ise, t çerçevesi t * hop_length zamanında başlar.
  • pad_mode (str, isteğe bağlı, varsayılan "reflect") — center True olduğunda kullanılan dolgu modu. Olası değerler: "constant" (sıfırlarla doldur), "edge" (kısa değerlerle doldur), "reflect" (aynalı değerlerle doldur).
  • onesided (bool, isteğe bağlı, varsayılan True) — True ise yalnızca pozitif frekansları hesaplar ve fft_length // 2 + 1 frekans kutucuğu içeren bir spektrogram döndürür. False ise negatif frekansları da hesaplar ve fft_length frekans kutucuğu döndürür.
  • dither (float, isteğe bağlı, varsayılan 0.0) — Dithering ekler. Başka bir deyişle, her kareye küçük bir Gauss gürültüsü ekler. Örn. 0.0 merkezli ve 4.0 standart sapmalı normal dağılımla dithering eklemek için 4.0 kullanın, 0.0 dithering olmadığı anlamına gelir. Dithering'in mel_floor ile benzer bir etkisi vardır. Sinyalde VAD kesme noktası (cutoff) mevcut olduğunda, sert-sıfır bölümlere sahip sinyallerin yüksek log_mel_fbank değerlerini azaltır.
  • preemphasis (float, isteğe bağlı) — DFT'den önce ön vurgu uygulayan bir alçak geçiren filtre için katsayı.
  • mel_filters (np.ndarray, şekli (num_freq_bins, num_mel_filters), isteğe bağlı) — Mel filtre bankası. Verilirse, mel spektrogram oluşturmak için bu filtre bankası uygulanır.
  • mel_floor (float, isteğe bağlı, varsayılan 1e-10) — Mel frekans bankalarının minimum değeri.
  • log_mel (str, isteğe bağlı) — Spektrogramın logaritmik ölçeğe nasıl dönüştürüleceğini belirtir. Olası seçenekler: None (dönüştürme), "log" (doğal logaritmayı al) "log10" (tabanı 10 olan logaritmayı al), "dB" (desibele dönüştür). Yalnızca power değeri None olmadığında kullanılabilir.
  • reference (float, isteğe bağlı, varsayılan 1.0) — 0 dB'ye karşılık gelen giriş spektrogram değerini ayarlar. Örneğin, en yüksek sesli kısmı 0 dB olarak ayarlamak için np.max(spectrogram) kullanın. Sıfırdan büyük olmalıdır.
  • min_value (float, isteğe bağlı, varsayılan 1e-10) — Spektrum, log(0) alınmasını önlemek için desibele dönüştürülmeden önce bu minimum değere kırpılır. Güç spektrumu için 1e-10 varsayılan değeri -100 dB'lik bir minimuma karşılık gelir. Genlik spektrumu için 1e-5 değeri -100 dB'ye karşılık gelir. Sıfırdan büyük olmalıdır.
  • db_range (float, isteğe bağlı) — Maksimum dinamik aralığı desibel cinsinden ayarlar. Örneğin, db_range = 80 ise, tepe değeri ile en küçük değer arasındaki fark asla 80 dB'den fazla olmaz. Sıfırdan büyük olmalıdır.
  • remove_dc_offset (bool, isteğe bağlı) — Her karede dalga formundan ortalama değer çıkarılır; bu işlem ön vurgulamadan (pre-emphasis) önce uygulanır. Mel filtrelerinin hesaplanmasında torchaudio.compliance.kaldi.fbank ile aynı sonuçları almak için bu değer true olarak ayarlanmalıdır.
  • dtype (np.dtype, isteğe bağlı, varsayılan np.float32) — Spektrum gergisinin veri türü. power None ise, bu argüman yok sayılır ve veri türü np.complex64 olur.

Kısa Süreli Fourier Dönüşümü kullanarak tek bir dalga formu üzerinde spektrogram hesaplar.

Bu fonksiyon aşağıdaki türlerde spektrogramlar oluşturabilir:

  • genlik spektrogramı (power = 1.0)
  • güç spektrogramı (power = 2.0)
  • kompleks değerli spektrogram (power = None)
  • spektrogram (log) (log_mel argümanını kullanın)
  • mel spektrogramu (mel_filters sağla)
  • log-mel spektrogramu (mel_filters ve log_mel sağla)

Bunun nasıl çalıştığı:

  1. Giriş dalga formu, frame_length boyutundaki ve `frame_length` örnek kadar kısmen üst üste binen çerçevelere bölünür.
    • hop_length` örnek.
  2. Her çerçeve, pencere ile çarpılır ve fft_length boyutundaki bir tampona yerleştirilir.
  3. DFT, her pencere uygulanmış çerçevenin alınır.
  4. Sonuçlar bir spektrograma yığılır.

Örnek verilerin aşağıdaki “blokları” arasında bir ayrım yapıyoruz; bunların her birinin farklı uzunluklara sahip olması mümkündür:

  • Analiz çerçevesi. Bu, giriş dalga formunun bölündüğü zaman dilimlerinin boyutudur.
  • Pencere. Spektral sızıntıyı önlemek için her analiz çerçevesi pencere ile çarpılır.
  • FFT giriş tamponu. Bu tamponun uzunluğu, spektrogramdaki frekans kutularının sayısını belirler.

Bu uygulamada, pencerenin analiz çerçevesiyle aynı boyuta sahip olması için sıfır dolgulu olduğu varsayılır. Dolgulu bir pencere, window_function() işlevinden elde edilebilir. FFT giriş tamponu, genellikle bir sonraki iki kuvveti olan, analiz çerçevesinden daha büyük olabilir.

Not: Bu fonksiyon henüz hız için optimize edilmemiştir. Spektrogramların oluşturulabileceği farklı yöntemler nedeniyle daha esnek olmakla birlikte, büyük ölçüde librosa.stft ve torchaudio.functional.transforms.Spectrogram ile uyumlu olmalıdır.

transformers.audio_utils.power_to_db

< >

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

Parametreler

  • spectrogram (np.ndarray) — Girdi güç (mel) spektrogramı. Not: bir güç spektrogramında genlikler karelenmiştir!
  • reference (float, isteğe bağlı, varsayılan 1.0) — 0 dB'ye karşılık gelen giriş spektrogram değerini ayarlar. Örneğin, en yüksek sesli kısmı 0 dB olarak ayarlamak için np.max(spectrogram) kullanın. Sıfırdan büyük olmalıdır.
  • min_value (float, isteğe bağlı, varsayılan 1e-10) — Spektrum, log(0) alınmasını önlemek için desibele dönüştürülmeden önce bu minimum değere kırpılır. 1e-10 varsayılanı, -100 dB'lik bir minimuma karşılık gelir. Sıfırdan büyük olmalıdır.
  • db_range (float, isteğe bağlı) — Maksimum dinamik aralığı desibel cinsinden ayarlar. Örneğin, db_range = 80 ise, tepe değeri ile en küçük değer arasındaki fark asla 80 dB'den fazla olmaz. Sıfırdan büyük olmalıdır.

Dönüş değeri

np.ndarray

desibel cinsinden spektrogram

Güç spektrogramını desibel ölçeğine dönüştürür. Bu, sayısal kararlılık için temel logaritma özelliklerini kullanarak 10 * log10(spectrogram / reference) ifadesini hesaplar.

(mel) spektrograma logaritma fonksiyonunun uygulanmasındaki motivasyon, insanların ses şiddetini doğrusal bir ölçekle algılamamasıdır. Genel olarak bir sesin algılanan ses seviyesini ikiye katlamak için enerjisini 8 kat artırmak gerekir. Bu da, ses zaten yüksekse, enerji üzerindeki büyük değişimlerin o kadar da farklı duyulmayabileceği anlamına gelir. Bu sıkıştırma işlemi, (mel) spektrogram özelliklerinin insanların aslında duyduklarıyla daha yakından örtüşmesini sağlar.

librosa.power_to_db uygulamasına dayanır.

transformers.audio_utils.amplitude_to_db

< >

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

Parametreler

  • spectrogram (np.ndarray) — Girdi genlik (mel) spektrogramı.
  • reference (float, isteğe bağlı, varsayılan 1.0) — 0 dB'ye karşılık gelen giriş spektrogram değerini ayarlar. Örneğin, en yüksek sesli kısmı 0 dB olarak ayarlamak için np.max(spectrogram) kullanın. Sıfırdan büyük olmalıdır.
  • min_value (float, isteğe bağlı, varsayılan 1e-5) — Spektrum, log(0) alınmasını önlemek için desibele dönüştürülmeden önce bu minimum değere kırpılır. 1e-5 varsayılanı, -100 dB'lik bir minimuma karşılık gelir. Sıfırdan büyük olmalıdır.
  • db_range (float, isteğe bağlı) — Maksimum dinamik aralığı desibel cinsinden ayarlar. Örneğin, db_range = 80 ise, tepe değeri ile en küçük değer arasındaki fark asla 80 dB'den fazla olmaz. Sıfırdan büyük olmalıdır.

Dönüş değeri

np.ndarray

desibel cinsinden spektrogram

Amplitüd spektrogramını desibel ölçeğine dönüştürür. Bu, sayısal kararlılık için temel logaritma özelliklerini kullanarak 20 * log10(spectrogram / reference) ifadesini hesaplar.

(mel) spektrograma logaritma fonksiyonunun uygulanmasındaki motivasyon, insanların ses şiddetini doğrusal bir ölçekle algılamamasıdır. Genel olarak bir sesin algılanan ses seviyesini ikiye katlamak için enerjisini 8 kat artırmak gerekir. Bu da, ses zaten yüksekse, enerji üzerindeki büyük değişimlerin o kadar da farklı duyulmayabileceği anlamına gelir. Bu sıkıştırma işlemi, (mel) spektrogram özelliklerinin insanların aslında duyduklarıyla daha yakından örtüşmesini sağlar.

Update on GitHub

←Görüntü işleyicileri için yardımcı programlar Genel yardımcılar→