Transformers documentation
Utilitários para FeatureExtractors
Utilitários para FeatureExtractors
Esta página lista todas as funções utilitárias que podem ser usadas pelo FeatureExtractor de áudio para calcular recursos especiais a partir de um áudio bruto, utilizando algoritmos comuns como a Short Time Fourier Transform ou o log mel spectrogram.
A maioria delas só é útil se você estiver estudando o código dos processadores de áudio na biblioteca.
Transformações de Áudio
transformers.audio_utils.hertz_to_mel
< source >( freq: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
Converte a frequência de hertz para mels.
transformers.audio_utils.mel_to_hertz
< source >( mels: float | numpy.ndarraymel_scale: str = 'htk' ) → float or np.ndarray
Converte a frequência de mels para 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)
Parâmetros
- num_frequency_bins (
int) — Número de bins de frequência (deve ser igual an_fft // 2 + 1, onden_ffté o tamanho da Transformada de Fourier usada para calcular o espectrograma). - num_mel_filters (
int) — Número de filtros mel a serem gerados. - min_frequency (
float) — Frequência mínima de interesse em Hz. - max_frequency (
float) — Frequência máxima de interesse em Hz. Este valor não deve excedersampling_rate / 2. - sampling_rate (
int) — Taxa de amostragem da forma de onda de áudio. - norm (
str, opcional) — Se"slaney", divide os pesos triangulares de mel pela largura da banda de mel (normalização de área). - mel_scale (
str, opcional, padrão"htk") — A escala de frequência mel a ser utilizada,"htk","kaldi"ou"slaney". - triangularize_in_mel_space (
bool, opcional, padrãoFalse) — Se esta opção estiver habilitada, o filtro triangular é aplicado no espaço mel em vez do espaço de frequência. Isso deve ser definido comotruepara obter os mesmos resultados que otorchaudioao calcular filtros mel.
Retorna
np.ndarray de forma (num_frequency_bins, num_mel_filters)
Matriz do banco de filtros triangular. Esta é uma matriz de projeção para converter um espectrograma em um espectrograma mel.
Cria uma matriz de conversão de bandas de frequência usada para obter um espectrograma mel. Isso é chamado de mel filter bank, e existem várias implementações, que diferem no número de filtros, na forma dos filtros, na forma como os filtros são espaçados, na largura de banda dos filtros e na maneira como o espectro é distorcido. O objetivo desses recursos é aproximar a percepção não linear humana da variação de tom em relação à frequência.
Diferentes bancos de filtros mel foram introduzidos na literatura. As seguintes variações são suportadas:
- MFCC FB-20: introduzido em 1980 por Davis e Mermelstein, ele assume uma frequência de amostragem de 10 kHz e uma largura de banda de fala de
[0, 4600]Hz. - MFCC FB-24 HTK: do Cambridge HMM Toolkit (HTK) (1995), utiliza um banco de filtros com 24 filtros para uma largura de banda de fala de
[0, 8000]Hz. Isso pressupõe uma taxa de amostragem ≥ 16 kHz. - MFCC FB-40: derivado do Auditory Toolbox para MATLAB, escrito por Slaney em 1998, assume uma taxa de amostragem de 16 kHz e uma largura de banda de fala de
[133, 6854]Hz. Esta versão também inclui normalização de área. - O HFCC-E FB-29 (Human Factor Cepstral Coefficients) de Skowronski e Harris (2004) pressupõe uma taxa de amostragem de 12,5 kHz e uma largura de banda da fala de
[0, 6250]Hz.
Este código é adaptado de torchaudio e librosa. Observe que os parâmetros padrão de melscale_fbanks do torchaudio implementam os filtros "htk", enquanto o librosa usa a implementação "slaney".
Encontra o melhor tamanho de entrada de FFT para um determinado window_length. Esta função recebe um comprimento de janela e, se ele não for
uma potência de dois, arredonda para a próxima potência de dois.
O algoritmo FFT funciona mais rápido quando o comprimento da entrada é uma potência de dois, o que pode ser maior que o tamanho da janela ou do quadro de análise. Por exemplo, se a janela for de 400 amostras, usar um tamanho de entrada FFT de 512 amostras é mais otimizado do que um tamanho FFT de 400 amostras. Usar um tamanho FFT maior não afeta as frequências detectadas, ele simplesmente fornece uma resolução de frequência mais alta (ou seja, os bins de frequência são menores).
transformers.audio_utils.window_function
< source >( window_length: intname: str = 'hann'periodic: bool = Trueframe_length: int | None = Nonecenter: bool = True )
Parâmetros
- window_length (
int) — O comprimento da janela em amostras. - name (
str, opcional, padrão"hann") — O nome da função de janela. - periodic (
bool, opcional, padrãoTrue) — Se a janela é periódica ou simétrica. - frame_length (
int, opcional) — O comprimento dos quadros de análise em amostras. Forneça um valor paraframe_lengthse a janela for menor que o comprimento do quadro, para que ele seja preenchido com zeros. - center (
bool, opcional, padrãoTrue) — Se deve centralizar a janela dentro do buffer da FFT. Usado apenas quandoframe_lengthé fornecido.
Retorna um array contendo a janela especificada. Esta janela destina-se a ser usada com stft.
Os seguintes tipos de janela são suportados:
"boxcar": uma janela retangular"hamming": a janela de Hamming"hann": a janela de Hann"povey": a janela 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'> )
Parâmetros
- waveform (
np.ndarrayde forma(length,)) — A forma de onda de entrada. Esta deve ser uma forma de onda mono, de valor real único. - window (
np.ndarrayde forma(frame_length,)) — A função de janelamento a ser aplicada, incluindo o preenchimento com zeros, se necessário. O comprimento real da janela pode ser menor queframe_length, mas assumimos que o array já foi preenchido com zeros. - frame_length (
int) — O comprimento dos quadros de análise em amostras. Com o librosa, isso é sempre igual afft_length, mas também permitimos tamanhos menores. - hop_length (
int) — O deslocamento entre os quadros de análise sucessivos, em amostras. - fft_length (
int, opcional) — O tamanho do buffer de FFT em amostras. Isso determina quantos bins de frequência o espectrograma terá. Para velocidade ótima, este valor deve ser uma potência de dois. Se forNone, usaframe_length. - power (
float, opcional, padrão 1.0) — Se 1.0, retorna o espectrograma de amplitude. Se 2.0, retorna o espectrograma de potência. SeNone, retorna números complexos. - center (
bool, opcional, padrãoTrue) — Indica se a forma de onda deve ser preenchida para que o quadrotesteja centralizado em torno do tempot * hop_length. SeFalse, o quadrotcomeçará no tempot * hop_length. - pad_mode (
str, opcional, padrão"reflect") — Modo de preenchimento usado quandocenteréTrue. Os valores possíveis são:"constant"(preenche com zeros),"edge"(preenche com os valores da borda),"reflect"(preenche com valores espelhados). - onesided (
bool, opcional, padrãoTrue) — Se True, calcula apenas as frequências positivas e retorna um espectrograma contendofft_length // 2 + 1bins de frequência. Se False, também calcula as frequências negativas e retornafft_lengthbins de frequência. - 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, opcional) — Coeficiente para um filtro passa-baixa que aplica pré-ênfase antes da DFT. - mel_filters (
np.ndarrayde forma(num_freq_bins, num_mel_filters), opcional) — O banco de filtros mel. Se fornecido, aplica este banco de filtros para criar um espectrograma mel. - mel_floor (
float, opcional, padrão 1e-10) — Valor mínimo dos bancos de frequência mel. - log_mel (
str, opcional) — Como converter o espectrograma para a escala logarítmica. As opções possíveis são:None(não converter),"log"(aplicar o logaritmo natural)"log10"(aplicar o logaritmo na base 10),"dB"(converter para decibéis). Pode ser usado apenas quandopowernão forNone. - reference (
float, opcional, padrão 1.0) — Define o valor do espectrograma de entrada que corresponde a 0 dB. Por exemplo, usenp.max(spectrogram)para definir a parte mais alta como 0 dB. Deve ser maior que zero. - min_value (
float, opcional, padrão1e-10) — O espectrograma será limitado a este valor mínimo antes da conversão para decibéis, para evitar calcularlog(0). Para um espectrograma de potência, o valor padrão de1e-10corresponde a um mínimo de -100 dB. Para um espectrograma de amplitude, o valor1e-5corresponde a -100 dB. Deve ser maior que zero. - db_range (
float, opcional) — Define a faixa dinâmica máxima em decibéis. Por exemplo, sedb_range = 80, a diferença entre o valor de pico e o menor valor nunca será superior a 80 dB. Deve ser maior que zero. - remove_dc_offset (
bool, opcional) — Subtrai a média da forma de onda em cada quadro, aplicado antes da pré-ênfase. Isso deve ser definido comotruepara obter os mesmos resultados quetorchaudio.compliance.kaldi.fbankao calcular os filtros mel. - dtype (
np.dtype, opcional, padrãonp.float32) — Tipo de dados do tensor do espectrograma. Sepowerfor None, este argumento é ignorado e o dtype seránp.complex64.
Calcula um espectrograma sobre uma forma de onda usando a Transformada de Fourier de Tempo Curto.
Esta função pode criar os seguintes tipos de espectrogramas:
- espectrograma de amplitude (
power = 1.0) - espectrograma de potência (
power = 2.0) - espectrograma de valores complexos (
power = None) - espectrograma log (use o argumento
log_mel) - espectrograma mel (fornecer
mel_filters) - espectrograma log-mel (forneça
mel_filterselog_mel)
Como isso funciona:
- O sinal de entrada é dividido em quadros de tamanho
frame_lengthque se sobrepõem parcialmente em `frame_length- amostras de `hop_length`.
- Cada quadro é multiplicado pela janela e colocado em um buffer de tamanho
fft_length. - A DFT é calculada para cada janela de quadro.
- Os resultados são empilhados em um espectrograma.
Fazemos uma distinção entre os seguintes “blocos” de dados de exemplo, cada um dos quais pode ter um comprimento diferente:
- O quadro de análise. Este é o tamanho das fatias de tempo em que a forma de onda de entrada é dividida.
- A janela. Cada quadro de análise é multiplicado pela janela para evitar vazamento espectral.
- O buffer de entrada da FFT. O comprimento deste determina quantos bins de frequência há no espectrograma.
Nesta implementação, assume-se que a janela é preenchida com zeros para ter o mesmo tamanho que o quadro de análise. Uma janela preenchida pode ser obtida a partir de window_function(). O buffer de entrada da FFT pode ser maior que o quadro de análise, tipicamente a próxima potência de dois.
Observação: Esta função ainda não foi otimizada para velocidade. Ela deve ser compatível, em grande parte, com librosa.stft e torchaudio.functional.transforms.Spectrogram, embora seja mais flexível devido às diferentes maneiras pelas quais os espectrogramas podem ser construídos.
transformers.audio_utils.power_to_db
< source >( spectrogram: ndarrayreference: float = 1.0min_value: float = 1e-10db_range: float | None = None ) → np.ndarray
Parâmetros
- spectrogram (
np.ndarray) — O espectrograma de potência (mel) de entrada. Observe que um espectrograma de potência tem as amplitudes ao quadrado! - reference (
float, opcional, padrão 1.0) — Define o valor do espectrograma de entrada que corresponde a 0 dB. Por exemplo, usenp.max(spectrogram)para definir a parte mais alta como 0 dB. Deve ser maior que zero. - min_value (
float, opcional, padrão1e-10) — O espectrograma será limitado a este valor mínimo antes da conversão para decibéis, para evitar calcularlog(0). O padrão de1e-10corresponde a um mínimo de -100 dB. Deve ser maior que zero. - db_range (
float, opcional) — Define a faixa dinâmica máxima em decibéis. Por exemplo, sedb_range = 80, a diferença entre o valor de pico e o menor valor nunca será superior a 80 dB. Deve ser maior que zero.
Retorna
np.ndarray
o espectrograma em decibéis
Converte um espectrograma de potência para a escala de decibéis. Isso calcula 10 * log10(spectrogram / reference), usando propriedades básicas de logaritmos para estabilidade numérica.
A motivação para aplicar a função log na espectrograma (mel) é que os humanos não percebem a intensidade sonora em uma escala linear. Em geral, para dobrar o volume percebido de um som, é necessário aumentar sua energia em 8 vezes. Isso significa que grandes variações de energia podem não soar muito diferentes se o som já for alto por natureza. Essa operação de compressão faz com que os recursos da espectrograma (mel) correspondam mais de perto ao que os humanos realmente ouvem.
Com base na implementação de 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
Parâmetros
- spectrogram (
np.ndarray) — O espectrograma de amplitude (mel) de entrada. - reference (
float, opcional, padrão 1.0) — Define o valor do espectrograma de entrada que corresponde a 0 dB. Por exemplo, usenp.max(spectrogram)para definir a parte mais alta como 0 dB. Deve ser maior que zero. - min_value (
float, opcional, padrão1e-5) — O espectrograma será limitado a este valor mínimo antes da conversão para decibéis, para evitar calcularlog(0). O valor padrão de1e-5corresponde a um mínimo de -100 dB. Deve ser maior que zero. - db_range (
float, opcional) — Define a faixa dinâmica máxima em decibéis. Por exemplo, sedb_range = 80, a diferença entre o valor de pico e o menor valor nunca será superior a 80 dB. Deve ser maior que zero.
Retorna
np.ndarray
o espectrograma em decibéis
Converte um espectrograma de amplitude para a escala de decibéis. Isso calcula 20 * log10(spectrogram / reference), usando
propriedades básicas do logaritmo para estabilidade numérica.
A motivação para aplicar a função log na espectrograma (mel) é que os humanos não percebem a intensidade sonora em uma escala linear. Em geral, para dobrar o volume percebido de um som, é necessário aumentar sua energia em 8 vezes. Isso significa que grandes variações de energia podem não soar muito diferentes se o som já for alto por natureza. Essa operação de compressão faz com que os recursos da espectrograma (mel) correspondam mais de perto ao que os humanos realmente ouvem.