Transformers documentation

Utilitaires pour les 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

Utilitaires pour les FeatureExtractors

Cette page répertorie toutes les fonctions utilitaires que le FeatureExtractor audio peut utiliser afin de calculer des caractéristiques spécifiques à partir d'un audio brut en utilisant des algorithmes courants tels que la Short Time Fourier Transform ou le log mel spectrogram.

La plupart de ces éléments ne sont utiles que si vous étudiez le code des processeurs audio de la bibliothèque.

Transformations audio

transformers.audio_utils.hertz_to_mel

< >

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

Paramètres

  • freq (float ou np.ndarray) — La fréquence, ou les fréquences multiples, en hertz (Hz).
  • mel_scale (str, facultatif, par défaut "htk") — L'échelle de fréquences mel à utiliser, "htk", "kaldi" ou "slaney".

Retourne

float ou np.ndarray

Les fréquences sur l'échelle mélo.

Convertir la fréquence d'heurts en mels.

transformers.audio_utils.mel_to_hertz

< >

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

Paramètres

  • mels (float ou np.ndarray) — La fréquence, ou les fréquences multiples, en mels.
  • mel_scale (str, facultatif, "htk") — L'échelle de fréquences mel à utiliser, "htk", "kaldi" ou "slaney".

Retourne

float ou np.ndarray

Les fréquences en hertz.

Convertir la fréquence des mels en 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)

Paramètres

  • num_frequency_bins (int) — Nombre de bandes de fréquence (doit être identique à n_fft // 2 + 1 où n_fft est la taille de la transformée de Fourier utilisée pour calculer le spectrogramme).
  • num_mel_filters (int) — Nombre de filtres mel à générer.
  • min_frequency (float) — Fréquence minimale d'intérêt en Hz.
  • max_frequency (float) — Fréquence maximale d'intérêt en Hz. Elle ne doit pas dépasser sampling_rate / 2.
  • sampling_rate (int) — Taux d'échantillonnage de la forme d'onde audio.
  • norm (str, facultatif) — Si "slaney", divise les poids triangulaires mel par la largeur de la bande mel (normalisation de surface).
  • mel_scale (str, facultatif, par défaut "htk") — L'échelle de fréquences mel à utiliser, "htk", "kaldi" ou "slaney".
  • triangularize_in_mel_space (bool, facultatif, par défaut False) — Si cette option est activée, le filtre triangulaire est appliqué dans l’espace mel plutôt que dans l’espace des fréquences. Il convient de définir cette valeur sur true afin d’obtenir les mêmes résultats que torchaudio lors du calcul des filtres mel.

Retourne

np.ndarray de forme (num_frequency_bins, num_mel_filters)

Matrice de banque de filtres triangulaire. Il s'agit d'une matrice de projection pour passer d'un spectrogramme à un spectrogramme mel.

Crée une matrice de conversion de bandes de fréquences utilisée pour obtenir un spectrogramme mel. Il s’agit d’une banque de filtres mel, et plusieurs implémentations existent, qui diffèrent par le nombre de filtres, la forme des filtres, la manière dont les filtres sont espacés, la bande passante des filtres et la façon dont le spectre est déformé. L’objectif de ces caractéristiques est d’approximer la perception non linéaire humaine de la variation de la hauteur de ton en fonction de la fréquence.

Différentes banques de filtres mel ont été introduites dans la littérature. Les variations suivantes sont prises en charge :

  • MFCC FB-20 : introduit en 1980 par Davis et Mermelstein, il suppose une fréquence d'échantillonnage de 10 kHz et une bande passante vocale de [0, 4600] Hz.
  • MFCC FB-24 HTK : issue de la Cambridge HMM Toolkit (HTK) (1995), elle utilise une banque de filtres de 24 filtres pour une bande passante vocale de [0, 8000] Hz. Cela suppose un taux d'échantillonnage ≥ 16 kHz.
  • MFCC FB-40 : issu de l’Auditory Toolbox pour MATLAB, rédigé par Slaney en 1998, il suppose un taux d’échantillonnage de 16 kHz et une bande passante de la parole de [133, 6854] Hz. Cette version inclut également une normalisation de surface.
  • HFCC-E FB-29 (Human Factor Cepstral Coefficients) de Skowronski et Harris (2004) suppose un taux d'échantillonnage de 12,5 kHz et une bande passante de la parole de [0, 6250] Hz.

Ce code est adapté de torchaudio et librosa. Notez que les paramètres par défaut de melscale_fbanks de torchaudio implémentent les filtres "htk", tandis que librosa utilise l'implémentation "slaney".

transformers.audio_utils.optimal_fft_length

< >

( window_length: int )

Trouve la meilleure taille d'entrée FFT pour une window_length donnée. Cette fonction prend une longueur de fenêtre donnée et, si elle n'est pas déjà une puissance de deux, l'arrondit à la puissance de deux supérieure.

L'algorithme FFT fonctionne le plus rapidement lorsque la longueur de l'entrée est une puissance de deux, ce qui peut être supérieur à la taille de la fenêtre ou du cadre d'analyse. Par exemple, si la fenêtre est de 400 échantillons, l'utilisation d'une taille d'entrée FFT de 512 échantillons est plus optimale qu'une taille FFT de 400 échantillons. L'utilisation d'une taille FFT plus grande n'affecte pas les fréquences détectées, elle donne simplement une résolution de fréquence plus élevée (c'est-à-dire que les bins de fréquence sont plus petits).

transformers.audio_utils.window_function

< >

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

Paramètres

  • window_length (int) — La longueur de la fenêtre en échantillons.
  • name (str, facultatif, par défaut "hann") — Le nom de la fonction de fenêtre.
  • periodic (bool, facultatif, par défaut True) — Indique si la fenêtre est périodique ou symétrique.
  • frame_length (int, facultatif) — La longueur des trames d'analyse en échantillons. Fournissez une valeur pour frame_length si la fenêtre est plus petite que la longueur de la trame, afin qu'elle soit complétée par des zéros.
  • center (bool, facultatif, par défaut True) — Indique s'il faut centrer la fenêtre à l'intérieur du tampon FFT. Utilisé uniquement lorsque frame_length est fourni.

Retourne un tableau contenant la fenêtre spécifiée. Cette fenêtre est destinée à être utilisée avec stft.

Les types de fenêtre suivants sont pris en charge :

  • "boxcar" : une fenêtre rectangulaire
  • "hamming" : la fenêtre de Hamming
  • "hann" : la fenêtre de Hann
  • "povey" : la fenêtre de 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'> )

Paramètres

  • waveform (np.ndarray de forme (length,)) — La forme d'onde d'entrée. Il doit s'agir d'une forme d'onde mono à valeurs réelles.
  • window (np.ndarray de forme (frame_length,)) — La fonction de fenêtrage à appliquer, y compris le bourrage de zéros si nécessaire. La longueur réelle de la fenêtre peut être inférieure à frame_length, mais nous supposons que le tableau a déjà été bourré de zéros.
  • frame_length (int) — La longueur des trames d’analyse en échantillons. Avec librosa, elle est toujours égale à fft_length, mais nous autorisons également des tailles plus petites.
  • hop_length (int) — La distance entre les trames d'analyse successives, en échantillons.
  • fft_length (int, facultatif) — La taille du tampon FFT en échantillons. Cela détermine le nombre de bandes de fréquences que contiendra le spectrogramme. Pour une vitesse optimale, cette valeur doit être une puissance de deux. Si None, utilise frame_length.
  • power (float, facultatif, valeur par défaut 1.0) — Si 1.0, renvoie le spectrogramme d'amplitude. Si 2.0, renvoie le spectrogramme de puissance. Si None, renvoie des nombres complexes.
  • center (bool, facultatif, par défaut True) — Indique s'il faut compléter le signal par des zéros afin que la trame t soit centrée sur le temps t * hop_length. Si False, la trame t commence au temps t * hop_length.
  • pad_mode (str, facultatif, par défaut "reflect") — Mode de bourrage utilisé lorsque center est True. Les valeurs possibles sont : "constant" (bourrage avec des zéros), "edge" (bourrage avec les valeurs des bords), "reflect" (bourrage avec des valeurs miroir).
  • onesided (bool, facultatif, par défaut True) — Si True, ne calcule que les fréquences positives et renvoie un spectrogramme contenant fft_length // 2 + 1 bins de fréquence. Si False, calcule également les fréquences négatives et renvoie fft_length bins de fréquence.
  • 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, facultatif) — Coefficient d'un filtre passe-bas qui applique une pré-emphase avant la TFD.
  • mel_filters (np.ndarray de forme (num_freq_bins, num_mel_filters), facultatif) — La banque de filtres mel. Si fournie, applique cette banque de filtres pour créer un spectrogramme mel.
  • mel_floor (float, facultatif, par défaut 1e-10) — Valeur minimale des banques de fréquences mel.
  • log_mel (str, facultatif) — Méthode de conversion du spectrogramme en échelle logarithmique. Les options possibles sont : None (aucune conversion), "log" (prendre le logarithme naturel) "log10" (prendre le logarithme en base 10), "dB" (convertir en décibels). Ne peut être utilisé que lorsque power n’est pas None.
  • reference (float, facultatif, par défaut 1.0) — Définit la valeur du spectrogramme d'entrée correspondant à 0 dB. Par exemple, utilisez np.max(spectrogram) pour définir la partie la plus forte à 0 dB. Doit être supérieur à zéro.
  • min_value (float, facultatif, par défaut 1e-10) — Le spectrogramme est rogné à cette valeur minimale avant conversion en décibels, afin d’éviter de calculer log(0). Pour un spectrogramme de puissance, la valeur par défaut de 1e-10 correspond à un minimum de -100 dB. Pour un spectrogramme d’amplitude, la valeur 1e-5 correspond à -100 dB. Doit être strictement supérieure à zéro.
  • db_range (float, facultatif) — Définit la plage dynamique maximale en décibels. Par exemple, si db_range = 80, la différence entre la valeur de crête et la valeur minimale ne dépassera jamais 80 dB. Doit être supérieure à zéro.
  • remove_dc_offset (bool, facultatif) — Soustrait la moyenne de la forme d’onde sur chaque trame, appliqué avant la pré-emphase. Cette valeur doit être définie sur true afin d’obtenir les mêmes résultats que torchaudio.compliance.kaldi.fbank lors du calcul des filtres mel.
  • dtype (np.dtype, facultatif, par défaut np.float32) — Type de données du tenseur de spectrogramme. Si power est None, cet argument est ignoré et le dtype sera np.complex64.

Calcule un spectrogramme sur une forme d’onde à l’aide de la transformée de Fourier à court terme.

Cette fonction peut créer les types de spectrogrammes suivants :

  • spectrogram d'amplitude (power = 1.0)
  • spectrogram de puissance (power = 2.0)
  • spectrogram à valeurs complexes (power = None)
  • spectrogramme logarithmique (utiliser l'argument log_mel)
  • spectrogram mel (fournir mel_filters)
  • spectrogram log-mel (fournir mel_filters et log_mel)

Comment cela fonctionne :

  1. Le signal d'entrée est découpé en trames de taille frame_length qui se chevauchent partiellement de `frame_length
    • échantillons de `hop_length`.
  2. Chaque trame est multipliée par la fenêtre et placée dans un tampon de taille fft_length.
  3. La DFT est calculée sur chaque fenêtre de trame.
  4. Les résultats sont empilés pour former un spectrogramme.

Nous faisons la distinction entre les « blocs » de données d'exemple suivants, chacun pouvant avoir une longueur différente :

  • Le cadre d'analyse. Il s'agit de la taille des tranches temporelles dans lesquelles le signal d'entrée est découpé.
  • La fenêtre. Chaque trame d'analyse est multipliée par la fenêtre afin d'éviter la fuite spectrale.
  • Le tampon d'entrée de la FFT. La longueur de ce dernier détermine le nombre de bandes de fréquences présentes dans le spectrogramme.

Dans cette implémentation, la fenêtre est supposée être complétée par des zéros pour avoir la même taille que le cadre d'analyse. Une fenêtre complétée peut être obtenue à partir de window_function(). Le tampon d'entrée de la FFT peut être plus grand que le cadre d'analyse, généralement la puissance de deux supérieure.

Note : Cette fonction n'est pas encore optimisée pour la vitesse. Elle devrait être principalement compatible avec librosa.stft et torchaudio.functional.transforms.Spectrogram, bien qu'elle soit plus flexible en raison des différentes façons de construire des spectrogrammes.

transformers.audio_utils.power_to_db

< >

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

Paramètres

  • spectrogram (np.ndarray) — Le spectrogramme de puissance (mel) d'entrée. Notez qu'un spectrogramme de puissance a les amplitudes au carré !
  • reference (float, facultatif, par défaut 1.0) — Définit la valeur du spectrogramme d'entrée correspondant à 0 dB. Par exemple, utilisez np.max(spectrogram) pour définir la partie la plus forte à 0 dB. Doit être supérieur à zéro.
  • min_value (float, facultatif, par défaut 1e-10) — Le spectrogramme est rogné à cette valeur minimale avant conversion en décibels, afin d'éviter de calculer log(0). La valeur par défaut de 1e-10 correspond à un minimum de -100 dB. Doit être strictement supérieur à zéro.
  • db_range (float, facultatif) — Définit la plage dynamique maximale en décibels. Par exemple, si db_range = 80, la différence entre la valeur de crête et la valeur minimale ne dépassera jamais 80 dB. Doit être supérieure à zéro.

Retourne

np.ndarray

le spectrogramme en décibels

Convertit un spectrogramme de puissance en échelle décibels. Cette opération calcule 10 * log10(spectrogram / reference), en utilisant les propriétés de base des logarithmes pour la stabilité numérique.

La motivation derrière l'application de la fonction logarithmique sur le spectrogramme (mel) est que les humains ne perçoivent pas l'intensité sonore sur une échelle linéaire. En général, pour doubler le volume perçu d'un son, il faut y injecter huit fois plus d'énergie. Cela signifie que de grandes variations d'énergie peuvent ne pas paraître très différentes si le son est déjà fort. Cette opération de compression permet aux caractéristiques du spectrogramme (mel) de correspondre plus étroitement à ce que les humains entendent réellement.

Basé sur l'implémentation 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

Paramètres

  • spectrogram (np.ndarray) — Le spectrogramme d'amplitude (mel) d'entrée.
  • reference (float, facultatif, par défaut 1.0) — Définit la valeur du spectrogramme d'entrée correspondant à 0 dB. Par exemple, utilisez np.max(spectrogram) pour définir la partie la plus forte à 0 dB. Doit être supérieur à zéro.
  • min_value (float, facultatif, par défaut 1e-5) — Le spectrogramme est rogné à cette valeur minimale avant conversion en décibels, afin d'éviter de calculer log(0). La valeur par défaut de 1e-5 correspond à un minimum de -100 dB. Doit être strictement supérieure à zéro.
  • db_range (float, facultatif) — Définit la plage dynamique maximale en décibels. Par exemple, si db_range = 80, la différence entre la valeur de crête et la valeur minimale ne dépassera jamais 80 dB. Doit être supérieure à zéro.

Retourne

np.ndarray

le spectrogramme en décibels

Convertit un spectrogramme d'amplitude en échelle décibels. Ce calcul effectue 20 * log10(spectrogram / reference), en utilisant les propriétés de base des logarithmes pour la stabilité numérique.

La motivation derrière l'application de la fonction logarithmique sur le spectrogramme (mel) est que les humains ne perçoivent pas l'intensité sonore sur une échelle linéaire. En général, pour doubler le volume perçu d'un son, il faut y injecter huit fois plus d'énergie. Cela signifie que de grandes variations d'énergie peuvent ne pas paraître très différentes si le son est déjà fort. Cette opération de compression permet aux caractéristiques du spectrogramme (mel) de correspondre plus étroitement à ce que les humains entendent réellement.

Update on GitHub