# Higgs Audio V2 Tokenizer

## 概要

- 低フレームレート: 25 fps において、当社のトークナイザーは、高い音質を維持しながら、多くのベースラインのフレームレートを半分にします。
- 24 kHzでの統一トレーニング: 音声、音楽、サウンドイベントのクリップを1つのモデルで混合し、意味的な詳細と音響的な詳細の両方を捉えることで、オーディオ言語モデルのトレーニングを大幅に促進します。
- 高速推論:拡散ステップを回避することで、エンコーダー/デコーダーはバッチを高速に処理でき、リアルタイムや大規模なタスクに実用的になります。

**モデルアーキテクチャ:**

    

## 使用方法

```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/main/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`、*optional*、デフォルトは`24000`) : 音声ファイルをデジタル化するためのサンプリングレート（ヘルツ (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`, *任意*, デフォルトは `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`, *optional*, デフォルトは 16000) : セマンティックモデルが音声入力を想定するサンプリングレート (Hz)。

downsample_factor (`int`、*optional*、デフォルト値は 320) : セマンティック特徴のダウンサンプリング係数。

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

設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/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/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L456)

**パラメータ:**

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

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

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

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

[ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L564)

**パラメータ:**

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) を返すかどうか

**戻り値:**

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

#### encode[[transformers.HiggsAudioV2TokenizerModel.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/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L512)

**パラメータ:**

input_values (`torch.Tensor`、形状 `(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.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/main/src/transformers/models/higgs_audio_v2_tokenizer/modeling_higgs_audio_v2_tokenizer.py#L592)

**パラメータ:**

input_values (`torch.Tensor`、形状 `(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` のいずれかの値である必要があります。デフォルトでは、利用可能な最大の帯域幅が使用されます。

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

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

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

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`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
```