Transformers 文档

EnCodec

Hugging Face's logo
加入 Hugging Face 社区

并访问增强型文档体验

开始使用

EnCodec

概述

EnCodec 神经编解码模型由 Alexandre Défossez、Jade Copet、Gabriel Synnaeve 和 Yossi Adi 在 高保真神经音频压缩 中提出。

论文的摘要如下

我们介绍了一种利用神经网络的实时、高保真音频编解码器,它处于最先进水平。它由一个端到端训练的、带有量化潜空间的流式编码器-解码器架构组成。我们通过使用单一的多尺度频谱图对抗器简化并加速了训练,该对抗器有效地减少了伪影并生成了高质量样本。我们引入了新的损失平衡器机制来稳定训练:损失的权重现在定义了它应该代表的总梯度的比例,从而将此超参数的选择从典型损失规模中分离出来。最后,我们研究了轻量级 Transformer 模型如何被用于进一步压缩获得的表示,压缩率高达 40%,同时保持比实时速度更快。我们详细描述了所提出模型的关键设计选择,包括:训练目标、架构变化以及对各种感知损失函数的研究。我们针对一系列带宽和音频域(包括语音、噪声混响语音和音乐)进行了广泛的主观评估(MUSHRA 测试)以及消融研究。在所有评估设置中,我们的方法都优于基线方法,包括 24 kHz 单声道和 48 kHz 立体声音频。

该模型由 MatthijsPatrick Von PlatenArthur Zucker 贡献。原始代码可以在这里找到 here.

使用示例

以下是如何使用此模型编码和解码音频的快速示例

>>> from datasets import load_dataset, Audio
>>> from transformers import EncodecModel, AutoProcessor
>>> librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

>>> model = EncodecModel.from_pretrained("facebook/encodec_24khz")
>>> 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")

>>> encoder_outputs = model.encode(inputs["input_values"], inputs["padding_mask"])
>>> audio_values = model.decode(encoder_outputs.audio_codes, encoder_outputs.audio_scales, inputs["padding_mask"])[0]
>>> # or the equivalent with a forward pass
>>> audio_values = model(inputs["input_values"], inputs["padding_mask"]).audio_values

EncodecConfig

class transformers.EncodecConfig

< >

( target_bandwidths = [1.5, 3.0, 6.0, 12.0, 24.0] sampling_rate = 24000 audio_channels = 1 normalize = False chunk_length_s = None overlap = None hidden_size = 128 num_filters = 32 num_residual_layers = 1 upsampling_ratios = [8, 5, 4, 2] norm_type = 'weight_norm' kernel_size = 7 last_kernel_size = 7 residual_kernel_size = 3 dilation_growth_rate = 2 use_causal_conv = True pad_mode = 'reflect' compress = 2 num_lstm_layers = 2 trim_right_ratio = 1.0 codebook_size = 1024 codebook_dim = None use_conv_shortcut = True **kwargs )

参数

  • target_bandwidths (List[float], 可选, 默认为 [1.5, 3.0, 6.0, 12.0, 24.0]) — 模型可以用于对音频进行编码的不同带宽范围。
  • sampling_rate (int, 可选, 默认为 24000) — 音频波形数字化时的采样率,以赫兹 (Hz) 为单位。
  • audio_channels (int, 可选, 默认为 1) — 音频数据中的声道数。1 表示单声道,2 表示立体声。
  • normalize (bool, 可选, 默认为 False) — 是否在传递音频时进行归一化。
  • chunk_length_s (float, 可选) — 如果定义了,则音频将预处理成 chunk_length_s 长度的块,然后进行编码。
  • overlap (float, 可选) — 定义每个块之间的重叠。它用于使用以下公式计算 chunk_strideint((1.0 - self.overlap) * self.chunk_length)
  • num_filters (int, 可选, 默认为 32) — 第一个 EncodecConv1d 降采样层的卷积核数量。
  • num_residual_layers (int, 可选, 默认为 1) — 残差层的数量。
  • upsampling_ratios (Sequence[int] , 可选, 默认为 [8, 5, 4, 2]) — 卷积核大小和步幅比率。编码器使用降采样比率而不是上采样比率,因此它将使用与这里指定的比率相反的顺序,并且必须与解码器顺序匹配。
  • norm_type (str, 可选, 默认为 "weight_norm") — 归一化方法。应在 ["weight_norm", "time_group_norm"] 中。
  • kernel_size (int, 可选, 默认为 7) — 初始卷积的卷积核大小。
  • last_kernel_size (int, 可选, 默认为 7) — 最后一个卷积层的卷积核大小。
  • residual_kernel_size (int, 可选, 默认为 3) — 残差层的卷积核大小。
  • dilation_growth_rate (int, 可选, 默认为 2) — 每层增加多少膨胀。
  • use_causal_conv (bool, 可选, 默认为 True) — 是否使用完全因果卷积。
  • pad_mode (str, 可选, 默认为 "reflect") — 卷积的填充模式。
  • num_lstm_layers (int, optional, defaults to 2) — 编码器末端的 LSTM 层数。
  • trim_right_ratio (float, optional, defaults to 1.0) — 在 use_causal_conv = True 设置下,对转置卷积右侧进行裁剪的比例。如果等于 1.0,则意味着所有裁剪都在右侧完成。
  • codebook_size (int, optional, defaults to 1024) — 构成 VQVAE 的离散代码数量。
  • codebook_dim (int, optional) — 代码本向量的维度。如果未定义,则使用 hidden_size
  • use_conv_shortcut (bool, optional, defaults to True) — 是否在 EncodecResnetBlock 块中使用卷积层作为“跳跃”连接。如果为 False,则将使用恒等函数,从而提供一个通用的残差连接。

这是用于存储 EncodecModel 配置的配置类。它用于根据指定参数实例化 Encodec 模型,定义模型架构。使用默认值实例化配置将生成与 facebook/encodec_24khz 架构类似的配置。

配置对象继承自 PretrainedConfig,可用于控制模型输出。阅读 PretrainedConfig 的文档以获取更多信息。

示例

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

class transformers.EncodecFeatureExtractor

< >

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

参数

  • feature_size (int, optional, defaults to 1) — 提取特征的特征维度。对于单声道使用 1,对于立体声使用 2。
  • sampling_rate (int, optional, defaults to 24000) — 音频波形应以赫兹 (Hz) 表示的数字化的采样率。
  • chunk_length_s (float, optional) — 如果定义,音频将被预处理成长度为 chunk_length_s 的块,然后进行编码。
  • overlap (float, optional) — 定义每个块之间的重叠。它用于使用以下公式计算 chunk_strideint((1.0 - self.overlap) * self.chunk_length)

构建 EnCodec 特征提取器。

此特征提取器继承自 SequenceFeatureExtractor,其中包含大多数主要方法。用户应参考此超类以获取有关这些方法的更多信息。

使用默认值实例化特征提取器将产生与 facebook/encodec_24khz 架构类似的配置。

__call__

< >

( raw_audio: Union padding: Union = None truncation: Optional = False max_length: Optional = None return_tensors: Union = None sampling_rate: Optional = None )

参数

  • raw_audio (np.ndarray, List[float], List[np.ndarray], List[List[float]]) — 要处理的序列或序列批次。每个序列可以是 numpy 数组、浮点值列表、numpy 数组列表或浮点值列表列表。numpy 数组必须对于单声道音频(feature_size = 1)的形状为 (num_samples,),或者对于立体声音频(feature_size = 2)的形状为 (2, num_samples)
  • padding (bool, str or PaddingStrategy, optional, defaults to True) — 选择一个策略来填充返回的序列(根据模型的填充侧和填充索引),方法如下:

    • True'longest':填充到批次中最长的序列(如果只提供单个序列,则不填充)。
    • 'max_length':填充到使用参数 max_length 指定的最大长度,或者如果未提供该参数,则填充到模型可接受的最大输入长度。
    • False'do_not_pad'(默认):不填充(即,可以输出具有不同长度序列的批次)。
  • truncation (bool, optional, defaults to False) — 激活截断,将长度超过 max_length 的输入序列截断到 max_length
  • max_length (int, optional) — 返回列表的最大长度,以及可选的填充长度(见上文)。
  • return_tensors (str or TensorType, optional) — 如果设置,将返回张量而不是 Python 整数列表。可接受的值为:

    • 'tf':返回 TensorFlow tf.constant 对象。
    • 'pt':返回 PyTorch torch.Tensor 对象。
    • 'np':返回 NumPy np.ndarray 对象。
  • sampling_rate (int, optional) — audio 输入采样的采样率。强烈建议在正向调用中传递 sampling_rate,以防止出现静默错误。

将一个或多个序列特征化并为模型准备的主要方法。

EncodecModel

class transformers.EncodecModel

< >

( config: EncodecConfig )

参数

  • config (EncodecConfig) — 模型配置类,包含模型的所有参数。 使用配置文件初始化不会加载与模型关联的权重,只会加载配置。 请查看from_pretrained() 方法加载模型权重。

EnCodec 神经音频编解码器模型。 此模型继承自PreTrainedModel。 请查看超类文档以了解库为所有模型实现的通用方法(例如下载或保存、调整输入嵌入的大小、修剪注意力头等)。

此模型也是 PyTorch torch.nn.Module 子类。 将其用作常规 PyTorch 模块,并参考 PyTorch 文档以了解有关一般用法和行为的所有事项。

解码

< >

( audio_codes: Tensor audio_scales: Tensor padding_mask: Optional = None return_dict: Optional = None )

参数

  • audio_codes (torch.LongTensor 形状为 (batch_size, nb_chunks, chunk_length)可选) — 使用 model.encode 计算的离散代码嵌入。
  • audio_scales (torch.Tensor 形状为 (batch_size, nb_chunks)可选) — 每个 audio_codes 输入的缩放因子。
  • padding_mask (torch.Tensor 形状为 (batch_size, channels, sequence_length)) — 用于填充 input_values 的填充掩码。
  • return_dict (bool可选) — 是否返回 ModelOutput 而不是普通元组。

将给定的帧解码为输出音频波形。

注意,输出可能比输入大一点。 在这种情况下,可以剪掉最后的任何额外步骤。

编码

< >

( input_values: Tensor padding_mask: Tensor = None bandwidth: Optional = None return_dict: Optional = None )

参数

  • input_values (torch.Tensor 形状为 (batch_size, channels, sequence_length)) — 输入音频波形的浮点值。
  • padding_mask (torch.Tensor 形状为 (batch_size, channels, sequence_length)) — 用于填充 input_values 的填充掩码。
  • bandwidth (float, *可选*) — 目标带宽。必须是 config.target_bandwidths 中的之一。如果为 None,则使用可能的最小带宽。带宽表示为千分之一,例如 6kbps 带宽表示为 bandwidth == 6.0

将输入音频波形编码为离散代码。

forward

< >

( input_values: Tensor padding_mask: Optional = None bandwidth: Optional = None audio_codes: Optional = None audio_scales: Optional = None return_dict: Optional = None ) transformers.models.encodec.modeling_encodec.EncodecOutputtuple(torch.FloatTensor)

参数

  • input_values (torch.FloatTensor 形状为 (batch_size, channels, sequence_length), *可选*) — 原始音频输入转换为浮点数,并填充到适当的长度,以便使用长度为 self.chunk_length 的块和 config.chunk_stride 的步长进行编码。
  • padding_mask (torch.BoolTensor 形状为 (batch_size, channels, sequence_length), *可选*) — 掩码,用于避免在填充令牌索引上计算缩放因子(我们可以避免在这些索引上计算卷积)。掩码值选择在 [0, 1] 中:

    • 1 表示未屏蔽的令牌。
    • 0 表示屏蔽的令牌。

    padding_mask 应始终传递,除非输入被截断或未填充。这是因为为了有效地处理张量,输入音频应进行填充,以便 input_length % stride = step,其中 step = chunk_length-stride。这确保所有块具有相同的形状。

  • bandwidth (float, *可选*) — 目标带宽。必须是 config.target_bandwidths 中的之一。如果为 None,则使用可能的最小带宽。带宽表示为千分之一,例如 bandwidth == 6.0 表示 6kbps 带宽。
  • audio_codes (torch.LongTensor 形状为 (batch_size, nb_chunks, chunk_length), *可选*) — 使用 model.encode 计算的离散代码嵌入。
  • audio_scales (torch.Tensor 形状为 (batch_size, nb_chunks), *可选*) — 每个 audio_codes 输入的缩放因子。
  • return_dict (bool, 可选) — 是否返回 ModelOutput 而不是普通元组。

返回

transformers.models.encodec.modeling_encodec.EncodecOutputtuple(torch.FloatTensor)

一个 transformers.models.encodec.modeling_encodec.EncodecOutput 或一个 torch.FloatTensor 的元组(如果传递了 return_dict=False 或当 config.return_dict=False 时),包含根据配置 (EncodecConfig) 和输入的不同元素。

  • audio_codes (torch.LongTensor 形状为 (batch_size, nb_chunks, chunk_length), 可选) — 使用 model.encode 计算的离散代码嵌入。
  • audio_values (torch.FlaotTensor 形状为 (batch_size, sequence_length), 可选) 使用 Encodec 的解码器部分获得的解码音频值。

EncodecModel 正向方法,覆盖 __call__ 特殊方法。

虽然正向传递的配方需要在此函数中定义,但应该之后调用 Module 实例,而不是这个,因为前者负责运行前处理和后处理步骤,而后者则默默地忽略它们。

例子

>>> 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
< > 在 GitHub 上更新