该模型于 2022-10-24 在 HF papers 上发布，并于 2023-06-14 贡献至 Hugging Face Transformers。

EnCodec

概述

EnCodec 神经编解码模型由 Alexandre Défossez、Jade Copet、Gabriel Synnaeve 和 Yossi Adi 在 High Fidelity Neural Audio Compression 中提出。

该论文的摘要如下：

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

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

使用示例

以下是使用此模型对音频进行编码和解码的简单示例：

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

class transformers.EncodecConfig

< source >

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

参数

target_bandwidths (list[float]，可选，默认为 [1.5, 3.0, 6.0, 12.0, 24.0]) — 模型可用于编码音频的不同带宽范围。
sampling_rate (int，可选，默认为 24000) — 音频文件应被数字化时的采样率，单位为赫兹（Hz）。
audio_channels (int，可选，默认为 1) — 输入通道的数量。
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) — 每一层中膨胀率（dilation）的增加量。
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) — 模型使用的并行码本数量。
codebook_dim (int，可选) — 每个码本嵌入向量的维度。
use_conv_shortcut (bool，可选，默认为 True) — 是否使用卷积层作为 EncodecResnetBlock 块中的“skip”连接。如果为 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

< source >

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

参数

feature_size (int，可选，默认为 1) — 提取特征的维度。单声道使用 1，立体声使用 2。
sampling_rate (int，可选，默认为 24000) — 用于数字化音频波形的采样率，单位为赫兹（Hz）。
padding_value (float，可选，默认为 0.0) — 用于填充 padding 值的数值。
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 (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 整数列表。可接受的值为：
- 'pt'：返回 PyTorch torch.Tensor 对象。
- 'np'：返回 Numpy np.ndarray 对象。
sampling_rate (int, 可选) — audio 输入被采样时的采样率。强烈建议在 forward 调用时传入 sampling_rate，以避免静默错误。

用于对一条或多条序列进行特征化并准备输入模型的主要方法。

EncodecModel

class transformers.EncodecModel

< source >

( config: EncodecConfig )

参数

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

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

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

decode

< source >

( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )

参数

audio_codes (torch.LongTensor，形状为 (nb_frames, batch_size, nb_quantizers, frame_len)，可选) — 使用 model.encode 计算得到的离散码嵌入。
audio_scales（长度为 nb_frames 的列表，元素为形状 (batch_size, 1) 的 torch.Tensor，可选） — 每个 audio_codes 输入的缩放因子。
padding_mask（形状为 (channels, sequence_length) 的 torch.Tensor）— 用于填充 input_values 的填充掩码。
return_dict (bool, 可选) — 是否返回 ModelOutput 而不是普通元组。
last_frame_pad_length (int, 可选) — 表示最后一帧中填充长度的整数，该填充会在解码过程中被移除。

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

请注意，输出可能比输入稍大。在这种情况下，末尾多余的步骤可以被裁剪掉。

encode

< source >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing

参数

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，则使用尽可能小的带宽。bandwidth 以其千分之一的值表示，例如 6kbps 的带宽表示为 bandwidth == 6.0

返回值

EncodecEncoderOutput 字典或元组，包含

audio_codes（形状为 (nb_frames, batch_size, nb_quantizers, frame_len) 的 torch.LongTensor，可选），
audio_scales（长度为 nb_frames 的列表，其中每个元素为形状为 (batch_size, 1) 的 torch.Tensor，可选），
last_frame_pad_length (int，可选)。

将输入音频波形编码为形状为 (nb_frames, batch_size, nb_quantizers, frame_len) 的离散码。

如果 self.config.chunk_length=None（因为编码器应用于完整音频），则 nb_frames=1，24kHz 模型即属于这种情况。否则，nb_frames=ceil(input_length/self.config.chunk_stride)，48kHz 模型即属于这种情况。
frame_len 是每个帧的长度。当 self.config.chunk_length=None 时（例如 24kHz 模型），其值等于 ceil(input_length/self.config.hop_length)。否则，如果定义了 self.config.chunk_length，则 frame_len=self.config.chunk_length/self.config.hop_length，例如 48kHz 模型中 frame_len=150 的情况。

forward

< source >

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

参数

input_values（形状为 (batch_size, channels, sequence_length) 的 torch.Tensor，可选） — 转换为 Float 并填充至适当长度的原始音频输入，以便使用长度为 self.chunk_length、步长为 config.chunk_stride 的块进行编码。
padding_mask (torch.BoolTensor 形状为 (batch_size, channels, sequence_length), ，可选) — 用于避免在填充 token 索引上计算缩放因子的掩码（是否可以避免在这些位置上进行卷积运算？）。掩码值取自 [0, 1]：1 表示未被掩码的 token，0 表示被掩码的 token。除非输入被截断或未进行填充，否则应始终传入 padding_mask。这是因为为了高效处理张量，输入音频应进行填充，使得 input_length % stride = step，其中 step = chunk_length - stride。这样可以确保所有 chunk 的形状一致 [0, 1]:
- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
padding_mask 应始终传入，除非输入已被截断或未进行填充。这是因为为了有效处理张量，输入音频应进行填充，使得 input_length % stride = step，其中 step = chunk_length-stride。这确保了所有块具有相同的形状
bandwidth (float, 可选) — 目标带宽。必须是 config.target_bandwidths 中的一个值。如果为 None，则使用尽可能小的带宽。bandwidth 以千分位表示，例如 6kbps 的带宽表示为 bandwidth == 6.0
audio_codes (torch.LongTensor，形状为 (nb_frames, batch_size, nb_quantizers, frame_len)，可选) — 使用 model.encode 计算得到的离散码嵌入。
audio_scales（list，长度为 nb_frames，元素为形状 (batch_size, 1) 的 torch.Tensor，可选） — 每个 audio_codes 输入的缩放因子。
return_dict (bool, 可选) — 是否以字典形式返回输出。
last_frame_pad_length (int, 可选) — 最后一帧的填充长度（如果存在）。此值用于确保编码后的帧能够以张量形式输出。在解码时应传入此值，以确保从编码后的帧中移除填充。

返回值

EncodecOutput 或 tuple(torch.Tensor)

EncodecOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（EncodecConfig）和输入。

EncodecModel 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 Module 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。

audio_codes（形状为 (nb_frames, batch_size, nb_quantizers, frame_len) 的 torch.LongTensor，可选）— 使用 model.encode 计算得到的离散码嵌入。
audio_values（形状为 (batch_size, segment_length) 的 torch.Tensor，可选）— 解码后的音频值，通过 Encodec 的解码器部分获得。

示例：

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