# DAC

## 概述

DAC 模型由 Rithesh Kumar、Prem Seetharaman、Alejandro Luebs、Ishaan Kumar 和 Kundan Kumar 在 [Descript Audio Codec: High-Fidelity Audio Compression with Improved RVQGAN](https://huggingface.co/papers/2306.06546) 中提出。

Descript Audio Codec（DAC）模型是一款强大的音频数据压缩工具，在存储和传输方面具有极高的效率。通过将 44.1 KHz 音频压缩为仅占用 8kbps 带宽的 token，DAC 模型在显著降低数据占用的同时，实现了高质量的音频处理。这在带宽受限或存储空间宝贵的场景中尤为有用，例如流媒体应用、远程会议以及大型音频数据集的归档。

该论文的摘要如下：

*语言模型已被成功用于对图像、语音和音乐等自然信号进行建模。这些模型的一个关键组成部分是高质量的神经压缩模型，它能够将高维自然信号压缩为低维离散 token。为此，我们提出了一种高保真的通用神经音频压缩算法，可将 44.1 KHz 音频以仅 8kbps 的带宽压缩为 token，实现约 90 倍的压缩率。我们通过将高保真音频生成的最新进展与图像领域中更优的向量量化技术相结合，并改进对抗损失和重建损失，实现了这一目标。我们使用单一的通用模型压缩所有领域（语音、环境声、音乐等），使其可广泛应用于所有音频的生成式建模。我们将本方法与现有的音频压缩算法进行了对比，发现我们的方法显著优于它们。我们为每个设计选择提供了详尽的消融实验，并开源了代码和训练好的模型权重。我们希望我们的工作能为下一代高保真音频建模奠定基础。*

该模型由 [Kamil Akesbi](https://huggingface.co/kamilakesbi) 贡献。原始代码可在 [此处](https://github.com/descriptinc/descript-audio-codec/tree/main?tab=readme-ov-file) 找到。

## 模型结构

Descript 音频编解码器（DAC）模型由三个不同的阶段组成：

1. 编码器模型：此阶段对输入音频进行压缩，在保留关键信息的同时减小其体积。
2. 残差向量量化器（RVQ）模型：与编码器协同工作，该模型对音频的潜在编码进行量化，优化压缩效果并确保高质量的重建。
3. 解码器模型：此最终阶段从压缩形式重建音频，将其恢复为与原始输入高度相似的状态。

## 使用示例

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

```python
from datasets import Audio, load_dataset

from transformers import AutoProcessor, DacModel

librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

model = DacModel.from_pretrained("descript/dac_16khz", device_map="auto")
processor = AutoProcessor.from_pretrained("descript/dac_16khz")
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"])
# Get the intermediate audio codes
audio_codes = encoder_outputs.audio_codes
# Reconstruct the audio from its quantized representation
audio_values = model.decode(encoder_outputs.quantized_representation)
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_values
```

## DacConfig[[transformers.DacConfig]]

#### transformers.DacConfig[[transformers.DacConfig]]

```python
transformers.DacConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, encoder_hidden_size: int = 64, downsampling_ratios: list[int] | tuple[int, ...] = (2, 4, 8, 8), decoder_hidden_size: int = 1536, n_codebooks: int = 9, codebook_size: int = 1024, codebook_dim: int = 8, quantizer_dropout: float | int = 0.0, commitment_loss_weight: float = 0.25, codebook_loss_weight: float = 1.0, sampling_rate: int = 16000)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/configuration_dac.py#L27)

**参数：**

encoder_hidden_size (`int`，*可选*，默认为 `64`)：隐藏表示的维度。

downsampling_ratios (`list[int]`, *可选*, 默认为 `[2, 4, 8, 8]`) : 编码器中的下采样比率。这些比率在解码器中按相反顺序用于上采样。

decoder_hidden_size (`int`，*可选*，默认为 `1536`)：隐藏表示的维度。

n_codebooks (`int`，*可选*，默认为 `9`)：模型使用的并行码本数量。

codebook_size (`int`，*可选*，默认为 `1024`)：模型使用的并行码本数量。

codebook_dim (`int`，*可选*，默认为 `8`)：每个码本嵌入向量的维度。

quantizer_dropout (`bool`, *可选*, 默认为 0) : 是否对量化器应用 dropout。

commitment_loss_weight (`float`, *可选*，默认为 0.25)：VQVAE 损失函数中承诺损失项的权重。

codebook_loss_weight (`float`, *可选*，默认为 1.0)：VQVAE 损失函数中码本损失项的权重。

sampling_rate (`int`, *可选*，默认为 `16000`)：音频文件应被数字化采样的采样率，以赫兹（Hz）为单位。

这是用于存储 DacModel 配置的类。它根据指定的参数实例化 Dac 模型，并定义模型架构。使用默认值实例化配置将生成与 [descript/dac_16khz](https://huggingface.co/descript/dac_16khz) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import DacModel, DacConfig

>>> # Initializing a "descript/dac_16khz" style configuration
>>> configuration = DacConfig()

>>> # Initializing a model (with random weights) from the "descript/dac_16khz" style configuration
>>> model = DacModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## DacFeatureExtractor[[transformers.DacFeatureExtractor]]

#### transformers.DacFeatureExtractor[[transformers.DacFeatureExtractor]]

```python
transformers.DacFeatureExtractor(feature_size: int = 1, sampling_rate: int = 16000, padding_value: float = 0.0, hop_length: int = 512, **kwargs)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/feature_extraction_dac.py#L26)

**参数：**

feature_size (`int`，*可选*，默认为 1)：提取特征的维度。单声道使用 1，立体声使用 2。

sampling_rate (`int`, *可选*，默认为 16000)：音频波形应被数字化采样的采样率，以赫兹 (Hz) 为单位。

padding_value (`float`, *可选*, 默认值为 0.0) : 用于填充的值。

hop_length (`int`，*可选*，默认为 512)：连续窗口之间的重叠长度。

构建一个 Dac 特征提取器。

此特征提取器继承自 [SequenceFeatureExtractor](/docs/transformers/main/zh/main_classes/feature_extractor#transformers.SequenceFeatureExtractor)，后者包含了大部分主要方法。有关这些方法的更多信息，请参阅该父类。

#### __调用__[[transformers.DacFeatureExtractor.__call__]]

```python
__call__(raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]], padding: bool | str | transformers.utils.generic.PaddingStrategy | None = None, truncation: bool | None = False, max_length: int | None = None, return_tensors: str | transformers.utils.generic.TensorType | None = None, sampling_rate: int | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/feature_extraction_dac.py#L57)

**参数：**

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](/docs/transformers/main/zh/internal/file_utils#transformers.utils.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](/docs/transformers/main/zh/internal/file_utils#transformers.TensorType)，*可选*，默认为 'pt')：如果设置，将返回张量而不是 Python 整数列表。可接受的值为： - `'pt'`：返回 PyTorch `torch.Tensor` 对象。 - `'np'`：返回 Numpy `np.ndarray` 对象。

sampling_rate (`int`, *可选*) : `audio` 输入的采样率。强烈建议在 forward 调用时传入 `sampling_rate`，以避免静默错误。

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

## DacModel[[transformers.DacModel]]

#### transformers.DacModel[[transformers.DacModel]]

```python
transformers.DacModel(config: DacConfig)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/modeling_dac.py#L563)

**参数：**

config ([DacConfig](/docs/transformers/main/zh/model_doc/dac#transformers.DacConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化并不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

DAC（Descript Audio Codec）模型。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel)。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

#### decode[[transformers.DacModel.decode]]

```python
decode(quantized_representation: typing.Optional[torch.Tensor] = None, audio_codes: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/modeling_dac.py#L609)

**参数：**

quantized_representation (`torch.Tensor`，形状为 `(batch_size, dimension, time_steps)`，*可选*) : 输入的量化连续表示。

audio_codes (`torch.Tensor`，形状为 `(batch_size, num_codebooks, time_steps)`，*可选*)：每个码本的码本索引，表示输入的量化离散表示。如果您希望直接从音频码进行解码，则应提供此参数（它将覆盖 quantized_representation）。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `DacDecoderOutput` 而不是普通元组。

**返回：** `DacDecoderOutput` 或 `tuple(torch.Tensor)`

`DacDecoderOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DacConfig](/docs/transformers/main/zh/model_doc/dac#transformers.DacConfig)）和输入。

- **audio_values**（形状为 `(batch_size, input_length)` 的 `torch.Tensor`，*可选*）-- 使用 Dac 的解码器部分获得的解码后的音频值。

#### encode[[transformers.DacModel.encode]]

```python
encode(input_values: Tensor, n_quantizers: int | None = None, return_dict: bool | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/modeling_dac.py#L582)

**参数：**

input_values (`torch.Tensor of shape `(batch_size, 1, time_steps)`) : 要编码的输入音频数据，

n_quantizers (`int`, *可选*) : 要使用的量化器数量。如果为 None，则使用所有量化器。默认为 None。

return_dict (`bool`, *可选*) : 是否返回 [ModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.utils.ModelOutput) 而不是普通元组。

**返回：** `DacEncoderOutput` 或 `tuple(torch.Tensor)`

`DacEncoderOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[DacConfig](/docs/transformers/main/zh/model_doc/dac#transformers.DacConfig)）和输入。

- **loss** (`torch.Tensor`, *可选*) -- 来自编码器模型的损失，由承诺损失和码本损失的加权组合构成。
- **quantized_representation** (`torch.Tensor`，形状为 `(batch_size, dimension, time_steps)`，*可选*) -- 输入的量化连续表示。
- **audio_codes**（形状为 `(batch_size, num_codebooks, time_steps)` 的 `torch.Tensor`，*可选*）-- 每个码本的码本索引（输入的量化离散表示）。
- **projected_latents** (`torch.Tensor`，形状为 `(batch_size, num_codebooks * dimension, time_steps)`，*可选*) -- 投影后的潜变量（量化前输入的连续表示）。

#### forward[[transformers.DacModel.forward]]

```python
forward(input_values: Tensor, n_quantizers: int | None = None, return_dict: bool | None = None)
```

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dac/modeling_dac.py#L642)

**参数：**

input_values (`torch.Tensor`，形状为 `(batch_size, 1, time_steps)`)：要编码的音频数据。

n_quantizers (`int`, *可选*) : 要使用的量化器数量。如果为 `None`，则使用所有量化器。默认值为 `None`。

return_dict (`bool`, *可选*) : 是否返回 [ModelOutput](/docs/transformers/main/zh/main_classes/output#transformers.utils.ModelOutput) 而不是普通元组。

**返回：** `DacOutput` 或 `tuple(torch.Tensor)`

`DacOutput` 或 `torch.Tensor` 元组（当传入 `return_dict=False` 或 `config.return_dict=False` 时），其包含的元素取决于配置（[DacConfig](/docs/transformers/main/zh/model_doc/dac#transformers.DacConfig)）和输入。

[DacModel](/docs/transformers/main/zh/model_doc/dac#transformers.DacModel) 的 forward 方法会重写 `__call__` 特殊方法。

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

- **loss** (`torch.Tensor`, *可选*) -- 来自编码器模型的损失，由承诺损失和码本损失的加权组合构成。
- **audio_values**（形状为 `(batch_size, input_length)` 的 `torch.Tensor`）-- 重构的音频数据。
- **quantized_representation**（形状为 `(batch_size, dimension, time_steps)` 的 `torch.Tensor`）-- 输入的量化连续表示。
- **audio_codes**（形状为 `(batch_size, num_codebooks, time_steps)` 的 `torch.LongTensor`）-- 每个码本的码本索引（输入的量化离散表示）。
- **projected_latents** (`torch.Tensor`，形状为 `(batch_size, num_codebooks * dimension, time_steps)`) -- 投影后的潜在变量（量化前输入的连续表示）。

示例：

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

>>> model = DacModel.from_pretrained("descript/dac_16khz")
>>> processor = AutoProcessor.from_pretrained("descript/dac_16khz")
>>> 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"])
>>> # Get the intermediate audio codes
>>> audio_codes = encoder_outputs.audio_codes
>>> # Reconstruct the audio from its quantized representation
>>> audio_values = model.decode(encoder_outputs.quantized_representation)
>>> # or the equivalent with a forward pass
>>> audio_values = model(inputs["input_values"]).audio_values
```

