Hugging Face's logo

Transformers documentation

EnCodec

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

and get access to the augmented documentation experience

to get started

Ce modèle a été publié dans HF papers le 2022-10-24 et ajouté à Hugging Face Transformers le 2023-06-14.

EnCodec

Aperçu

Le modèle de codec neuronal EnCodec a été proposé dans High Fidelity Neural Audio Compression par Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

L'abstract de l'article est le suivant :

Nous présentons un codec audio en temps réel, haute fidélité et de pointe, exploitant des réseaux de neurones. Il repose sur une architecture encodeur-décodeur en flux avec un espace latent quantifié, entraînée de manière bout en bout. Nous simplifions et accélérons l’entraînement en utilisant un seul adversaire multispectrogramme qui réduit efficacement les artefacts et produit des échantillons de haute qualité. Nous introduisons un mécanisme de rééquilibrage des pertes novateur pour stabiliser l’entraînement : le poids d’une perte définit désormais la fraction du gradient global qu’elle doit représenter, découplant ainsi le choix de ce hyperparamètre de l’échelle typique de la perte. Enfin, nous étudions comment des modèles Transformer légers peuvent être utilisés pour compresser davantage la représentation obtenue, jusqu’à 40 %, tout en restant plus rapide que le temps réel. Nous fournissons une description détaillée des choix de conception clés du modèle proposé, notamment : l’objectif d’entraînement, les modifications architecturales et une étude de diverses fonctions de perte perceptuelle. Nous présentons une évaluation subjective exhaustive (tests MUSHRA) ainsi qu’une étude d’ablation pour une gamme de bandes passantes et de domaines audio, incluant la parole, la parole bruyante et réverbérée, et la musique. Notre approche surpasse les méthodes de référence dans tous les paramètres évalués, en considérant à la fois l’audio monophonique à 24 kHz et l’audio stéréophonique à 48 kHz.

Ce modèle a été contribué par Matthijs, Patrick Von Platen et Arthur Zucker. Le code d'origine peut être trouvé ici.

Exemple d'utilisation

Voici un exemple rapide de l’encodage et du décodage d’un audio à l’aide de ce modèle :

from datasets import Audio, load_dataset

from transformers import AutoProcessor, EncodecModel


librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

model = EncodecModel.from_pretrained("facebook/encodec_24khz", device_map="auto")
processor = AutoProcessor.from_pretrained("facebook/encodec_24khz")
librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
audio_sample = librispeech_dummy[-1]["audio"]["array"]
inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt").to(model.device)

encoder_outputs = model.encode(inputs["input_values"], inputs["padding_mask"])
# `encoder_outputs.audio_codes` contains discrete codes
audio_values = model.decode(**encoder_outputs, padding_mask=inputs["padding_mask"])[0]
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"], inputs["padding_mask"]).audio_values

EncodecConfig

classe transformers.EncodecConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetarget_bandwidths: list[float] | tuple[float, ...] = (1.5, 3.0, 6.0, 12.0, 24.0)sampling_rate: int = 24000audio_channels: int = 1normalize: bool = Falsechunk_length_s: int | float | None = Noneoverlap: float | None = Nonehidden_size: int = 128num_filters: int = 32num_residual_layers: int = 1upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2)norm_type: str = 'weight_norm'kernel_size: int = 7last_kernel_size: int = 7residual_kernel_size: int = 3dilation_growth_rate: int = 2use_causal_conv: bool = Truepad_mode: str = 'reflect'compress: int = 2num_lstm_layers: int = 2trim_right_ratio: float = 1.0codebook_size: int = 1024codebook_dim: int | None = Noneuse_conv_shortcut: bool = True )

Paramètres

  • target_bandwidths (list[float], facultatif, par défaut [1.5, 3.0, 6.0, 12.0, 24.0]) — La plage de différentes largeurs de bande avec lesquelles le modèle peut encoder l'audio.
  • sampling_rate (int, facultatif, par défaut 24000) — Le taux d'échantillonnage auquel les fichiers audio doivent être numérisés, exprimé en hertz (Hz).
  • audio_channels (int, facultatif, par défaut 1) — Le nombre de canaux d'entrée.
  • normalize (bool, facultatif, par défaut False) — Indique si l'audio doit être normalisé lors de son passage.
  • chunk_length_s (float, facultatif) — Si défini, l’audio est pré-traité en segments de longueur chunk_length_s avant d’être encodé.
  • overlap (float, facultatif) — Définit le chevauchement entre chaque bloc. Il est utilisé pour calculer le chunk_stride à l'aide de la formule suivante : int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int, facultatif, par défaut 128) — Dimension des représentations cachées.
  • num_filters (int, facultatif, par défaut 32) — Nombre de noyaux de convolution de la première couche de sous-échantillonnage EncodecConv1d.
  • num_residual_layers (int, facultatif, par défaut 1) — Nombre de couches résiduelles.
  • upsampling_ratios (Sequence[int] , facultatif, par défaut [8, 5, 4, 2]) — Rapports de taille de noyau et de pas. L’encodeur utilise des rapports de rétrécissement au lieu de rapports d’agrandissement, il utilise donc les rapports dans l’ordre inverse de ceux spécifiés ici, qui doivent correspondre à l’ordre du décodeur.
  • norm_type (str, facultatif, par défaut "weight_norm") — Méthode de normalisation. Doit être dans ["weight_norm", "time_group_norm"]
  • kernel_size (int, facultatif, par défaut 7) — Taille du noyau pour la convolution initiale.
  • last_kernel_size (int, facultatif, valeur par défaut 7) — Taille du noyau pour la dernière couche de convolution.
  • residual_kernel_size (int, facultatif, valeur par défaut 3) — Taille du noyau pour les couches résiduelles.
  • dilation_growth_rate (int, facultatif, valeur par défaut 2) — Facteur d'augmentation de la dilatation à chaque couche.
  • use_causal_conv (bool, facultatif, par défaut True) — Indique s'il faut utiliser une convolution entièrement causale.
  • pad_mode (str, facultatif, par défaut "reflect") — Mode de bourrage pour les convolutions.
  • compress (int, facultatif, par défaut 2) — Dimension réduite dans les branches résiduelles (depuis Demucs v3).
  • num_lstm_layers (int, facultatif, valeur par défaut 2) — Nombre de couches LSTM à la fin de l'encodeur.
  • trim_right_ratio (float, facultatif, valeur par défaut 1.0) — Ratio de rognage à droite de la convolution transposée dans la configuration use_causal_conv = True. S'il est égal à 1.0, cela signifie que tout le rognage est effectué à droite.
  • codebook_size (int, facultatif, par défaut 1024) — Le nombre de codebooks parallèles utilisés par le modèle.
  • codebook_dim (int, facultatif) — Dimension de chaque vecteur d'embedding du codebook.
  • use_conv_shortcut (bool, facultatif, valeur par défaut True) — Indique s'il faut utiliser une couche de convolution comme connexion de « saut » dans le bloc EncodecResnetBlock. Si la valeur est False, une fonction identité est utilisée, ce qui donne une connexion résiduelle générique.

Ceci est la classe de configuration destinée à stocker la configuration d'un EncodecModel. Elle est utilisée pour instancier un modèle Encodec en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/encodec_24khz

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Exemple :

>>> from transformers import EncodecModel, EncodecConfig

>>> # Initializing a "facebook/encodec_24khz" style configuration
>>> configuration = EncodecConfig()

>>> # Initializing a model (with random weights) from the "facebook/encodec_24khz" style configuration
>>> model = EncodecModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

EncodecFeatureExtractor

classe transformers.EncodecFeatureExtractor

< >

( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0chunk_length_s: float | None = Noneoverlap: float | None = None**kwargs )

Paramètres

  • feature_size (int, facultatif, par défaut 1) — La dimension des caractéristiques des fonctionnalités extraites. Utilisez 1 pour le mono, 2 pour le stéréo.
  • sampling_rate (int, facultatif, valeur par défaut 24000) — La fréquence d'échantillonnage à laquelle la forme d'onde audio doit être numérisée, exprimée en hertz (Hz).
  • padding_value (float, facultatif, valeur par défaut 0.0) — La valeur utilisée pour remplir les valeurs de bourrage.
  • chunk_length_s (float, facultatif) — Si défini, l’audio est pré-traité en segments de longueur chunk_length_s avant d’être encodé.
  • overlap (float, facultatif) — Définit le chevauchement entre chaque bloc. Il est utilisé pour calculer le chunk_stride à l'aide de la formule suivante : int((1.0 - self.overlap) * self.chunk_length).

Construit un extracteur de fonctionnalités EnCodec.

Cet extracteur de fonctionnalités hérite de SequenceFeatureExtractor, qui contient la plupart des méthodes principales. Les utilisateurs doivent se référer à cette superclasse pour plus d'informations sur ces méthodes.

L'instantiation d'un extracteur de caractéristiques avec les valeurs par défaut produira une configuration similaire à celle de l'architecture facebook/encodec_24khz.

__call__

< >

( raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]padding: bool | str | transformers.utils.generic.PaddingStrategy | None = Nonetruncation: bool | None = Falsemax_length: int | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonesampling_rate: int | None = None )

Paramètres

  • raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — La séquence ou le lot de séquences à traiter. Chaque séquence peut être un tableau numpy, une liste de valeurs flottantes, une liste de tableaux numpy ou une liste de listes de valeurs flottantes. Le tableau numpy doit avoir la forme (num_samples,) pour un audio mono (feature_size = 1), ou (2, num_samples) pour un audio stéréo (feature_size = 2).
  • padding (bool, str ou PaddingStrategy, facultatif, défaut : True) — Sélectionne une stratégie pour mettre en place le padding des séquences renvoyées (selon le côté de padding et l'index de padding du modèle) parmi :
    • True ou 'longest' : Ajuster à la séquence la plus longue du lot (ou aucun ajustement si une seule séquence est fournie).
    • 'max_length' : Remplir jusqu'à une longueur maximale spécifiée par l'argument max_length ou jusqu'à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni.
    • False ou 'do_not_pad' (par défaut) : aucun padding (c’est-à-dire, peut produire un lot avec des séquences de longueurs différentes).
  • truncation (bool, facultatif, par défaut False) — Active la troncature pour couper les séquences d’entrée plus longues que max_length à max_length.
  • max_length (int, facultatif) — Longueur maximale de la liste renvoyée et, le cas échéant, longueur du bourrage (voir ci-dessus).
  • return_tensors (str ou TensorType, facultatif) — Si défini, renvoie des tenseurs au lieu d'une liste d'entiers Python. Les valeurs acceptées sont :
    • 'pt' : Renvoie des objets torch.Tensor de PyTorch.
    • 'np' : Renvoie des objets Numpy np.ndarray.
  • sampling_rate (int, facultatif) — La fréquence d’échantillonnage à laquelle l’entrée audio a été échantillonnée. Il est fortement recommandé de passer sampling_rate lors de l’appel forward afin d’éviter les erreurs silencieuses.

Méthode principale pour vectoriser et préparer une ou plusieurs séquences pour le modèle.

EncodecModel

classe transformers.EncodecModel

< >

( config: EncodecConfig )

Paramètres

  • config (EncodecConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.

Le modèle de codec audio neuronal EnCodec.

Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)

Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.

décoder

< >

( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )

Paramètres

  • audio_codes (torch.LongTensor de forme (nb_frames, batch_size, nb_quantizers, frame_len), facultatif) — Incrustations de codes discrets calculées à l'aide de model.encode.
  • audio_scales (liste de longueur nb_frames de torch.Tensor de forme (batch_size, 1), facultatif) — Facteur d'échelle pour chaque entrée audio_codes.
  • padding_mask (torch.Tensor de forme (channels, sequence_length)) — Masque de bourrage utilisé pour bourrer les input_values.
  • return_dict (bool, facultatif) — Indique s'il faut retourner un ModelOutput plutôt qu'un simple tuple.
  • last_frame_pad_length (int, facultatif) — Entier représentant la longueur du bourrage dans la dernière trame, qui est supprimé lors du décodage.

Décode les images données en une forme d'onde audio de sortie.

Notez que la sortie peut être légèrement plus grande que l'entrée. Dans ce cas, les étapes supplémentaires à la fin peuvent être supprimées.

encode

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing

Paramètres

  • input_values (torch.Tensor de forme (batch_size, channels, sequence_length)) — Valeurs flottantes de la forme d'onde audio d'entrée.
  • padding_mask (torch.Tensor de forme (batch_size, channels, sequence_length)) — Masque de bourrage utilisé pour bourrer les input_values.
  • bandwidth (float, facultatif) — La bande passante cible. Doit être l’une des valeurs de config.target_bandwidths. Si None, utilise la bande passante la plus petite possible. bandwidth est représenté en millièmes de sa valeur réelle, par exemple une bande passante de 6 kbps est représentée par bandwidth == 6.0

Retourne

EncodecEncoderOutput dict ou un tuple contenant

  • audio_codes (torch.LongTensor de forme (nb_frames, batch_size, nb_quantizers, frame_len), facultatif),
  • audio_scales (liste de longueur nb_frames de torch.Tensor de forme (batch_size, 1), facultatif),
  • last_frame_pad_length (int, facultatif).

Encode la forme d'onde audio d'entrée en codes discrets de forme (nb_frames, batch_size, nb_quantizers, frame_len).

  • nb_frames=1 si self.config.chunk_length=None (l’encodeur étant appliqué sur l’audio complet), ce qui est le cas pour le modèle 24 kHz. Sinon, nb_frames=ceil(input_length/self.config.chunk_stride), ce qui est le cas pour le modèle 48 kHz.
  • frame_len est la longueur de chaque trame, qui est égale à ceil(input_length/self.config.hop_length) si self.config.chunk_length=None (par exemple, pour le modèle 24 kHz). Sinon, si self.config.chunk_length est défini, frame_len=self.config.chunk_length/self.config.hop_length, par exemple le cas du modèle 48 kHz avec frame_len=150.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.BoolTensor] = Nonebandwidth: float | None = Noneaudio_codes: typing.Optional[torch.LongTensor] = Noneaudio_scales: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 ) → EncodecOutput or tuple(torch.Tensor)

Paramètres

  • input_values (torch.Tensor de forme (batch_size, channels, sequence_length), facultatif) — Entrée audio brute convertie en Float et complétée à la longueur appropriée afin d'être encodée à l'aide de blocs de longueur self.chunk_length et d'un pas de config.chunk_stride.
  • padding_mask (torch.BoolTensor de forme (batch_size, channels, sequence_length), facultatif) — Masque pour éviter de calculer les facteurs d'échelle sur les indices des jetons de bourrage (peut-on éviter de calculer la convolution sur ces jetons ?). Les valeurs du masque sont sélectionnées dans [0, 1] : 1 pour les jetons non masqués, 0 pour les jetons masqués. padding_mask doit toujours être transmis, sauf si l'entrée a été tronquée ou n'a pas été bourrée. En effet, pour traiter efficacement les tenseurs, l'audio d'entrée doit être bourré de manière à ce que input_length % stride = step, avec step = chunk_length-stride. Cela garantit que tous les segments ont la même forme [0, 1]:
    • 1 pour les jetons qui ne sont pas masqués,
    • 0 pour les jetons masqués.

    padding_mask doit toujours être transmis, sauf si l'entrée a été tronquée ou n'a pas été rembourrée. En effet, afin de traiter les tenseurs efficacement, l'audio d'entrée doit être rembourré de sorte que input_length % stride = step avec step = chunk_length-stride. Cela garantit que tous les segments ont la même forme

  • bandwidth (float, facultatif) — La bande passante cible. Doit être l’une des valeurs de config.target_bandwidths. Si None, utilise la bande passante la plus petite possible. bandwidth est représentée en millièmes de sa valeur réelle, par exemple une bande passante de 6 kbps est représentée par bandwidth == 6.0
  • audio_codes (torch.LongTensor de forme (nb_frames, batch_size, nb_quantizers, frame_len), facultatif) — Incrustations de codes discrets calculées à l'aide de model.encode.
  • audio_scales (list de longueur nb_frames de torch.Tensor de forme (batch_size, 1), facultatif) — Facteur d'échelle pour chaque entrée audio_codes.
  • return_dict (bool, facultatif) — Indique s'il faut retourner les sorties sous forme de dictionnaire.
  • last_frame_pad_length (int, facultatif) — La longueur du bourrage dans la dernière image, le cas échéant. Cette valeur est utilisée pour garantir que les images encodées peuvent être sorties sous forme de tenseur. Cette valeur doit être transmise lors du décodage pour s’assurer que le bourrage est retiré des images encodées.

Retourne

EncodecOutput ou tuple(torch.Tensor)

Un EncodecOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (EncodecConfig) et des entrées.

La méthode forward du modèle EncodecModel redéfinit la méthode spéciale __call__.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance Module plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

  • audio_codes (torch.LongTensor de forme (nb_frames, batch_size, nb_quantizers, frame_len), facultatif) — Incrustations de codes discrets calculées à l'aide de model.encode.
  • audio_values (torch.Tensor de forme (batch_size, segment_length), facultatif) — Valeurs audio décodées, obtenues à l’aide de la partie décodeur d’Encodec.

Exemples :

>>> from datasets import load_dataset
>>> from transformers import AutoProcessor, EncodecModel

>>> dataset = load_dataset("hf-internal-testing/ashraq-esc50-1-dog-example")
>>> audio_sample = dataset["train"]["audio"][0]["array"]

>>> model_id = "facebook/encodec_24khz"
>>> model = EncodecModel.from_pretrained(model_id)
>>> processor = AutoProcessor.from_pretrained(model_id)

>>> inputs = processor(raw_audio=audio_sample, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values
Update on GitHub

←Dia FastSpeech2Conformer→