# Higgs Audio V2 Tokenizer

## 개요

- 낮은 프레임 레이트: 25 fps에서, 우리의 토크나이저는 높은 오디오 품질을 유지하면서 많은 베이스라인의 프레임 레이트를 절반으로 줄입니다.
- 통합 24 kHz 학습: 음성, 음악, 사운드 이벤트 클립을 하나의 모델에 혼합하여 학습함으로써 의미론적 및 음향적 세부 사항을 모두 포착하며, 이를 통해 오디오 언어 모델의 학습을 크게 촉진합니다.
- 빠른 추론: diffusion steps를 피함으로써, 우리의 encoder/decoder가 배치(batch)를 빠르게 처리하여 실시간 또는 대규모 작업에 실용적으로 사용할 수 있습니다.

**모델 아키텍처:**

    

## 사용

```python
from datasets import Audio, load_dataset

from transformers import AutoFeatureExtractor, HiggsAudioV2TokenizerModel

# load model and feature extractor
model_id = "eustlb/higgs-audio-v2-tokenizer"
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
model = HiggsAudioV2TokenizerModel.from_pretrained(model_id, device_map="auto")

# load audio sample
dummy_dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
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
```

## HiggsAudioV2TokenizerConfig[[transformers.HiggsAudioV2TokenizerConfig]]

#### transformers.HiggsAudioV2TokenizerConfig[[transformers.HiggsAudioV2TokenizerConfig]]

```python
transformers.HiggsAudioV2TokenizerConfig(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 = 24000, 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 = 64, 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, semantic_sample_rate: int = 16000, downsample_factor: int = 320)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/higgs_audio_v2_tokenizer/configuration_higgs_audio_v2_tokenizer.py#L34)

**매개변수:**

target_bandwidths (`List[float]`, *선택 사항*, 기본값 `[0.5, 1, 1.5, 2]`) : 모델이 오디오를 인코딩할 수 있는 다양한 대역폭(kbps) 범위입니다.

sample_rate (`int`, *선택 사항*, 기본값 `24000`) : 오디오 파일을 디지털화할 때 사용할 샘플링 레이트를 헤르츠(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`, *선택 사항*, 기본값 `64`) : 각 코드북 임베딩 벡터의 차원.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

acoustic_model_config (`Union[Dict, AutoConfig]`, *선택*) : 음향(DAC) 모델의 구성 설정 인스턴스입니다.

semantic_model_config (`Union[Dict, AutoConfig]`, *선택*) : 시맨틱(HuBERT) 모델의 구성 객체 인스턴스입니다.

semantic_sample_rate (`int`, *선택 사항*, 기본값 16000) : 의미 모델이 오디오 입력을 기대하는 샘플링 주파수입니다. 단위는 헤르츠(Hz)입니다.

downsample_factor (`int`, *선택 사항*, 기본값 320) : 의미론적 특징의 다운샘플링 계수입니다.

이것은 HiggsAudioV2TokenizerModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Higgs Audio V2 Tokenizer 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 [bosonai/higgs-audio-v2-tokenizer](https://huggingface.co/bosonai/higgs-audio-v2-tokenizer)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

예:

```python
>>> from transformers import HiggsAudioV2TokenizerModel, HiggsAudioV2TokenizerConfig

>>> # Initializing configuration
>>> configuration = HiggsAudioV2TokenizerConfig()

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

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

## HiggsAudioV2TokenizerModel[[transformers.HiggsAudioV2TokenizerModel]]

#### transformers.HiggsAudioV2TokenizerModel[[transformers.HiggsAudioV2TokenizerModel]]

```python
transformers.HiggsAudioV2TokenizerModel(config: HiggsAudioV2TokenizerConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L456)

**매개변수:**

config ([HiggsAudioV2TokenizerConfig](/docs/transformers/v5.23.0/ko/model_doc/higgs_audio_v2_tokenizer#transformers.HiggsAudioV2TokenizerConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

HiggsAudioV2Tokenizer 신경 오디오 코덱 모델입니다.

이 모델은 [PreTrainedModel](/docs/transformers/v5.23.0/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.HiggsAudioV2TokenizerModel.decode]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L564)

**매개변수:**

audio_codes (`torch.LongTensor`, shape `(batch_size, num_quantizers, codes_length)`) : `model.encode`를 사용하여 계산된 이산 코드 인덱스.

return_dict (`bool`, *선택 사항*) : [ModelOutput](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부

**반환값:**

HiggsAudioV2Tokenizer의 디코더 부분을 사용하여 얻은 `(batch_size, channels, num_samples)` 형태의 디코딩된 오디오 값입니다.

#### encode[[transformers.HiggsAudioV2TokenizerModel.encode]]

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

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L512)

**매개변수:**

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/v5.23.0/ko/main_classes/output#transformers.utils.ModelOutput)를 반환할지 여부.

**반환값:**

`torch.LongTensor` 형식의 `(batch_size, num_quantizers, codes_length)` 차원 텐서로, 이산 인코딩된 오디오 코드를 포함합니다.

#### forward[[transformers.HiggsAudioV2TokenizerModel.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/v5.23.0/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L592)

**매개변수:**

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` 중 하나여야 합니다. 기본값은 사용 가능한 가장 높은 대역폭입니다.

**반환값:** `HiggsAudioV2TokenizerOutput` 또는 튜플 `(audio_codes, audio_values)`

- `audio_codes`: `(batch_size, num_quantizers, codes_length)` 모양의 양자화된 이산 코드.
- `audio_values`의 shape이 `(batch_size, channels, num_samples)`인 재구성된 오디오 웨이브폼입니다.

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

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

예:

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

>>> model_id = "hf-audio/higgs_audio_v2_tokenizer-hubert-librispeech"
>>> model = HiggsAudioV2TokenizerModel.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
```