# 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과 같은 음향 코덱이 음성 토큰화(audio tokenization)에 사용됩니다. 그러나 이러한 코덱은 원래 음성 압축을 위해 설계되었기 때문에 음성 LLM 컨텍스트에서 최적이지 않은 성능을 초래할 수 있습니다. 본 연구는 현재 음성 LLM 코덱의 한계를 해결하는 것을 목표로 하며, 특히 생성된 음성에서 의미적 무결성을 유지하는 데 있어 직면한 문제를 다룹니다. 예를 들어, 텍스트 전사본에 조건을 부여하여 음향 토큰 생성을 수행하는 VALL-E와 같은 기존 방법은 음향 토큰의 의미적 오해석으로 인해 콘텐츠 부정확성과 높은 단어 오류율(WER)을 겪는 경우가 많으며, 이는 단어 생략과 오류로 이어집니다. 이러한 문제를 극복하기 위해, 우리는 X-Codec이라는 단순하면서도 효과적인 접근법을 제안합니다. X-Codec은 Residual Vector Quantization(RVQ) 단계 전에 사전 학습된 의미 인코더의 의미적 특징을 통합하고, RVQ 이후에 의미 재구성 손실을 도입합니다. 코덱의 의미적 능력을 향상시킴으로써, X-Codec은 음성 합성 작업에서 WER을 현저히 줄이고 이러한 이점을 음악 및 사운드 생성을 포함한 비음성(non-speech) 응용 분야로 확장합니다. 텍스트-음성 변환, 음악 연속 생성, 텍스트-사운드 변환 작업에 대한 우리의 실험은 의미 정보를 통합하면 음성 생성에서 언어 모델의 전반적인 성능이 크게 향상됨을 보여줍니다.*

모델 카드:

- (음성을 위한) [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)에서, 다섯 가지 다른 모델의 원본 체크포인트는 [여기](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]`, *선택 사항*, 기본값 `[0.5, 1, 1.5, 2, 4]`) : 모델이 오디오를 인코딩할 수 있는 다양한 대역폭(kbps) 범위입니다.

sample_rate (`int`, *선택 사항*, 기본값 `16000`) : 오디오 파일을 디지털화할 때 사용할 샘플링 주파수입니다. 헤르츠(Hz) 단위로 표시됩니다.

kernel_size (`int`, *선택 사항*, 기본값 `3`) : 컨볼루션 커널의 크기입니다.

channel_ratios (`List[float]`, *선택 사항*, 기본값 `[1, 1]`) : 각 시맨틱 블록의 출력 채널 수에 대한 확장 계수입니다.

strides (`List[int]`, *선택 사항*, 기본값 `[1, 1]`) : 각 시맨틱 인코더 블록의 스트라이드입니다.

block_dilations (`List[int]`, *선택 사항*, 기본값 `[1, 1]`) : 시맨틱 블록의 잔차 단위(residual units)에 사용되는 팽창 계수(dilation factors)입니다.

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]`, *선택*) : 의미론적(HuBERT) 모델의 구성 객체 인스턴스입니다.

이것은 XcodecModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Xcodec 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [Manel/X-Codec](https://huggingface.co/Manel/X-Codec)의 구성과 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/main/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/main/ko/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/ko/model_doc/xcodec#transformers.XcodecConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/main/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

Xcodec 신경 오디오 코덱 모델.

이 모델은 [PreTrainedModel](/docs/transformers/main/ko/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`, shape `(batch_size, num_quantizers, codes_length)`) : `model.encode`를 사용하여 계산된 이산 코드 인덱스.

return_dict (`bool`, *선택 사항*) : [ModelOutput](/docs/transformers/main/ko/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.Tensor`, shape `(batch_size, channels, num_samples)`) : 입력 오디오 웨이브폼의 Float 값.

bandwidth (`float`, *선택 사항*) : `config.target_bandwidths`에 포함된 값만 지원하는 대상 대역폭(kbps)입니다. 기본값은 사용 가능한 가장 높은 대역폭인 `4.0` kbps입니다.

return_dict (`bool`, *선택 사항*) : [ModelOutput](/docs/transformers/main/ko/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.Tensor`, shape `(batch_size, channels, num_samples)`) : 입력 오디오 웨이브폼의 원시 float 값.

audio_codes (`torch.LongTensor`, shape `(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`의 shape이 `(batch_size, channels, num_samples)`인 재구성된 오디오 웨이브폼입니다.

[XcodecModel](/docs/transformers/main/ko/model_doc/xcodec#transformers.XcodecModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `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
```