EnCodec

概述

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

论文摘要如下：

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

此模型由 Matthijs、Patrick Von Platen 和 Arthur Zucker 贡献。原始代码可在此处找到。

使用示例

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

>>> 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_stride：int((1.0 - self.overlap) * self.chunk_length)。
hidden_size (int, 可选, 默认为 128) — 中间表示维度。
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") — 卷积的填充模式。
compress (int, 可选, 默认为 2) — 残差分支中的降维（来自 Demucs v3）。
num_lstm_layers (int, 可选, 默认为 2) — 编码器末尾的 LSTM 层数。
trim_right_ratio (float, 可选, 默认为 1.0) — 在 use_causal_conv = True 设置下，转置卷积右侧修剪的比率。如果等于 1.0，则表示所有修剪都在右侧完成。
codebook_size (int, 可选, 默认为 1024) — 构成 VQVAE 的离散代码的数量。
codebook_dim (int, 可选) — 码本向量的维度。如果未定义，则使用 hidden_size。
use_conv_shortcut (bool, 可选, 默认为 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: typing.Optional[float] = None overlap: typing.Optional[float] = None **kwargs )

参数

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

构建一个 EnCodec 特征提取器。

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

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

call

< 源 >

( raw_audio: typing.Union[numpy.ndarray, list[float], list[numpy.ndarray], list[list[float]]] padding: typing.Union[bool, str, transformers.utils.generic.PaddingStrategy, NoneType] = None truncation: typing.Optional[bool] = False max_length: typing.Optional[int] = None return_tensors: typing.Union[str, transformers.utils.generic.TensorType, NoneType] = None sampling_rate: typing.Optional[int] = None )

参数

raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — 要处理的序列或序列批次。每个序列可以是 numpy 数组、浮点值列表、numpy 数组列表或浮点值列表的列表。对于单声道音频（feature_size = 1），numpy 数组的形状必须为 (num_samples,)；对于立体声音频（feature_size = 2），必须为 (2, num_samples)。
padding (bool, str 或 PaddingStrategy, 可选, 默认为 True) — 在以下策略中选择一种来填充返回的序列（根据模型的填充侧和填充索引）：
- True 或 'longest'：填充到批次中最长的序列（如果只提供一个序列，则不填充）。
- 'max_length'：填充到由参数 max_length 指定的最大长度，或者如果未提供该参数，则填充到模型可接受的最大输入长度。
- False 或 'do_not_pad' (默认)：不填充（即，可以输出具有不同长度序列的批次）。
truncation (bool, 可选, 默认为 False) — 激活截断以将长于 max_length 的输入序列截断为 max_length。
max_length (int, 可选) — 返回列表的最大长度和可选的填充长度（见上文）。
return_tensors (str 或 TensorType, 可选) — 如果设置，将返回张量而不是 Python 整数列表。可接受的值为：
- 'tf'：返回 TensorFlow tf.constant 对象。
- 'pt'：返回 PyTorch torch.Tensor 对象。
- 'np'：返回 Numpy np.ndarray 对象。
sampling_rate (int, 可选) — audio 输入的采样率。强烈建议在转发调用时传递 sampling_rate，以防止静默错误。

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

EncodecModel

class transformers.EncodecModel

< source >

( config: EncodecConfig )

参数

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

EnCodec 神经网络音频编解码器模型。

此模型继承自 PreTrainedModel。请查看超类文档，了解库为其所有模型实现的一般方法（例如下载或保存、调整输入嵌入大小、修剪头部等）。

此模型也是 PyTorch torch.nn.Module 子类。将其作为常规 PyTorch 模块使用，并参阅 PyTorch 文档中所有与一般用法和行为相关的事项。

decode

< source >

( audio_codes: Tensor audio_scales: Tensor padding_mask: typing.Optional[torch.Tensor] = None return_dict: typing.Optional[bool] = None )

参数

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

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

请注意，输出可能比输入稍大。在这种情况下，末尾的任何额外步骤都可以剪切。

编码

< source >

( input_values: Tensor padding_mask: typing.Optional[torch.Tensor] = None bandwidth: typing.Optional[float] = None return_dict: typing.Optional[bool] = None )

参数

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

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

forward

< source >

( input_values: Tensor padding_mask: typing.Optional[torch.Tensor] = None bandwidth: typing.Optional[float] = None audio_codes: typing.Optional[torch.Tensor] = None audio_scales: typing.Optional[torch.Tensor] = None return_dict: typing.Optional[bool] = None ) → transformers.models.encodec.modeling_encodec.EncodecOutput 或 tuple(torch.FloatTensor)

参数

input_values (形状为 (batch_size, channels, sequence_length) 的 torch.FloatTensor，可选) — 原始音频输入，转换为浮点数并填充到适当长度，以便使用长度为 self.chunk_length 且步幅为 config.chunk_stride 的块进行编码。
padding_mask (形状为 (batch_size, channels, sequence_length) 的 torch.BoolTensor，可选) — 用于避免在填充标记索引上计算缩放因子的掩码（我们能否避免在这些标记上计算卷积？）。掩码值选择在 [0, 1] 中：
- 1 表示**未被掩码**的标记，
- 0 表示**被掩码**的标记。
除非输入被截断或未填充，否则应始终传递 padding_mask。这是因为为了有效处理张量，输入音频应进行填充，以便 input_length % stride = step，其中 step = chunk_length-stride。这确保了所有块都具有相同的形状。
bandwidth (float, 可选) — 目标带宽。必须是 config.target_bandwidths 之一。如果为 None，则使用最小可能的带宽。带宽表示为其千分之一，例如 6kbps 带宽表示为 bandwidth == 6.0
audio_codes (形状为 (batch_size, nb_chunks, chunk_length) 的 torch.LongTensor，可选) — 使用 model.encode 计算的离散代码嵌入。
audio_scales (形状为 (batch_size, nb_chunks) 的 torch.Tensor，可选) — 每个 audio_codes 输入的缩放因子。
return_dict (bool, 可选) — 是否返回 ModelOutput 而不是普通元组。

transformers.models.encodec.modeling_encodec.EncodecOutput 或 tuple(torch.FloatTensor)

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

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

EncodecModel 的 forward 方法，重写了 __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 上更新

Transformers

EnCodec

概述

使用示例

EncodecConfig

class transformers.EncodecConfig

EncodecFeatureExtractor

class transformers.EncodecFeatureExtractor

__call__

EncodecModel

class transformers.EncodecModel

decode

编码

forward

call