Hugging Face's logo

Transformers documentation

EnCodec

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo se publicó en HF papers el 24-10-2022 y se contribuyó a Hugging Face Transformers el 14-06-2023.

EnCodec

Resumen

El modelo de códec neuronal EnCodec fue propuesto en High Fidelity Neural Audio Compression por Alexandre Défossez, Jade Copet, Gabriel Synnaeve, Yossi Adi.

El resumen del artículo es el siguiente:

Presentamos un códec de audio en tiempo real y de alta fidelidad, de última generación, que aprovecha redes neuronales. Consiste en una arquitectura de codificador-decodificador en streaming con un espacio latente cuantizado, entrenada de extremo a extremo. Simplificamos y aceleramos el entrenamiento mediante el uso de un único adversario de espectrograma multiescala, que reduce de manera eficiente los artefactos y produce muestras de alta calidad. Introducimos un mecanismo novedoso de equilibrador de pérdidas para estabilizar el entrenamiento: el peso de una pérdida define ahora la fracción del gradiente total que debe representar, lo que desacopla la elección de este hiperparámetro de la escala típica de la pérdida. Finalmente, estudiamos cómo los modelos Transformer ligeros pueden utilizarse para comprimir aún más la representación obtenida hasta un 40%, manteniéndose más rápidos que el tiempo real. Proporcionamos una descripción detallada de las decisiones de diseño clave del modelo propuesto, que incluyen: el objetivo de entrenamiento, los cambios arquitectónicos y un estudio de diversas funciones de pérdida perceptual. Presentamos una evaluación subjetiva extensa (pruebas MUSHRA) junto con un estudio de ablatión para una serie de anchos de banda y dominios de audio, que incluyen voz, voz con ruido y reverberación, y música. Nuestro enfoque es superior a los métodos de referencia en todos los escenarios evaluados, considerando tanto audio monofónico a 24 kHz como audio estéreo a 48 kHz.

Este modelo fue aportado por Matthijs, Patrick Von Platen y Arthur Zucker. El código original se puede encontrar aquí.

Ejemplo de uso

Aquí hay un ejemplo rápido de cómo codificar y decodificar un audio con 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

clase 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, valor predeterminado [1.5, 3.0, 6.0, 12.0, 24.0]) — El rango de diferentes anchos de banda con los que el modelo puede codificar el audio.
  • sampling_rate (int, opcional, valor predeterminado 24000) — La tasa de muestreo a la que deben digitalizarse los archivos de audio, expresada en hercios (Hz).
  • audio_channels (int, opcional, valor predeterminado 1) — El número de canales de entrada.
  • normalize (bool, opcional, valor predeterminado False) — Si el audio debe normalizarse al pasarse.
  • chunk_length_s (float, opcional) — Si se define, el audio se preprocesa en fragmentos de longitud chunk_length_s y luego se codifica.
  • overlap (float, opcional) — Define la superposición entre cada fragmento. Se utiliza para calcular el chunk_stride mediante la siguiente fórmula: int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int, opcional, valor predeterminado 128) — Dimensión de las representaciones ocultas.
  • num_filters (int, opcional, valor predeterminado 32) — Número de núcleos de convolución de la primera capa de muestreo descendente EncodecConv1d.
  • num_residual_layers (int, opcional, valor predeterminado 1) — Número de capas residuales.
  • upsampling_ratios (Sequence[int] , opcional, valor predeterminado [8, 5, 4, 2]) — Proporciones de tamaño de kernel y stride. El codificador utiliza proporciones de muestreo descendente en lugar de proporciones de muestreo ascendente, por lo que utilizará las proporciones en el orden inverso al especificado aquí, que debe coincidir con el orden del decodificador.
  • norm_type (str, opcional, valor predeterminado "weight_norm") — Método de normalización. Debe estar en ["weight_norm", "time_group_norm"]
  • kernel_size (int, opcional, valor predeterminado 7) — Tamaño del kernel para la convolución inicial.
  • last_kernel_size (int, opcional, valor predeterminado 7) — Tamaño del kernel para la última capa de convolución.
  • residual_kernel_size (int, opcional, valor predeterminado 3) — Tamaño del kernel para las capas residuales.
  • dilation_growth_rate (int, opcional, valor predeterminado 2) — Cuánto aumentar la dilatación en cada capa.
  • use_causal_conv (bool, opcional, valor predeterminado True) — Si se debe usar una convolución completamente causal.
  • pad_mode (str, opcional, valor predeterminado "reflect") — Modo de relleno para las convoluciones.
  • compress (int, opcional, valor predeterminado 2) — Dimensionalidad reducida en las ramas residuales (de Demucs v3).
  • num_lstm_layers (int, opcional, valor predeterminado 2) — Número de capas LSTM al final del codificador.
  • trim_right_ratio (float, opcional, valor predeterminado 1.0) — Proporción para recortar en el lado derecho de la convolución transpuesta bajo la configuración use_causal_conv = True. Si es igual a 1.0, significa que todo el recorte se realiza en el lado derecho.
  • codebook_size (int, opcional, valor predeterminado 1024) — El número de libros de códigos paralelos utilizados por el modelo.
  • codebook_dim (int, opcional) — Dimensionalidad de cada vector de incrustación del libro de códigos.
  • use_conv_shortcut (bool, opcional, valor predeterminado True) — Si se debe usar una capa convolucional como conexión de ‘skip’ en el bloque EncodecResnetBlock. Si es False, se usará una función identidad, lo que da lugar a una conexión residual genérica.

Esta es la clase de configuración para almacenar la configuración de un EncodecModel. Se utiliza para instanciar un modelo Encodec según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de facebook/encodec_24khz

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

Ejemplo:

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

clase 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, valor predeterminado 1) — La dimensión de las características de las características extraídas. Use 1 para mono y 2 para estéreo.
  • sampling_rate (int, opcional, valor predeterminado 24000) — La tasa de muestreo a la que la forma de onda de audio debe digitalizarse, expresada en hercios (Hz).
  • padding_value (float, opcional, valor predeterminado 0.0) — El valor que se utiliza para rellenar los valores de relleno.
  • chunk_length_s (float, opcional) — Si se define, el audio se preprocesa en fragmentos de longitud chunk_length_s y luego se codifica.
  • overlap (float, opcional) — Define la superposición entre cada fragmento. Se utiliza para calcular el chunk_stride mediante la siguiente fórmula: int((1.0 - self.overlap) * self.chunk_length).

Construye un extractor de características de EnCodec.

Este extractor de características hereda de SequenceFeatureExtractor, que contiene la mayoría de los métodos principales. Los usuarios deben consultar esta superclase para obtener más información sobre dichos métodos.

Instanciar un extractor de características con los valores predeterminados producirá una configuración similar a la de la arquitectura 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]]) — La secuencia o lote de secuencias a procesar. Cada secuencia puede ser un array de numpy, una lista de valores float, una lista de arrays de numpy o una lista de listas de valores float. El array de numpy debe tener forma (num_samples,) para audio mono (feature_size = 1), o (2, num_samples) para audio estéreo (feature_size = 2).
  • padding (bool, str o PaddingStrategy, opcional, por defecto True) — Seleccione una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre:
    • True o 'longest': Rellena hasta la secuencia más larga del lote (o no aplica relleno si solo se proporciona una secuencia).
    • 'max_length': Rellena hasta una longitud máxima especificada con el argumento max_length o hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona dicho argumento.
    • False o 'do_not_pad' (predeterminado): Sin relleno (es decir, puede generar un lote con secuencias de diferentes longitudes).
  • truncation (bool, opcional, valor predeterminado False) — Activa la truncación para recortar las secuencias de entrada más largas que max_length a max_length.
  • max_length (int, opcional) — Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (véase arriba).
  • return_tensors (str o TensorType, opcional) — Si se establece, devolverá tensores en lugar de una lista de enteros de Python. Los valores aceptables son:
    • 'pt': Devuelve objetos torch.Tensor de PyTorch.
    • 'np': Devuelve objetos Numpy np.ndarray.
  • sampling_rate (int, opcional) — La tasa de muestreo a la que se muestreó la entrada de audio. Se recomienda encarecidamente pasar sampling_rate en la llamada de forward para evitar errores silenciosos.

Método principal para extraer características y preparar una o varias secuencias para el modelo.

EncodecModel

clase transformers.EncodecModel

< >

( config: EncodecConfig )

Parámetros

  • config (EncodecConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.

El modelo de códec de audio neuronal EnCodec.

Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

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) — Incrustaciones de códigos discretos calculadas usando model.encode.
  • audio_scales (lista de longitud nb_frames de torch.Tensor de forma (batch_size, 1), opcional) — Factor de escala para cada entrada de audio_codes.
  • padding_mask (torch.Tensor de forma (channels, sequence_length)) — Máscara de relleno utilizada para rellenar input_values.
  • return_dict (bool, opcional) — Indica si se debe devolver un ModelOutput en lugar de una tupla simple.
  • last_frame_pad_length (int, opcional) — Entero que representa la longitud del relleno en el último fotograma, que se elimina durante la decodificación.

Decodifica los fotogramas dados en una forma de onda de audio de salida.

Tenga en cuenta que la salida puede ser un poco más grande que la entrada. En ese caso, cualquier paso extra al final se puede recortar.

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 flotantes de la forma de onda de audio de entrada.
  • padding_mask (torch.Tensor de forma (batch_size, channels, sequence_length)) — Máscara de relleno utilizada para rellenar input_values.
  • bandwidth (float, opcional) — El ancho de banda objetivo. Debe ser uno de config.target_bandwidths. Si es None, se utiliza el ancho de banda más pequeño posible. bandwidth se representa como una milésima de su valor real, p. ej. un ancho de banda de 6kbps se representa como bandwidth == 6.0

Devuelve

EncodecEncoderOutput diccionario o una tupla que contiene

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

Codifica la forma de onda de audio de entrada en códigos discretos de forma (nb_frames, batch_size, nb_quantizers, frame_len).

  • nb_frames=1 si self.config.chunk_length=None (ya que el codificador se aplica al audio completo), que es el caso del modelo de 24 kHz. En caso contrario, nb_frames=ceil(input_length/self.config.chunk_stride), que es el caso del modelo de 48 kHz.
  • frame_len es la longitud de cada cuadro, que es igual a ceil(input_length/self.config.hop_length) si self.config.chunk_length=None (p. ej., para el modelo de 24 kHz). En caso contrario, si self.config.chunk_length está definido, frame_len=self.config.chunk_length/self.config.hop_length, por ejemplo, el caso del modelo de 48 kHz con 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 audio sin procesar convertida a Float y rellena hasta la longitud adecuada para ser codificada usando bloques de longitud self.chunk_length y un desplazamiento de config.chunk_stride.
  • padding_mask (torch.BoolTensor de forma (batch_size, channels, sequence_length), opcional) — Máscara para evitar el cálculo de factores de escalado en los índices de tokens de relleno (¿podemos evitar el cálculo de conv en estos+?). Valores de la máscara seleccionados en [0, 1]:
    • 1 para los tokens que no están enmascarados,
    • 0 para los tokens que están enmascarados.

    padding_mask siempre debe pasarse, a menos que la entrada se haya truncado o no esté rellena. Esto se debe a que, para procesar los tensores de manera efectiva, el audio de entrada debe rellenarse de modo que input_length % stride = step con step = chunk_length-stride. Esto garantiza que todos los fragmentos tengan la misma forma

  • bandwidth (float, opcional) — El ancho de banda objetivo. Debe ser uno de config.target_bandwidths. Si es None, se utiliza el ancho de banda más pequeño posible. bandwidth se representa como una milésima de su valor real, p. ej. un ancho de banda de 6kbps se representa como bandwidth == 6.0
  • audio_codes (torch.LongTensor de forma (nb_frames, batch_size, nb_quantizers, frame_len), opcional) — Incrustaciones de códigos discretos calculadas usando model.encode.
  • audio_scales (list de longitud nb_frames de torch.Tensor de forma (batch_size, 1), opcional) — Factor de escala para cada entrada de audio_codes.
  • return_dict (bool, opcional) — Si se deben devolver las salidas como un diccionario.
  • last_frame_pad_length (int, opcional) — La longitud del relleno en el último fotograma, si lo hay. Esto se utiliza para garantizar que los fotogramas codificados puedan emitirse como un tensor. Este valor debe pasarse durante la decodificación para asegurarse de que el relleno se elimine de los fotogramas codificados.

Devuelve

EncodecOutput o tuple(torch.Tensor)

Un EncodecOutput o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (EncodecConfig) y las entradas.

El método forward de EncodecModel reemplaza el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

  • audio_codes (torch.LongTensor de forma (nb_frames, batch_size, nb_quantizers, frame_len), opcional) — Incrustaciones de códigos discretos calculadas usando model.encode.
  • audio_values (torch.Tensor de forma (batch_size, segment_length), opcional) — Valores de audio decodificados, obtenidos mediante la parte decodificadora de Encodec.

Ejemplos:

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

←Día FastSpeech2Conformer→