# EnCodec

## 概要

EnCodecニューラルコーデックモデルは、Alexandre Défossez、Jade Copet、Gabriel Synnaeve、Yossi Adi によって [High Fidelity Neural Audio Compression](https://huggingface.co/papers/2210.13438) で提案されました。

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

*ニューラルネットワークを活用した、最先端のリアルタイムかつ高忠実度のオーディオコーデックを提案します。本コーデックは、量子化された潜在空間をエンドツーエンドで学習した、ストリーミング型のエンコーダ・デコーダアーキテクチャから構成されています。単一のマルチスケールスペクトログラム敵対的損失関数を用いることで、アーティファクトを効率的に低減し、高品質なサンプルを生成しながら、学習を簡素化かつ高速化しています。学習を安定させるための新しい損失バランサー機構を導入しました。この機構により、損失の重みが、全体の勾配に対して占めるべき割合を定義するものとなり、このハイパーパラメータの選択が損失の典型的なスケールから切り離されます。さらに、リアルタイムより速い処理速度を維持したまま、得られた表現を最大40%まで圧縮できる軽量なTransformerモデルの活用方法を検討しました。提案するモデルの主要な設計判断、すなわち学習目的、アーキテクチャの変更、および様々な知覚損失関数に関する検討について、詳細な説明を提供します。音声、ノイズ・残響の多い音声、音楽といった幅広い帯域幅とオーディオドメインを対象に、広範な主観的評価（MUSHRAテスト）とアブレーションスタディを提示します。24 kHzモノラルおよび48 kHzステレオオーディオの両方を対象としたすべての評価設定において、当社のアプローチはベースライン手法を上回ります。*

このモデルは、[Matthijs](https://huggingface.co/Matthijs)、[Patrick Von Platen](https://huggingface.co/patrickvonplaten)、[Arthur Zucker](https://huggingface.co/ArthurZ) によって提供されました。元のコードは[こちら](https://github.com/facebookresearch/encodec)で確認できます。

## 使用例

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

```python
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[[transformers.EncodecConfig]]

#### transformers.EncodecConfig[[transformers.EncodecConfig]]

```python
transformers.EncodecConfig(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, target_bandwidths: list[float] | tuple[float, ...] = (1.5, 3.0, 6.0, 12.0, 24.0), sampling_rate: int = 24000, audio_channels: int = 1, normalize: bool = False, chunk_length_s: int | float | None = None, overlap: float | None = None, hidden_size: int = 128, num_filters: int = 32, num_residual_layers: int = 1, upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2), norm_type: str = 'weight_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, num_lstm_layers: int = 2, trim_right_ratio: float = 1.0, codebook_size: int = 1024, codebook_dim: int | None = None, use_conv_shortcut: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/encodec/configuration_encodec.py#L27)

**パラメータ:**

target_bandwidths (`list[float]`、*optional*、デフォルトは`[1.5, 3.0, 6.0, 12.0, 24.0]`) : モデルが音声エンコードに使用できる異なる帯域幅の範囲です。

sampling_rate (`int`、*optional*、デフォルトは`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`、*optional*、デフォルトは 32) : 最初の`EncodecConv1d`ダウンサンプリング層の畳み込みカーネルの数。

num_residual_layers (`int`、*optional*、デフォルトは 1) : 残差層の数。

upsampling_ratios (`Sequence[int]` 、*optional*、デフォルトは`[8, 5, 4, 2]`) : カーネルサイズとストライドの比率。エンコーダーはアップサンプリング比率ではなくダウンサンプリング比率を使用するため、ここで指定した比率とは逆の順序で比率を使用します。この順序はデコーダーの順序と一致する必要があります。

norm_type (`str`、*任意*、デフォルトは `"weight_norm"`) : 正規化手法。`["weight_norm", "time_group_norm"]` のいずれかである必要があります。

kernel_size (`int`、*optional*、デフォルトは 7) : 初期畳み込みのカーネルサイズ。

last_kernel_size (`int`、*任意*、デフォルトは 7) : 最後の畳み込み層のカーネルサイズ。

residual_kernel_size (`int`、*optional*、デフォルトは 3) : 残差層のカーネルサイズ。

dilation_growth_rate (`int`、*optional*、デフォルトは 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](https://huggingface.co/facebook/encodec_24khz)と類似した設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> 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]]

#### transformers.EncodecFeatureExtractor[[transformers.EncodecFeatureExtractor]]

```python
transformers.EncodecFeatureExtractor(feature_size: int = 1, sampling_rate: int = 24000, padding_value: float = 0.0, chunk_length_s: float | None = None, overlap: float | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/encodec/feature_extraction_encodec.py#L26)

**パラメータ:**

feature_size (`int`, *optional*, デフォルトは 1) : 抽出された特徴量の次元数です。モノラルの場合は 1、ステレオの場合は 2 を指定します。

sampling_rate (`int`、*optional*、デフォルトは 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](/docs/transformers/main/ja/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。

デフォルト値でフィーチャーエクストラクターをインスタンス化すると、[facebook/encodec_24khz](https://huggingface.co/facebook/encodec_24khz)アーキテクチャと類似した設定が得られます。

#### __call__[[transformers.EncodecFeatureExtractor.__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/encodec/feature_extraction_encodec.py#L81)

**パラメータ:**

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*) : 設定されている場合、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです。 - `'pt'`: PyTorch の `torch.Tensor` オブジェクトを返します。 - `'np'`: Numpy の `np.ndarray` オブジェクトを返します。

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

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

## EncodecModel[[transformers.EncodecModel]]

#### transformers.EncodecModel[[transformers.EncodecModel]]

```python
transformers.EncodecModel(config: EncodecConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/encodec/modeling_encodec.py#L485)

**パラメータ:**

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

EnCodec ニューラルオーディオコーデックモデル。

このモデルは [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.EncodecModel.decode]]

```python
decode(audio_codes: LongTensor, audio_scales: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, last_frame_pad_length: int | None = 0)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/encodec/modeling_encodec.py#L661)

**パラメータ:**

audio_codes (`torch.LongTensor`、形状 `(nb_frames, batch_size, nb_quantizers, frame_len)`、*任意*) : `model.encode` を使用して計算された離散コード埋め込み。

audio_scales (`nb_frames` 個の長さの `torch.Tensor` のリスト、形状 `(batch_size, 1)`、*任意*) : 各 `audio_codes` 入力に対するスケーリング係数。

padding_mask (`torch.Tensor`、形状 `(channels, sequence_length)`) : `input_values`をパディングするために使用されるパディングマスク。

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

last_frame_pad_length (`int`, *任意*) : 最後のフレームのパディングの長さを表す整数。デコード時に削除されます。

与えられたフレームを出力音声波形にデコードします。

出力が入力よりやや大きくなる場合があります。その場合、末尾の余分なステップを切り捨てることもできます。

#### encode[[transformers.EncodecModel.encode]]

```python
encode(input_values: Tensor, padding_mask: typing.Optional[torch.Tensor] = None, bandwidth: float | None = None, return_dict: bool | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/encodec/modeling_encodec.py#L525)

**パラメータ:**

input_values (`torch.Tensor`、形状 `(batch_size, channels, sequence_length)`) : 入力音声波形の浮動小数点値。

padding_mask (`torch.Tensor`、形状 `(batch_size, channels, sequence_length)`) : `input_values`をパディングするために使用されるパディングマスク。

bandwidth (`float`, *任意*) : 目標帯域幅です。`config.target_bandwidths` のいずれかの値である必要があります。`None` の場合、可能な最小の帯域幅が使用されます。bandwidth は実際の値の千分の一で表されます。例えば、6kbps の帯域幅は bandwidth == 6.0 と表されます。

**戻り値:** `EncodecEncoderOutput dict or a tuple containing`

- audio_codes (`torch.LongTensor`、形状 `(nb_frames, batch_size, nb_quantizers, frame_len)`、*任意*)、
- audio_scales `nb_frames` 個の `torch.Tensor`（形状 `(batch_size, 1)`）のリスト、*任意*
- 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`は各フレームの長さであり、`ceil(input_length/self.config.hop_length)`に等しくなります。
`self.config.chunk_length=None`（例：24kHz モデルの場合）です。それ以外の場合、`self.config.chunk_length` が定義されていると、`frame_len=self.config.chunk_length/self.config.hop_length` となります。例えば、`frame_len=150` の 48kHz モデルの場合です。

#### forward[[transformers.EncodecModel.forward]]

```python
forward(input_values: Tensor, padding_mask: typing.Optional[torch.BoolTensor] = None, bandwidth: float | None = None, audio_codes: typing.Optional[torch.LongTensor] = None, audio_scales: typing.Optional[torch.Tensor] = None, return_dict: bool | None = None, last_frame_pad_length: int | None = 0)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/encodec/modeling_encodec.py#L716)

**パラメータ:**

input_values (`torch.Tensor`、形状 `(batch_size, channels, sequence_length)`、*任意*) : Float に変換され、長さ self.chunk_length のチャンクと `config.chunk_stride` のストライドでエンコードできるように適切な長さにパディングされた生オーディオ入力。

padding_mask (`torch.BoolTensor`、shape `(batch_size, channels, sequence_length)`、*任意*) : padding トークンインデックスでのスケーリング係数の計算を回避するためのマスク（これらのトークンでの conv の計算を回避できるか+）。`[0, 1]` から選択されるマスク値： - **マスクされていない**トークンは 1、- **マスクされている**トークンは 0。    `padding_mask` は、入力が切り詰められた場合や padding されていない場合を除き、常に渡す必要があります。これは、テンソルを効果的に処理するために、`input_length % stride = step`（`step = chunk_length-stride`）となるように入力オーディオを padding する必要があるためです。これにより、すべてのチャンクが同じ shape になることが保証されます

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`、*optional*) : 各 `audio_codes` 入力に対するスケーリング係数。

return_dict (`bool`, *任意*) : 出力を辞書として返すかどうか。

last_frame_pad_length (`int`, *optional*) : 最後のフレームにパディングがある場合、その長さです。エンコードされたフレームをテンソルとして出力できるようにするために使用されます。デコード時にこの値を渡すことで、エンコードされたフレームからパディングが除去されることを保証します。

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

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

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

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

- **audio_codes** (`torch.LongTensor`、形状 `(nb_frames, batch_size, nb_quantizers, frame_len)`、*任意*) -- `model.encode` を使用して計算された離散コード埋め込み。
- **audio_values** (`torch.Tensor`、形状 `(batch_size, segment_length)`、*任意*) -- Encodec のデコーダー部分を使用して取得したデコード済みオーディオ値。

例:

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