EnCodec
概述
EnCodec 神经编解码器模型在 High Fidelity Neural Audio Compression 中被 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_valuesEncodecConfig
class transformers.EncodecConfig
< source >( 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.configEncodecFeatureExtractor
class transformers.EncodecFeatureExtractor
< source >( 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, 可选, 默认为 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__
< source >( 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 数组列表或浮点值列表的列表。 对于单声道音频 (feature_size = 1)，numpy 数组的形状必须为(num_samples,)；对于立体声音频 (feature_size = 2)，numpy 数组的形状必须为(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'：返回 TensorFlowtf.constant对象。'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.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: Optional = None return_dict: Optional = 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 而不是普通元组。
将给定的帧解码为输出音频波形。
请注意，输出可能比输入稍大。 在这种情况下，可以修剪末尾的任何额外步骤。
encode
< source >( input_values: Tensor padding_mask: Tensor = None bandwidth: Optional = None return_dict: Optional = None )
参数
- input_values (形状为
(batch_size, channels, sequence_length)的torch.Tensor) — 输入音频波形的浮点值。 - padding_mask (形状为
(batch_size, channels, sequence_length)的torch.Tensor) — 用于填充input_values的填充掩码。 - bandwidth (
float, optional) — 目标带宽。必须是config.target_bandwidths中的一个。如果为None，则使用可能的最小带宽。带宽以千分之一表示，例如 6kbps 带宽表示为 bandwidth == 6.0
将输入的音频波形编码为离散代码。
forward
< source >( 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.EncodecOutput 或 tuple(torch.FloatTensor)
参数
- input_values (
torch.FloatTensor，形状为(batch_size, channels, sequence_length)，可选) — 原始音频输入已转换为 Float 类型，并填充到适当的长度，以便使用长度为 self.chunk_length 和步长为config.chunk_stride的块进行编码。 - padding_mask (
torch.BoolTensor，形状为(batch_size, channels, sequence_length)，可选) — 用于避免计算填充 token 索引上的缩放因子的掩码（我们可以避免在这些索引上计算 conv 吗？）。掩码值在[0, 1]中选择：- 1 表示 未被掩码 的 token，
- 0 表示 已被掩码 的 token。
padding_mask应始终传递，除非输入被截断或未填充。这是因为为了有效地处理张量，输入音频应进行填充，以便input_length % stride = step，其中step = chunk_length-stride。这确保所有块都具有相同的形状 - bandwidth (
float, optional) — 目标带宽。必须是config.target_bandwidths中的一个。如果为None，则使用可能的最小带宽。带宽以千分之一表示，例如 6kbps 带宽表示为bandwidth == 6.0 - 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, optional) — 是否返回 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 (
torch.LongTensor，形状为(batch_size, nb_chunks, chunk_length)，可选) — 使用model.encode计算的离散代码嵌入。 - audio_values (
torch.FlaotTensor，形状为(batch_size, sequence_length)，可选) 使用 Encodec 的解码器部分获得的解码音频值。
EncodecModel forward 方法，覆盖了 __call__ 特殊方法。
尽管 forward 传递的配方需要在该函数中定义，但应在此之后调用 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