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
类 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
, optional, defaults to 24000) — 音频波形应被数字化的采样率,以赫兹(Hz)表示。 - audio_channels (
int
, optional, 默认为 1) — 音频数据中的通道数。1 表示单声道,2 表示立体声。 - normalize (
bool
, 可选, 默认为False
) — 音频在传递时是否应进行标准化处理。 - chunk_length_s (
float
, optional) — 如果定义了,音频将被预处理成长度为chunk_length_s
的块,然后进行编码。 - overlap (
float
, 可选) — 定义每个块之间的重叠。它用于通过以下公式计算chunk_stride
:int((1.0 - self.overlap) * self.chunk_length)
. - hidden_size (
int
, optional, 默认为 128) — 中间表示的维度。 - num_filters (
int
, 可选, 默认为 32) — 第一个EncodecConv1d
下采样层的卷积核数量。 - num_residual_layers (
int
, optional, defaults to 1) — 残差层的数量。 - upsampling_ratios (
Sequence[int]
, 可选, 默认为[8, 5, 4, 2]
) — 核大小和步幅比率。编码器使用下采样比率而不是上采样比率,因此它将使用与这里指定的比率相反的顺序,这些比率必须与解码器的顺序匹配。 - norm_type (
str
, 可选, 默认为"weight_norm"
) — 归一化方法。应在["weight_norm", "time_group_norm"]
中 - kernel_size (
int
, optional, defaults to 7) — 初始卷积的核大小。 - last_kernel_size (
int
, optional, 默认为 7) — 最后一个卷积层的核大小。 - residual_kernel_size (
int
, optional, defaults to 3) — 残差层的核大小。 - dilation_growth_rate (
int
, optional, defaults to 2) — 每层增加多少扩张率. - use_causal_conv (
bool
, optional, defaults toTrue
) — 是否使用完全因果卷积。 - pad_mode (
str
, 可选, 默认为"reflect"
) — 卷积的填充模式。 - compress (
int
, 可选, 默认为 2) — 残差分支中的降维(来自 Demucs v3)。 - num_lstm_layers (
int
, optional, defaults to 2) — 编码器末尾的LSTM层数。 - trim_right_ratio (
float
, 可选, 默认为 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
, 可选, 默认为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
类 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
, optional, 默认为 1) — 提取特征的特征维度。单声道使用1,立体声使用2。 - sampling_rate (
int
, optional, defaults to 24000) — 音频波形应被数字化的采样率,以赫兹(Hz)表示。 - padding_value (
float
, optional, 默认为 0.0) — 用于填充填充值的值。 - chunk_length_s (
float
, optional) — 如果定义了,音频将被预处理成长度为chunk_length_s
的块,然后进行编码。 - overlap (
float
, 可选) — 定义每个块之间的重叠。它用于通过以下公式计算chunk_stride
:int((1.0 - self.overlap) * self.chunk_length)
.
构建一个EnCodec特征提取器。
此特征提取器继承自SequenceFeatureExtractor,其中包含 大部分主要方法。用户应参考此超类以获取有关这些方法的更多信息。
使用默认值实例化特征提取器将产生与facebook/encodec_24khz架构类似的配置。
__call__
< source >( raw_audio: typing.Union[numpy.ndarray, typing.List[float], typing.List[numpy.ndarray], typing.List[typing.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
or PaddingStrategy, optional, defaults toTrue
) — Select a strategy to pad the returned sequences (according to the model’s padding side and padding index) among:True
or'longest'
: Pad to the longest sequence in the batch (or no padding if only a single sequence if provided).'max_length'
: Pad to a maximum length specified with the argumentmax_length
or to the maximum acceptable input length for the model if that argument is not provided.False
or'do_not_pad'
(default): No padding (i.e., can output a batch with sequences of different lengths).
- 截断 (
bool
, 可选, 默认为False
) — 激活截断功能,将超过max_length
的输入序列截断至max_length
. - max_length (
int
, optional) — 返回列表的最大长度以及可选的填充长度(见上文)。 - return_tensors (
str
或 TensorType, 可选) — 如果设置,将返回张量而不是Python整数列表。可接受的值有:'tf'
: 返回 TensorFlowtf.constant
对象。'pt'
: 返回 PyTorchtorch.Tensor
对象。'np'
: 返回 Numpynp.ndarray
对象。
- sampling_rate (
int
, optional) —audio
输入被采样的采样率。强烈建议在前向调用时传递sampling_rate
以防止静默错误。
用于特征化并为一个或多个序列准备模型的主要方法。
EncodecModel
类 transformers.EncodecModel
< source >( config: EncodecConfig )
参数
- config (EncodecConfig) — 模型配置类,包含模型的所有参数。使用配置文件初始化不会加载与模型相关的权重,仅加载配置。查看 from_pretrained() 方法以加载模型权重。
EnCodec 神经音频编解码器模型。 该模型继承自 PreTrainedModel。请查看超类文档以了解库为其所有模型实现的通用方法(如下载或保存、调整输入嵌入大小、修剪头等)。
该模型也是一个PyTorch torch.nn.Module 子类。 将其作为常规的PyTorch模块使用,并参考PyTorch文档以获取与一般使用和行为相关的所有信息。
解码
< source >( audio_codes: Tensor audio_scales: Tensor padding_mask: typing.Optional[torch.Tensor] = None return_dict: typing.Optional[bool] = None )
参数
- audio_codes (
torch.LongTensor
形状为(batch_size, nb_chunks, chunk_length)
, 可选) — 使用model.encode
计算的离散代码嵌入. - audio_scales (
torch.Tensor
of shape(batch_size, nb_chunks)
, optional) — 每个audio_codes
输入的缩放因子。 - padding_mask (
torch.Tensor
of shape(batch_size, channels, sequence_length)
) — 用于填充input_values
的填充掩码。 - return_dict (
bool
, 可选) — 是否返回一个ModelOutput而不是一个普通的元组。
将给定的帧解码为输出音频波形。
请注意,输出可能比输入稍大。在这种情况下,可以修剪末尾的任何额外步骤。
编码
< source >( input_values: 张量 padding_mask: 张量 = 无 bandwidth: 可选[浮点数] = 无 return_dict: 可选[布尔值] = 无 )
参数
- input_values (
torch.Tensor
of shape(batch_size, channels, sequence_length)
) — 输入音频波形的浮点值。 - padding_mask (
torch.Tensor
of shape(batch_size, channels, sequence_length)
) — 用于填充input_values
的填充掩码。 - 带宽 (
float
, 可选) — 目标带宽。必须是config.target_bandwidths
中的一个。如果为None
,则使用最小可能的 带宽。带宽以千分之一表示,例如 6kbps 带宽表示为 带宽 == 6.0
将输入的音频波形编码为离散代码。
前进
< 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 (
torch.FloatTensor
形状为(batch_size, channels, sequence_length)
, 可选) — 原始音频输入转换为浮点数并填充到适当的长度,以便使用长度为 self.chunk_length 和步幅为config.chunk_stride
的块进行编码。 - padding_mask (
torch.BoolTensor
of shape(batch_size, channels, sequence_length)
, optional) — Mask to avoid computing scaling factors on padding token indices (can we avoid computing conv on these+). Mask values selected in[0, 1]
:- 1 for tokens that are not masked,
- 0 for tokens that are masked.
padding_mask
应该始终被传递,除非输入被截断或未填充。这是因为为了有效地处理张量,输入音频应该被填充,以便input_length % stride = step
且step = chunk_length-stride
。这确保了所有块具有相同的形状。 - 带宽 (
float
, 可选) — 目标带宽。必须是config.target_bandwidths
中的一个。如果为None
,则使用最小可能的 带宽。带宽以其千分之一表示,例如 6kbps 带宽表示为bandwidth == 6.0
- audio_codes (
torch.LongTensor
形状为(batch_size, nb_chunks, chunk_length)
, 可选) — 使用model.encode
计算的离散代码嵌入. - audio_scales (
torch.Tensor
of shape(batch_size, nb_chunks)
, optional) — 每个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 (
torch.LongTensor
形状为(batch_size, nb_chunks, chunk_length)
, 可选) — 使用model.encode
计算的离散代码嵌入。 - audio_values (
torch.FlaotTensor
形状为(batch_size, sequence_length)
, 可选) 解码的音频值,使用 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