# Higgs Audio V2 Tokenizer

## Aperçu

- Basse fréquence d'images : à 25 images par seconde, notre tokenizer divise par deux la fréquence d'images de nombreuses références tout en maintenant une haute qualité audio.
- Entraînement unifié à 24 kHz : nous mélangeons des extraits de parole, de musique et d'événements sonores dans un seul modèle, capturant à la fois les détails sémantiques et acoustiques, ce qui facilite considérablement l'entraînement des modèles de langage audio.
- Inférence rapide : en évitant les étapes de diffusion, notre encodeur/décodeur traite les lots rapidement, ce qui le rend pratique pour les tâches en temps réel ou à grande échelle.

**Architecture du modèle :**

    

## Utilisation

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

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

**Paramètres :**

target_bandwidths (`List[float]`, *facultatif*, par défaut `[0.5, 1, 1.5, 2]`) : La plage des différentes largeurs de bande (en kbps) avec lesquelles le modèle peut encoder l'audio.

sample_rate (`int`, *facultatif*, valeur par défaut `24000`) : Le taux d'échantillonnage auquel les fichiers audio doivent être numérisés, exprimé en hertz (Hz).

kernel_size (`int`, *facultatif*, valeur par défaut : 3) : Taille du noyau pour la convolution sémantique initiale.

channel_ratios (`List[float]`, *facultatif*, par défaut `[1, 1]`) : Facteurs d'expansion pour le nombre de canaux de sortie dans chaque bloc sémantique.

strides (`List[int]`, *facultatif*, par défaut `[1, 1]`) : Pas pour chaque bloc d'encodeur sémantique.

block_dilations (`List[int]`, *facultatif*, valeur par défaut `[1, 1]`) : Facteurs de dilatation pour les unités résiduelles dans les blocs sémantiques.

unit_kernel_size (`int`, *facultatif*, valeur par défaut : 3) : Taille du noyau à l'intérieur de chaque ResidualUnit des blocs sémantiques.

codebook_size (`int`, *facultatif*, valeur par défaut `1024`) : Le nombre de codebooks parallèles utilisés par le modèle.

codebook_dim (`int`, *facultatif*, valeur par défaut `64`) : Dimension de chaque vecteur d'embedding du codebook.

initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

acoustic_model_config (`Union[Dict, AutoConfig]`, *facultatif*) : Une instance de la configuration du modèle acoustique (DAC).

semantic_model_config (`Union[Dict, AutoConfig]`, *facultatif*) : Une instance de l'objet de configuration pour le modèle sémantique (HuBERT).

semantic_sample_rate (`int`, *facultatif*, valeur par défaut 16000) : Fréquence d'échantillonnage à laquelle le modèle sémantique s'attend à recevoir l'entrée audio, en hertz (Hz).

downsample_factor (`int`, *facultatif*, valeur par défaut 320) : Facteur de sous-échantillonnage pour les caractéristiques sémantiques.

Il s'agit de la classe de configuration destinée à stocker la configuration d'un HiggsAudioV2TokenizerModel. Elle est utilisée pour instancier un modèle Higgs Audio V2 Tokenizer en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [bosonai/higgs-audio-v2-tokenizer](https://huggingface.co/bosonai/higgs-audio-v2-tokenizer)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

config ([HiggsAudioV2TokenizerConfig](/docs/transformers/v5.23.0/fr/model_doc/higgs_audio_v2_tokenizer#transformers.HiggsAudioV2TokenizerConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Le modèle de codec audio neuronal HiggsAudioV2Tokenizer.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

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

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

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

**Paramètres :**

audio_codes (`torch.LongTensor` de forme `(batch_size, num_quantizers, codes_length)`) : Indices de codes discrets calculés à l'aide de `model.encode`.

return_dict (`bool`, *facultatif*) : Indique s'il faut ou non retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput)

**Retourne :**

Valeurs audio décodées de forme `(batch_size, channels, num_samples)` obtenues à l'aide de la partie décodeur de HiggsAudioV2Tokenizer.

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

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

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

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, channels, num_samples)`) : Valeurs flottantes de la forme d'onde audio d'entrée.

bandwidth (`float`, *facultatif*) : La bande passante cible en (kbps) n'accepte que les valeurs définies dans `config.target_bandwidths`. Par défaut, la bande passante maximale disponible, soit `4.0` kbps, est utilisée.

return_dict (`bool`, *facultatif*) : Indique s'il faut renvoyer un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) ou non.

**Retourne :**

`torch.LongTensor` de forme `(batch_size, num_quantizers, codes_length)` contenant les codes audio encodés discrets.

#### 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'>)
```

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

**Paramètres :**

input_values (`torch.Tensor` de forme `(batch_size, channels, num_samples)`) : Les valeurs flottantes brutes de la forme d'onde audio d'entrée.

audio_codes (`torch.LongTensor` de forme `(batch_size, num_quantizers, codes_length)` : indices de codes discrets calculés à l'aide de `model.encode`.

bandwidth (`float`, *facultatif*) : Bande passante cible en kbps. Doit être l'une des valeurs de `config.target_bandwidths`. Par défaut, la bande passante disponible la plus élevée est utilisée.

bandwidth (`float`, *facultatif*) : Bande passante cible en kbps. Doit être l'une des valeurs de `config.target_bandwidths`. Par défaut, la bande passante disponible la plus élevée est utilisée.

**Retourne :** `HiggsAudioV2TokenizerOutput` ou tuple `(audio_codes, audio_values)`

- `audio_codes` de forme `(batch_size, num_quantizers, codes_length)` : les codes discrets quantifiés.
- `audio_values` de forme `(batch_size, channels, num_samples)` : la forme d’onde audio reconstruite à partir des codes.

La méthode forward du modèle [HiggsAudioV2TokenizerModel](/docs/transformers/v5.23.0/fr/model_doc/higgs_audio_v2_tokenizer#transformers.HiggsAudioV2TokenizerModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

Exemple :

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

