# 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 の帯域幅でトークンに圧縮することで、DAC モデルはデータサイズを大幅に削減しながら、高品質な音声処理を可能にします。これは、ストリーミングアプリケーション、リモート会議、大規模な音声データセットのアーカイブなど、帯域幅が制限されている場合やストレージ容量が重要なシナリオで特に有用です。

論文の抄録は以下の通りです。

*言語モデルは、画像、音声、音楽などの自然シグナルのモデリングに成功裏に活用されてきました。これらのモデルの重要な構成要素は、高次元の自然シグナルを低次元の離散トークンに圧縮できる高品質なニューラル圧縮モデルです。この目的のため、44.1 KHz の音声をわずか 8kbps の帯域幅でトークンに圧縮し、約 90 倍の圧縮率を実現する、高忠実度の汎用ニューラル音声圧縮アルゴリズムを導入します。これは、高忠実度の音声生成の進歩と、画像分野からのより優れたベクトル量子化技術、さらに改善された敵対的損失と再構成損失を組み合わせることで実現しています。単一の汎用モデルですべてのドメイン（音声、環境音、音楽など）を圧縮するため、すべての音声の生成モデリングに広く適用できます。競合する音声圧縮アルゴリズムと比較したところ、本手法がそれらを大幅に上回ることを確認しました。すべての設計判断について徹底的なアブレーション分析を行い、オープンソースのコードと学習済みモデルの重みも提供します。本作業が、次世代の高忠実度音声モデリングの基盤となることを期待しています。*

このモデルは[Kamil Akesbi](https://huggingface.co/kamilakesbi)氏によって提供されました。元のコードは[こちら](https://github.com/descriptinc/descript-audio-codec/tree/main?tab=readme-ov-file)で確認できます。

## モデル構造

Descript Audio Codec (DAC) モデルは、3つの異なる段階で構成されています。

1. Encoder Model: この段階では、入力オーディオを圧縮し、サイズを縮小しながらも本質的な情報を保持します。
2. Residual Vector Quantizer (RVQ) モデル: エンコーダーと連携して動作し、音声の潜在コードを量子化します。これにより圧縮が洗練され、高品質な再構築が保証されます。
3. Decoder Model：この最終段階では、圧縮された形式からオーディオを再構築し、元の入力に非常に近い状態に復元します。

## 使用例

このモデルを使用してオーディオをエンコードおよびデコードする簡単な例を以下に示します。

```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]`、*optional*、デフォルトは`[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`、*optional*、デフォルトは`16000`) : 音声ファイルをデジタル化するためのサンプリングレート（ヘルツ (Hz) 単位）。

これは、DacModel の設定を保存するための設定クラスです。指定された引数に基づいて Dac モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[descript/dac_16khz](https://huggingface.co/descript/dac_16khz) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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`, *optional*, デフォルトは 1) : 抽出された特徴量の次元数です。モノラルの場合は 1、ステレオの場合は 2 を指定します。

sampling_rate (`int`、*optional*、デフォルトは 16000) : 音声波形をデジタル化するためのサンプリングレート（ヘルツ (Hz) 単位）。

padding_value (`float`、*任意*、デフォルト値は 0.0) : パディングに使用される値。

hop_length (`int`、*optional*、デフォルトは 512) : 連続するウィンドウ間のオーバーラップ長。

Dacのフィーチャーエクストラクターを構築します。

このフィーチャーエクストラクターは、主要なメソッドの大部分を含む [SequenceFeatureExtractor](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。

#### __call__[[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/ja/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`, *optional*) : 返されるリストの最大長、および必要に応じてパディング長（上記を参照）。

return_tensors (`str` または [TensorType](/docs/transformers/main/ja/internal/file_utils#transformers.TensorType)、*optional*、デフォルトは 'pt') : 設定されている場合、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです: - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: Numpy の `np.ndarray` オブジェクトを返します。

sampling_rate (`int`, *任意*) : `audio` 入力がサンプリングされたレートです。サイレントエラーを防ぐため、forward 呼び出し時に `sampling_rate` を渡すことを強く推奨します。

1つ以上のシーケンスを特徴量化し、モデル用に準備するための主要なメソッド。

## 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/ja/model_doc/dac#transformers.DacConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

DAC(Descript Audio Codec)モデル。

このモデルは [PreTrainedModel](/docs/transformers/main/ja/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`、shape `(batch_size, num_codebooks, time_steps)`、*optional*) : 各 codebook に対する codebook indices。入力の量子化された離散表現を表します。音声コードから直接デコードしたい場合は、このパラメータを指定してください（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/ja/model_doc/dac#transformers.DacConfig)）と入力に応じて、さまざまな要素で構成されます。

- **audio_values** (`torch.Tensor`、形状 `(batch_size, input_length)`、*任意*) -- 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`, *optional*) : 使用するクオンタイザーの数。None の場合、すべてのクオンタイザーが使用されます。デフォルトは None です。

return_dict (`bool`, *任意*) : プレーンなタプルではなく [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

**戻り値:** `DacEncoderOutput` または `tuple(torch.Tensor)`

`DacEncoderOutput`、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[DacConfig](/docs/transformers/main/ja/model_doc/dac#transformers.DacConfig)）と入力に応じて、さまざまな要素で構成されます。

- **loss** (`torch.Tensor`, *optional*) -- エンコーダーモデルからの損失。コミットメント損失とコードブック損失の重み付き組み合わせから構成されます。
- **quantized_representation** (`torch.Tensor`、形状 `(batch_size, dimension, time_steps)`、*任意*) -- 入力に対する量子化された連続表現。
- **audio_codes** (`torch.Tensor`、形状 `(batch_size, num_codebooks, time_steps)`、*任意*) -- 各コードブックのインデックス（入力の量子化された離散表現）。
- **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`、shape `(batch_size, 1, time_steps)`) : エンコードするオーディオデータ。

n_quantizers (`int`, *optional*) : 使用するクアンタイザーの数。`None`の場合、すべてのクアンタイザーが使用されます。デフォルトは`None`です。

return_dict (`bool`, *任意*) : プレーンなタプルではなく [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか。

**戻り値:** `DacOutput` または `tuple(torch.Tensor)`

`DacOutput`、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[DacConfig](/docs/transformers/main/ja/model_doc/dac#transformers.DacConfig)）と入力に応じて、さまざまな要素で構成されます。

[DacModel](/docs/transformers/main/ja/model_doc/dac#transformers.DacModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **loss** (`torch.Tensor`, *optional*) -- エンコーダーモデルからの損失。コミットメント損失とコードブック損失の重み付き組み合わせから構成されます。
- **audio_values** (`torch.Tensor`、形状 `(batch_size, input_length)`) -- 再構成されたオーディオデータ。
- **quantized_representation** (`torch.Tensor`、形状 `(batch_size, dimension, time_steps)`) -- 入力の量子化された連続表現。
- **audio_codes** (`torch.LongTensor`、shape `(batch_size, num_codebooks, time_steps)`) -- 各 codebook に対する codebook インデックス（入力の量子化された離散表現）。
- **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
```