# X-Codec

## 概要

X-Codecモデルは、Zhen Ye、Peiwen Sun、Jiahe Lei、Hongzhan Lin、Xu Tan、Zheqi Dai、Qiuqiang Kong、Jianyi Chen、Jiahao Pan、Qifeng Liu、Yike Guo、Wei Xue による [Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model](https://huggingface.co/papers/2408.17175) で提案されました。

X-Codecモデルは、自己教師ありモデル（例：HuBERT）からの意味情報と従来の音響情報を統合したニューラルオーディオコーデックです。これにより、以下が可能になります。

- **音楽の継続生成**: 音楽的意味のモデリングが向上することで、より一貫性のある継続生成が可能になります。
- **テキストからサウンドを合成**: X-Codec は、テキストプロンプトと生成されたオーディオの間の意味的な整合性を捉えます。
- **セマンティック認識型オーディオトークナイズ**: X-Codec は、YuE の歌詞から楽曲を生成するモデルにおいて、オーディオトークナイザーとして使用されています。

この論文の要旨には、次のように記載されています。

*音声生成における最近の進歩は、大規模言語モデル（LLM）の能力によって大きく後押しされてきました。既存の音声LLMに関する研究は、主に音声言語モデルのアーキテクチャと規模の向上、およびより大規模なデータセットの活用に取り組んできおり、一般的にはEnCodecのような音響コーデックが音声のトークン化に使用されています。しかし、これらのコーデックは元々音声圧縮のために設計されており、音声LLMの文脈では最適でないパフォーマンスにつながる可能性があります。本研究では、現在の音声LLMコーデックの欠点、特に生成された音声における意味的一貫性の維持に関する課題に対処することを目的としています。例えば、VALL-Eのような既存の方法は、テキストの文字起こしを条件として音響トークンの生成を行うため、音響トークンの意味的誤解釈により、内容の不正確さや単語誤り率（WER）の上昇、すなわち単語のスキップや誤りが生じることがよくあります。これらの問題を克服するために、X-Codecと呼ばれるシンプルかつ効果的なアプローチを提案します。X-Codecは、Residual Vector Quantization（RVQ）ステージの前に事前学習された意味エンコーダーの意味的特徴を取り入れ、RVQの後に意味再構成損失を導入します。コーデックの意味的処理能力を強化することで、X-Codecは音声合成タスクにおけるWERを大幅に削減し、音楽やサウンド生成を含む非音声アプリケーションにもこれらの利点を拡張します。テキストから音声への変換、音楽の継続生成、テキストからサウンドへの変換タスクにおける実験により、意味情報の統合が音声生成における言語モデルの全体パフォーマンスを大幅に向上させることが示されました。*

モデルカード:

- [xcodec-hubert-librispeech](https://huggingface.co/hf-audio/xcodec-hubert-librispeech)（音声用）
- [xcodec-wavlm-mls](https://huggingface.co/hf-audio/xcodec-wavlm-mls)(音声用)
- [xcodec-wavlm-more-data](https://huggingface.co/hf-audio/xcodec-wavlm-more-data)（音声用）
- [xcodec-hubert-general](https://huggingface.co/hf-audio/xcodec-hubert-general)（一般的な音声用）
- [xcodec-hubert-general-balanced](https://huggingface.co/hf-audio/xcodec-hubert-general-balanced)（一般的な音声向け）

このモデルは [Manal El Aidouni](https://huggingface.co/Manel) によって提供されました。元のコードは [こちら](https://github.com/zhenye234/xcodec) で、5つの異なるモデルの元のチェックポイントは [こちら](https://github.com/zhenye234/xcodec?tab=readme-ov-file#available-models) で確認できます。

デモはこの[ページ](https://x-codec-audio.github.io/)で確認できます。

## 使用例

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

```python
from datasets import Audio, load_dataset

from transformers import AutoFeatureExtractor, XcodecModel

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

# load model and feature extractor
model_id = "hf-audio/xcodec-hubert-librispeech"
model = XcodecModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

# load audio sample
dummy_dataset = dummy_dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audio_sample = dummy_dataset[-1]["audio"]["array"]
inputs = feature_extractor(raw_audio=audio_sample, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(model.device)

# encode and decode
encoder_outputs = model.encode(inputs["input_values"])
decoder_outputs = model.decode(encoder_outputs.audio_codes)
audio_values = decoder_outputs.audio_values

# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_values
```

元の音声と再構成された音声を聴くには、以下のスニペットを実行し、生成された`original.wav`と`reconstruction.wav`ファイルを音楽プレーヤーで開いて比較してください。

```python
import soundfile as sf

original = audio_sample
reconstruction = audio_values[0].cpu().detach().numpy()
sampling_rate = feature_extractor.sampling_rate

sf.write("original.wav", original, sampling_rate)
sf.write("reconstruction.wav", reconstruction.T, sampling_rate)
```

## XcodecConfig[[transformers.XcodecConfig]]

#### transformers.XcodecConfig[[transformers.XcodecConfig]]

```python
transformers.XcodecConfig(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[int | float] | tuple[int | float, ...] = (0.5, 1, 1.5, 2, 4), sample_rate: int = 16000, kernel_size: int = 3, channel_ratios: list[int] | tuple[int, ...] = (1, 1), strides: list[int] | tuple[int, ...] = (1, 1), block_dilations: list[int] | tuple[int, ...] = (1, 1), unit_kernel_size: int = 3, codebook_size: int = 1024, codebook_dim: int | None = None, initializer_range: float = 0.02, acoustic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, semantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/configuration_xcodec.py#L28)

**パラメータ:**

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

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

kernel_size (`int`、*任意*、デフォルトは`3`) : 畳み込みカーネルのサイズ。

channel_ratios (`List[float]`、*任意*、デフォルトは `[1, 1]`) : 各セマンティックブロックにおける出力チャネル数の拡張係数。

strides (`List[int]`、*任意*、デフォルトは`[1, 1]`) : 各セマンティックエンコーダーブロックのストライド。

block_dilations (`List[int]`、*任意*、デフォルトは`[1, 1]`) : セマンティックブロック内の残差ユニットのディレイション係数。

unit_kernel_size (`int`、*任意*、デフォルトは 3) : セマンティックブロック内の各 ResidualUnit におけるカーネルサイズ。

codebook_size (`int`、*任意*、デフォルトは `1024`) : モデルが使用する並列コードブックの数。

codebook_dim (`int`, *任意*) : 各コードブック埋め込みベクトルの次元数。

initializer_range (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

acoustic_model_config (`Union[Dict, DacConfig]`, *任意*) : 音響（DAC）モデルの設定のインスタンス。

semantic_model_config (`Union[Dict, HubertConfig, WavLMConfig]`, *optional*) : セマンティック（HuBERT）モデルの設定オブジェクトのインスタンス。

This is the configuration class to store the configuration of a XcodecModel. It is used to instantiate a Xcodec model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the [Manel/X-Codec](https://huggingface.co/Manel/X-Codec)

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

例:

```python
>>> from transformers import XcodecModel, XcodecConfig

>>> # Initializing configuration
>>> configuration = XcodecConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = XcodecModel(configuration)

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

## XcodecModel[[transformers.XcodecModel]]

#### transformers.XcodecModel[[transformers.XcodecModel]]

```python
transformers.XcodecModel(config: XcodecConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L445)

**パラメータ:**

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

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

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

```python
decode(audio_codes: Tensor, return_dict: bool | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L541)

**パラメータ:**

audio_codes (`torch.LongTensor`、形状 `(batch_size, num_quantizers, codes_length)`) : `model.encode` を使用して計算された離散コードのインデックス。

return_dict (`bool`, *任意*) : [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput) を返すかどうか

**戻り値:**

Xcodec のデコーダー部分を使用して取得した、形状が `(batch_size, channels, num_samples)` のデコード済みオーディオ値です。

#### encode[[transformers.XcodecModel.encode]]

```python
encode(input_values: Tensor, bandwidth: float | None = None, return_dict: bool | None = None)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L489)

**パラメータ:**

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

bandwidth (`float`, *任意*) : 目標帯域幅 (kbps) です。`config.target_bandwidths` に含まれる値のみサポートされます。デフォルトでは、利用可能な最高帯域幅である `4.0` kbps が使用されます。

return_dict (`bool`, *任意*) : [ModelOutput](/docs/transformers/main/ja/main_classes/output#transformers.utils.ModelOutput)を返すかどうか。

**戻り値:**

`torch.LongTensor` 型で、形状が `(batch_size, num_quantizers, codes_length)` の、離散化されたエンコード済みオーディオコードを含むテンソル。

#### forward[[transformers.XcodecModel.forward]]

```python
forward(input_values: Tensor, audio_codes: typing.Optional[torch.Tensor] = None, bandwidth: float | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/xcodec/modeling_xcodec.py#L569)

**パラメータ:**

input_values (`torch.FloatTensor`、shape `(batch_size, channels, num_samples)`) : 入力音声波形の生の浮動小数点値。

audio_codes (`torch.LongTensor`、形状 `(batch_size, num_quantizers, codes_length)` : `model.encode` を使用して計算された離散コードのインデックス。

bandwidth (`float`, *任意*) : kbps 単位のターゲット帯域幅。`config.target_bandwidths` のいずれかの値である必要があります。デフォルトでは、利用可能な最大の帯域幅が使用されます。

bandwidth (`float`, *任意*) : kbps 単位のターゲット帯域幅。`config.target_bandwidths` のいずれかの値である必要があります。デフォルトでは、利用可能な最大の帯域幅が使用されます。

**戻り値:** `XcodecOutput` またはタプル `(audio_codes, audio_values)`

- `audio_codes`: 量子化された離散コード。形状は `(batch_size, num_quantizers, codes_length)` です。
- `audio_values`、形状 `(batch_size, channels, num_samples)`: コードから再構成されたオーディオ波形。

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

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

例:

```python
>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, XcodecModel

>>> model_id = "hf-audio/xcodec-hubert-librispeech"
>>> model = XcodecModel.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
>>> audio_sample = dataset[0]['audio']['array']

>>> inputs = feature_extractor(raw_audio=audio_sample, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values
```