# 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]] #### 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') ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L554) **Parâmetros:** freq (`float` ou `np.ndarray`) : A frequência, ou múltiplas frequências, em hertz (Hz). mel_scale (`str`, *opcional*, padrão `"htk"`) : A escala de frequência mel a ser usada, `"htk"`, `"kaldi"` ou `"slaney"`. **Retorna:** `float` ou `np.ndarray` As frequências na escala mel. Converte a frequência de hertz para 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') ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L590) **Parâmetros:** mels (`float` ou `np.ndarray`) : A frequência, ou múltiplas frequências, em mels. mel_scale (`str`, *opcional*, `"htk"`) : A escala de frequência mel a ser usada, `"htk"`, `"kaldi"` ou `"slaney"`. **Retorna:** `float` ou `np.ndarray` As frequências em hertz. Converte a frequência de mels para 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L744) **Parâmetros:** num_frequency_bins (`int`) : Número de bins de frequência (deve ser o mesmo que `n_fft // 2 + 1`, onde `n_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 exceder `sampling_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 usada, `"htk"`, `"kaldi"` ou `"slaney"`. triangularize_in_mel_space (`bool`, *opcional*, padrão `False`) : 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 como `true` para obter os mesmos resultados que o `torchaudio` ao calcular os 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 *banco de filtros mel*, e existem diversas 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, pressupõe 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 faixa de frequência 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 de 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"`. #### transformers.audio_utils.optimal_fft_length[[transformers.audio_utils.optimal_fft_length]] ```python transformers.audio_utils.optimal_fft_length(window_length: int) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L838) Encontra o melhor tamanho de entrada de FFT para um determinado `window_length`. Esta função recebe um comprimento de janela e, se este não for uma potência de dois, arredonda-o 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[[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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L851) **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ão `True`) : Indica 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 para `frame_length` se a janela for menor que o comprimento do quadro, para que ele seja preenchido com zeros. center (`bool`, *opcional*, padrão `True`) : Se centralizar a janela dentro do buffer da FFT. Usado apenas quando `frame_length` é fornecido. **Retorna:** `np.ndarray` de forma `(window_length,)` ou `(frame_length,)` contendo a janela. 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[[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 = ) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L915) **Parâmetros:** waveform (`np.ndarray` de forma `(length,)`) : A forma de onda de entrada. Esta deve ser uma forma de onda mono, de valor real único. window (`np.ndarray` de 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 que `frame_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 a `fft_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 da FFT em amostras. Isso determina quantos bins de frequência o espectrograma terá. Para velocidade ideal, este valor deve ser uma potência de dois. Se for `None`, usa `frame_length`. power (`float`, *opcional*, padrão 1.0) : Se for 1.0, retorna o espectrograma de amplitude. Se for 2.0, retorna o espectrograma de potência. Se for `None`, retorna números complexos. center (`bool`, *opcional*, padrão `True`) : Se deve aplicar padding à forma de onda para que o quadro `t` esteja centralizado em torno do tempo `t * hop_length`. Se `False`, o quadro `t` começará no tempo `t * hop_length`. pad_mode (`str`, *opcional*, padrão `"reflect"`) : Modo de preenchimento usado quando `center` é `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ão `True`) : Se True, calcula apenas as frequências positivas e retorna um espectrograma contendo `fft_length // 2 + 1` bins de frequência. Se False, também calcula as frequências negativas e retorna `fft_length` bins de frequência. dither (`float`, *opcional*, padrão 0.0) : Adiciona dithering. Em outras palavras, adiciona um pequeno ruído gaussiano a cada quadro. Por exemplo, use 4.0 para adicionar dithering com uma distribuição normal centrada em 0.0 com desvio padrão de 4.0; 0.0 significa sem dithering. O dithering tem efeito semelhante ao de `mel_floor`. Ele reduz os valores altos de log_mel_fbank para sinais com seções de zero duro, quando há um corte de VAD presente no sinal. preemphasis (`float`, *opcional*) : Coeficiente para um filtro passa-baixa que aplica pré-ênfase antes da DFT. mel_filters (`np.ndarray` de 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"` (calcular o logaritmo natural) `"log10"` (calcular o logaritmo na base 10), `"dB"` (converter para decibéis). Pode ser usado apenas quando `power` não for `None`. reference (`float`, *opcional*, padrão 1.0) : Define o valor do espectrograma de entrada que corresponde a 0 dB. Por exemplo, use `np.max(spectrogram)` para definir a parte mais alta como 0 dB. Deve ser maior que zero. min_value (`float`, *opcional*, padrão `1e-10`) : O espectrograma será limitado a este valor mínimo antes da conversão para decibéis, para evitar calcular `log(0)`. Para um espectrograma de potência, o valor padrão de `1e-10` corresponde a um mínimo de -100 dB. Para um espectrograma de amplitude, o valor `1e-5` corresponde a -100 dB. Deve ser maior que zero. db_range (`float`, *opcional*) : Define a faixa dinâmica máxima em decibéis. Por exemplo, se `db_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 como `true` para obter os mesmos resultados que `torchaudio.compliance.kaldi.fbank` ao calcular os filtros mel. dtype (`np.dtype`, *opcional*, padrão `np.float32`) : Tipo de dados do tensor do espectrograma. Se `power` for None, este argumento é ignorado e o dtype será `np.complex64`. **Retorna:** `nd.array` contendo um espectrograma com formato `(num_frequency_bins, length)` para um espectrograma regular ou formato `(num_mel_filters, length)` para um espectrograma mel. 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_filters` e `log_mel`) Como isso funciona: 1. A forma de onda de entrada é dividida em quadros de tamanho `frame_length` que se sobrepõem parcialmente por `frame_length - amostras de `hop_length`. 2. Cada quadro é multiplicado pela janela e colocado em um buffer de tamanho `fft_length`. 3. A DFT é calculada para cada janela de quadro. 4. 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[[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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1337) **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, use `np.max(spectrogram)` para definir a parte mais alta como 0 dB. Deve ser maior que zero. min_value (`float`, *opcional*, padrão `1e-10`) : O espectrograma será limitado a este valor mínimo antes da conversão para decibéis, para evitar calcular `log(0)`. O padrão de `1e-10` corresponde 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, se `db_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 do logaritmo para estabilidade numérica. A motivação por trás da aplicação da função log no 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 em primeiro lugar. Essa operação de compressão faz com que os recursos do 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[[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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1437) **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, use `np.max(spectrogram)` para definir a parte mais alta como 0 dB. Deve ser maior que zero. min_value (`float`, *opcional*, padrão `1e-5`) : O espectrograma será limitado a este valor mínimo antes da conversão para decibéis, para evitar calcular `log(0)`. O padrão de `1e-5` corresponde 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, se `db_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 por trás da aplicação da função log no 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 em primeiro lugar. Essa operação de compressão faz com que os recursos do espectrograma (mel) correspondam mais de perto ao que os humanos realmente ouvem.