Transformers documentation

Utilitários para FeatureExtractors

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

and get access to the augmented documentation experience

to get started

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

< >

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

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 utilizada, "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

< >

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

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 utilizada: "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

< >

( 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 a 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 utilizada, "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 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".

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

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

< >

( 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ão True) — 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 deve centralizar a janela dentro do buffer da FFT. Usado apenas quando frame_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

< >

( 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.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 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 for None, usa frame_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. Se None, retorna números complexos.
  • center (bool, opcional, padrão True) — Indica se a forma de onda deve ser preenchida 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, 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 as mel_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.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" (aplicar o logaritmo natural) "log10" (aplicar 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.

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. O sinal de entrada é dividido em quadros de tamanho frame_length que se sobrepõem parcialmente em `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

< >

( 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, 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 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

< >

( 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, 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 valor 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 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.

Update on GitHub