# 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]] #### 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') ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L556) **Paramètres :** freq (`float` ou `np.ndarray`) : La fréquence, ou plusieurs fréquences, 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[[transformers.audio_utils.mel_to_hertz]] ```python transformers.audio_utils.mel_to_hertz(mels: float | numpy.ndarray, mel_scale: str = 'htk') ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L592) **Paramètres :** mels (`float` ou `np.ndarray`) : La fréquence, ou plusieurs fréquences, 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[[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) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L746) **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. Cette valeur ne doit pas dépasser `sampling_rate / 2`. sampling_rate (`int`) : Fréquence 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*, valeur par défaut `False`) : Si cette option est activée, le filtre triangulaire est appliqué dans l'espace mélo plutôt que dans l'espace de fréquence. Cette valeur doit être définie sur `true` afin d'obtenir les mêmes résultats que `torchaudio` lors du calcul des filtres mélo. **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 permettant de passer d'un spectrogramme à un spectrogramme en échelle de mel. Crée une matrice de conversion de bandes de fréquences utilisée pour obtenir un spectrogramme mel. On l’appelle *banque de filtres mel*, et diverses implémentations existent, qui diffèrent par le nombre de filtres, la forme des filtres, l’espacement des filtres, la bande passante des filtres et la manière 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 hauteur 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 du 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 de *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[[transformers.audio_utils.optimal_fft_length]] ```python transformers.audio_utils.optimal_fft_length(window_length: int) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L840) Trouve la taille d'entrée FFT optimale 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[[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) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L853) **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*, valeur 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*, valeur 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 :** `np.ndarray` de forme `(window_length,)` ou `(frame_length,)` contenant la fenêtre. 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[[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 = ) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L917) **Paramètres :** waveform (`np.ndarray` de forme `(length,)`) : La forme d'onde d'entrée. Elle doit être une forme d'onde mono à valeurs réelles. window (`np.ndarray` de forme `(frame_length,)`) : Fonction de fenêtrage à appliquer, y compris le bourrage de zéros le cas échéant. 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, cette valeur est toujours égale à `fft_length`, mais nous autorisons également des tailles plus petites. hop_length (`int`) : Le pas 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 la valeur est 1.0, renvoie le spectrogramme d'amplitude. Si la valeur est 2.0, renvoie le spectrogramme de puissance. Si la valeur est `None`, renvoie des nombres complexes. center (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut ajouter des zéros (padding) à la forme d'onde 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*, valeur 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*, valeur par défaut `True`) : Si True, seules les fréquences positives sont calculées et un spectrogramme contenant `fft_length // 2 + 1` bandes de fréquences est renvoyé. Si False, les fréquences négatives sont également calculées et `fft_length` bandes de fréquences sont renvoyées. dither (`float`, *facultatif*, valeur par défaut 0.0) : Ajoute un dithering. Autrement dit, ajoute un petit bruit gaussien à chaque image. Par exemple, utilisez 4.0 pour ajouter un dithering avec une distribution normale centrée sur 0.0 et un écart-type de 4.0 ; 0.0 signifie qu'aucun dithering n'est appliqué. Le dithering a un effet similaire à celui de `mel_floor`. Il réduit les valeurs élevées de log_mel_fbank pour les signaux comportant des sections à zéro dur, lorsque la coupure VAD est présente dans le 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*, valeur 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*, valeur 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 strictement supérieur à zéro. min_value (`float`, *facultatif*, valeur par défaut `1e-10`) : Le spectrogramme est tronqué à cette valeur minimale avant la conversion en décibels, afin d'éviter de calculer `log(0)`. Pour un spectrogramme de puissance, la valeur par défaut `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 plus petite valeur ne dépassera jamais 80 dB. Doit être strictement supérieur à 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`. **Retourne :** `nd.array` contenant un spectrogramme de forme `(num_frequency_bins, length)` pour un spectrogramme standard ou de forme `(num_mel_filters, length)` pour un spectrogramme mel. 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. La forme d'onde d'entrée est découpée en trames de taille `frame_length` qui se chevauchent partiellement par `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 afin d’avoir la même taille que la trame 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 la trame 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[[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) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1339) **Paramètres :** spectrogram (`np.ndarray`) : Spectrogram d'énergie (mel) d'entrée. Notez qu'un spectrogramme d'énergie contient les amplitudes au carré ! reference (`float`, *facultatif*, valeur 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 strictement supérieur à zéro. min_value (`float`, *facultatif*, valeur par défaut `1e-10`) : Le spectrogramme est tronqué à cette valeur minimale avant la 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 plus petite valeur ne dépassera jamais 80 dB. Doit être strictement supérieur à 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 8 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[[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) ``` [Source](https://github.com/huggingface/transformers/blob/main/src/transformers/audio_utils.py#L1439) **Paramètres :** spectrogram (`np.ndarray`) : Spectrogram d'amplitude (mel) en entrée. reference (`float`, *facultatif*, valeur 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 strictement supérieur à zéro. min_value (`float`, *facultatif*, valeur par défaut `1e-5`) : Le spectrogramme est tronqué à cette valeur minimale avant la 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é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 plus petite valeur ne dépassera jamais 80 dB. Doit être strictement supérieur à zéro. **Retourne :** `np.ndarray` le spectrogramme en décibels Convertit un spectrogramme d'amplitude en échelle décibels. Cette opération calcule `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 8 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.