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.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi publicado nos HF papers em 2022-10-24 e contribuído para o Hugging Face Transformers em 2023-06-14.

EnCodec

Visão geral

O modelo de codec neural EnCodec foi proposto em High Fidelity Neural Audio Compression por Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

O resumo do artigo é o seguinte:

Apresentamos um codec de áudio em tempo real, de alta fidelidade e estado da arte, que utiliza redes neurais. Ele consiste em uma arquitetura de codificador-decodificador em streaming com espaço latente quantizado, treinada de forma ponta a ponta. Simplificamos e aceleramos o treinamento ao usar um único adversário de espectrograma multiescala, que reduz eficientemente artefatos e produz amostras de alta qualidade. Introduzimos um mecanismo inovador de balanceamento de perdas para estabilizar o treinamento: o peso de uma perda agora define a fração do gradiente total que ela deve representar, desacoplando assim a escolha desse hiperparâmetro da escala típica da perda. Por fim, estudamos como modelos Transformer leves podem ser usados para comprimir ainda mais a representação obtida em até 40%, mantendo-se mais rápido que o tempo real. Fornecemos uma descrição detalhada das principais escolhas de design do modelo proposto, incluindo: objetivo de treinamento, alterações arquitetônicas e um estudo de diversas funções de perda perceptual. Apresentamos uma avaliação subjetiva extensa (testes MUSHRA) juntamente com um estudo de ablação para uma faixa de larguras de banda e domínios de áudio, incluindo fala, fala com ruído e reverberação, e música. Nossa abordagem é superior aos métodos de referência em todos os cenários avaliados, considerando tanto áudio monofônico de 24 kHz quanto estéreo de 48 kHz.

Este modelo foi contribuído por Matthijs, Patrick Von Platen e Arthur Zucker. O código original pode ser encontrado aqui.

Exemplo de uso

Aqui está um exemplo rápido de como codificar e decodificar um áudio usando este modelo:

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 )

Parâmetros

  • target_bandwidths (list[float], opcional, padrão [1.5, 3.0, 6.0, 12.0, 24.0]) — A faixa de diferentes larguras de banda com as quais o modelo pode codificar áudio.
  • sampling_rate (int, opcional, padrão 24000) — A taxa de amostragem na qual os arquivos de áudio devem ser digitalizados, expressa em hertz (Hz).
  • audio_channels (int, opcional, padrão 1) — O número de canais de entrada.
  • normalize (bool, opcional, padrão False) — Se o áudio deve ser normalizado ao ser passado.
  • chunk_length_s (float, opcional) — Se definido, o áudio é pré-processado em blocos de tamanho chunk_length_s e, em seguida, codificado.
  • overlap (float, opcional) — Define a sobreposição entre cada bloco. É usado para calcular o chunk_stride usando a seguinte fórmula: int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int, opcional, padrão 128) — Dimensão das representações ocultas.
  • num_filters (int, opcional, padrão 32) — Número de núcleos de convolução da primeira camada de downsampling EncodecConv1d.
  • num_residual_layers (int, opcional, padrão 1) — Número de camadas residuais.
  • upsampling_ratios (Sequence[int] , opcional, padrão [8, 5, 4, 2]) — Proporções de tamanho do kernel e de stride. O codificador usa proporções de downsampling em vez de proporções de upsampling, portanto, ele usará as proporções na ordem inversa àquelas especificadas aqui, que devem corresponder à ordem do decodificador.
  • norm_type (str, opcional, padrão "weight_norm") — Método de normalização. Deve estar em ["weight_norm", "time_group_norm"]
  • kernel_size (int, opcional, padrão 7) — Tamanho do kernel para a convolução inicial.
  • last_kernel_size (int, opcional, padrão 7) — Tamanho do kernel para a última camada de convolução.
  • residual_kernel_size (int, opcional, padrão 3) — Tamanho do kernel para as camadas residuais.
  • dilation_growth_rate (int, opcional, padrão 2) — Quanto aumentar a dilatação em cada camada.
  • use_causal_conv (bool, opcional, padrão True) — Se deve usar convolução totalmente causal.
  • pad_mode (str, opcional, padrão "reflect") — Modo de preenchimento para as convoluções.
  • compress (int, opcional, padrão 2) — Dimensão reduzida nos ramos residuais (do Demucs v3).
  • num_lstm_layers (int, opcional, padrão 2) — Número de camadas LSTM no final do codificador.
  • trim_right_ratio (float, opcional, padrão 1.0) — Proporção para o recorte na parte direita da convolução transposta sob a configuração use_causal_conv = True. Se for igual a 1.0, significa que todo o recorte é feito na parte direita.
  • codebook_size (int, opcional, padrão 1024) — O número de codebooks paralelos usados pelo modelo.
  • codebook_dim (int, opcional) — Dimensão de cada vetor de incorporação do codebook.
  • use_conv_shortcut (bool, opcional, padrão True) — Indica se uma camada de convolução deve ser usada como conexão de ‘skip’ no bloco EncodecResnetBlock. Se for False, uma função identidade será utilizada, resultando em uma conexão residual genérica.

Esta é a classe de configuração para armazenar a configuração de um EncodecModel. Ela é usada para instanciar um modelo Encodec de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do facebook/encodec_24khz

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> 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 )

Parâmetros

  • feature_size (int, opcional, padrão 1) — A dimensão dos recursos dos recursos extraídos. Use 1 para mono e 2 para estéreo.
  • sampling_rate (int, opcional, padrão 24000) — A taxa de amostragem na qual a forma de onda de áudio deve ser digitalizada, expressa em hertz (Hz).
  • padding_value (float, opcional, padrão 0.0) — O valor usado para preencher os valores de padding.
  • chunk_length_s (float, opcional) — Se definido, o áudio é pré-processado em blocos de tamanho chunk_length_s e, em seguida, codificado.
  • overlap (float, opcional) — Define a sobreposição entre cada bloco. É usado para calcular o chunk_stride usando a seguinte fórmula: int((1.0 - self.overlap) * self.chunk_length).

Constrói um extrator de recursos EnCodec.

Este extrator de características herda de SequenceFeatureExtractor, que contém a maioria dos métodos principais. Os usuários devem consultar essa superclasse para obter mais informações sobre esses métodos.

A instanciação de um extrator de recursos com os padrões resultará em uma configuração semelhante à da arquitetura 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 )

Parâmetros

  • raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — A sequência ou lote de sequências a serem processadas. Cada sequência pode ser um array numpy, uma lista de valores float, uma lista de arrays numpy ou uma lista de listas de valores float. O array numpy deve ter a forma (num_samples,) para áudio mono (feature_size = 1), ou (2, num_samples) para áudio estéreo (feature_size = 2).
  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:
    • True ou 'longest': Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad' (padrão): Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • truncation (bool, opcional, padrão False) — Ativa a truncagem para cortar sequências de entrada com comprimento maior que max_length para max_length.
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors em vez de uma lista de inteiros do Python. Os valores aceitos são:
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do Numpy.
  • sampling_rate (int, opcional) — A taxa de amostragem na qual a entrada de audio foi amostrada. É fortemente recomendável passar sampling_rate na chamada de forward para evitar erros silenciosos.

Método principal para criar recursos e preparar uma ou várias sequências para o modelo.

EncodecModel

classe transformers.EncodecModel

< >

( config: EncodecConfig )

Parâmetros

  • config (EncodecConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

O modelo de codec neural de áudio EnCodec.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

decode

< >

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

Parâmetros

  • audio_codes (torch.LongTensor de forma (nb_frames, batch_size, nb_quantizers, frame_len), opcional) — Incorporações de códigos discretas calculadas usando model.encode.
  • audio_scales (lista de comprimento nb_frames de torch.Tensor com forma (batch_size, 1), opcional) — Fator de escala para cada entrada de audio_codes.
  • padding_mask (torch.Tensor de forma (channels, sequence_length)) — Máscara de preenchimento usada para preencher o input_values.
  • return_dict (bool, opcional) — Indica se deve retornar um ModelOutput em vez de uma tupla simples.
  • last_frame_pad_length (int, opcional) — Inteiro que representa o comprimento do preenchimento no último quadro, que é removido durante a decodificação.

Decodifica os quadros fornecidos em uma forma de onda de áudio de saída.

Observe que a saída pode ser um pouco maior que a entrada. Nesse caso, quaisquer etapas extras no final podem ser removidas.

encode

< >

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

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, channels, sequence_length)) — Valores em ponto flutuante da forma de onda de áudio de entrada.
  • padding_mask (torch.Tensor de forma (batch_size, channels, sequence_length)) — Máscara de preenchimento usada para preencher o input_values.
  • bandwidth (float, opcional) — A largura de banda alvo. Deve ser um dos valores de config.target_bandwidths. Se for None, usa a menor largura de banda possível. A largura de banda é representada como um milésimo do seu valor real, por exemplo, uma largura de banda de 6kbps é representada como bandwidth == 6.0

Retorna

EncodecEncoderOutput dict ou uma tupla contendo

  • audio_codes (torch.LongTensor de forma (nb_frames, batch_size, nb_quantizers, frame_len), opcional),
  • audio_scales (lista de comprimento nb_frames de torch.Tensor de forma (batch_size, 1), opcional),
  • last_frame_pad_length (int, opcional).

Codifica a forma de onda de áudio de entrada em códigos discretos de forma (nb_frames, batch_size, nb_quantizers, frame_len).

  • nb_frames=1 se self.config.chunk_length=None (uma vez que o codificador é aplicado ao áudio completo), o que é o caso do modelo de 24 kHz. Caso contrário, nb_frames=ceil(input_length/self.config.chunk_stride), o que é o caso do modelo de 48 kHz.
  • frame_len é o comprimento de cada quadro, que é igual a ceil(input_length/self.config.hop_length) se self.config.chunk_length=None (por exemplo, para o modelo de 24 kHz). Caso contrário, se self.config.chunk_length estiver definido, frame_len=self.config.chunk_length/self.config.hop_length, por exemplo, o caso do modelo de 48 kHz com 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)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, channels, sequence_length), opcional) — Entrada de áudio bruta convertida para Float e preenchida até o comprimento adequado para ser codificada usando blocos de comprimento self.chunk_length e um passo de config.chunk_stride.
  • padding_mask (torch.BoolTensor de forma (batch_size, channels, sequence_length), opcional) — Máscara para evitar o cálculo dos fatores de escala nos índices de tokens de padding (podemos evitar o cálculo de conv nesses+). Valores da máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    padding_mask deve ser sempre passado, a menos que a entrada tenha sido truncada ou não tenha sido preenchida. Isso ocorre porque, para processar os tensores de forma eficaz, o áudio de entrada deve ser preenchido de modo que input_length % stride = step, com step = chunk_length-stride. Isso garante que todos os blocos tenham a mesma forma

  • bandwidth (float, opcional) — A largura de banda alvo. Deve ser um dos valores de config.target_bandwidths. Se for None, usa a menor largura de banda possível. A largura de banda é representada como um milésimo do seu valor, por exemplo, uma largura de banda de 6kbps é representada como bandwidth == 6.0
  • audio_codes (torch.LongTensor de forma (nb_frames, batch_size, nb_quantizers, frame_len), opcional) — Incorporações de códigos discretas calculadas usando model.encode.
  • audio_scales (list de comprimento nb_frames de torch.Tensor de forma (batch_size, 1), opcional) — Fator de escala para cada entrada de audio_codes.
  • return_dict (bool, opcional) — Se deve retornar as saídas como um dicionário.
  • last_frame_pad_length (int, opcional) — O comprimento do preenchimento no último frame, se houver. Isso é usado para garantir que os frames codificados possam ser saídos como um tensor. Esse valor deve ser passado durante a decodificação para garantir que o preenchimento seja removido dos frames codificados.

Retorna

EncodecOutput ou tuple(torch.Tensor)

Um EncodecOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos dependendo da configuração (EncodecConfig) e das entradas.

O método forward do EncodecModel substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • audio_codes (torch.LongTensor de forma (nb_frames, batch_size, nb_quantizers, frame_len), opcional) — Embutimentos de códigos discretos calculados usando model.encode.
  • audio_values (torch.Tensor de forma (batch_size, segment_length), opcional) — Valores de áudio decodificados, obtidos usando a parte decodificadora do Encodec.

Exemplos:

>>> 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→