# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) est un modèle de génération musicale qui produit des chansons complètes d'une durée maximale de cinq minutes à partir de paroles et d'une description musicale, avec des voix expressives et une structure à long terme.

Le modèle est un hybride d'une étape autorégressive et d'une étape de diffusion : un modèle de langage global de 8B basé sur Qwen3 prédit un jeton audio sémantique par image, tandis qu'un petit décodeur de profondeur remplit sept codebooks résiduels RVQ, et leurs états cachés fusionnés conditionnent un transformateur de correspondance de flux de 2,4B qui produit des latents Flow-VAE dans des blocs superposés. Un décodeur de type DAC convertit les latents en audio stéréo à 44,1 kHz.

## Utilisation

MiniMax Music 3 est disponible sous forme de pipeline modulaire.

```py
import soundfile as sf
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-Music3")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

lyrics = """[verse]
Morning light filtering through the pine
Every quiet street is yours and mine
[chorus]
Softly the world begins to breathe"""

prompt = (
    "Genre: acoustic pop. BPM: 96. Key: C major. Warm and intimate, building gently into the chorus. "
    "Vocals: soft female lead, close and breathy, light stacked harmonies in the chorus. "
    "Arrangement: fingerpicked guitar and soft piano; brushed drums and upright bass enter in the chorus."
)

audio = pipe(
    prompt=prompt,
    lyrics=lyrics,
    audio_duration=60.0,
    generator=torch.Generator("cuda").manual_seed(7),
    output="audios",
)[0]

sf.write("minimax_music3.wav", audio.T, pipe.sampling_rate)
```

## Réduire l'utilisation de la mémoire

Reportez-vous au guide [Réduire l'utilisation de la mémoire](../../optimization/memory) pour plus de détails sur les différentes techniques d'économie de mémoire.

Le pipeline complet nécessite environ 23 Go de VRAM en bfloat16. Avec le déchargement automatique sur CPU, une génération s'exécute avec environ 22 Go de VRAM libre, et le déchargement par groupe du modèle de langage permet de tenir dans 8 Go.

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.hooks.group_offloading import apply_group_offloading

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-Music3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

# Only needed below ~22 GB of free VRAM — slower, but fits in 8 GB.
apply_group_offloading(
    pipe.language_model, onload_device=torch.device("cuda"), offload_type="leaf_level", use_stream=True
)
```

## Astuces

- Les balises de structure telles que `[intro]`, `[verse]`, `[pre-chorus]`, `[chorus]`, `[bridge]`, `[instrumental]`, `[solo]` et `[outro]` doivent chacune être placées sur leur propre ligne dans `lyrics`. Le texte situé sur la même ligne qu'une balise initiale est ignoré par le contrat d'entrée du modèle.
- La description musicale contrôle les voix : décrivez explicitement le genre et le timbre vocal (par exemple « voix féminine chaleureuse »), sinon le modèle peut dériver vers un rendu instrumental. Pour un contrôle fin, structurez la description en métadonnées globales (genre, BPM, tonalité, progression émotionnelle), détails vocaux et arrangement.
- `audio_duration` est une limite supérieure — le modèle de langage peut terminer la chanson plus tôt avec un jeton d’arrêt. L’étape autorégressive génère 25 images par seconde d’audio et domine le temps d’exécution.
- L'échelle de guidage sans classifieur de l'étape de flow-matching est un paramètre de guider (la valeur de référence pour l'inférence est 1,7) : remplacez-le par `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))`.
- Le pipeline renvoie la sortie stéréo native du vocodeur à 44,1 kHz. Le serveur de référence effectue en outre un rééchantillonnage à 32 kHz ; appliquez votre propre rééchantillonnage si vous avez besoin de cette fréquence exacte.

## MiniMaxMusic3ModularPipeline[[diffusers.MiniMaxMusic3ModularPipeline]]

#### diffusers.MiniMaxMusic3ModularPipeline[[diffusers.MiniMaxMusic3ModularPipeline]]

```python
diffusers.MiniMaxMusic3ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_music3/modular_pipeline.py#L22)

Un ModularPipeline pour la génération de musique conditionnée par des paroles et des légendes avec MiniMax Music 3.

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

#### diffusers.MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

```python
diffusers.MiniMaxMusic3Blocks()
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_music3/modular_blocks_minimax_music3.py#L130)

Pipeline modulaire pour la génération de musique conditionnée par des paroles et des légendes à l'aide de MiniMax Music 3. Un modèle de langage autoregressive Qwen3 génère des codes sémantiques par image et des états cachés à partir des paroles et de la description musicale ; un transformer flow-matching transforme les états cachés en latents Flow-VAE par blocs ; et un vocoder de type DAC les décode en une forme d'onde stéréo à 44,1 kHz.

Composants : tokenizer (`Qwen2Tokenizer`) language_model (`Qwen3ForCausalLM`) rvq_depth_decoder (`MiniMaxMusic3RVQDepthDecoder`) condition_encoder (`MiniMaxMusic3ConditionEncoder`) transformer (`MiniMaxMusic3Transformer1DModel`) scheduler (`FlowMatchEulerDiscreteScheduler`) guider (`ClassifierFreeGuidance`) vocoder (`MiniMaxMusic3Vocoder`)

Entrées : prompt (`str`) : La description de la musique (genre, ambiance, voix, instrumentation, arrangement). lyrics (`str`) : Les paroles à chanter. Les balises de structure telles que `[verse]` ou `[chorus]` doivent chacune être sur leur propre ligne ; le texte sur la même ligne qu'une balise initiale est ignoré par le contrat d'entrée du point de contrôle. audio_duration (`float`, *facultatif*, valeur par défaut 60.0) : Limite supérieure de la durée de l'audio généré, en secondes. Le modèle de langage peut s'arrêter plus tôt. Plafonné à 9000 images (six minutes). generator (`Generator`, *facultatif*) : Générateur Torch pour une génération déterministe. num_inference_steps (`int`, *facultatif*, valeur par défaut 30) : Nombre d'étapes d'Euler de flow-matching par bloc. output_type (`str`, *facultatif*, valeur par défaut np) : Format de sortie : 'np' ou 'pt'.

Sorties : audios (`Tensor | ndarray`) : la forme d'onde stéréo générée de forme `(batch, channels, samples)` dans `[-1, 1]`.

## MiniMaxMusic3ConditionEncoder[[diffusers.MiniMaxMusic3ConditionEncoder]]

#### diffusers.MiniMaxMusic3ConditionEncoder[[diffusers.MiniMaxMusic3ConditionEncoder]]

```python
diffusers.MiniMaxMusic3ConditionEncoder(condition_hidden_dim: int = 4096, num_condition_layers: int = 8, out_dim: int = 2048, input_sampling_rate: int = 24000, input_hop_length: int = 960, output_sampling_rate: int = 44100, output_hop_length: int = 512)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_minimax_music3.py#L23)

Projette les états cachés par image de l'étape autorégressive sur la chronologie latente du Flow-VAE.

Chaque image générée porte `num_condition_layers` états cachés de taille `condition_hidden_dim` (un provenant du modèle de langage et un par étape de codebook résiduel). Ils sont mélangés avec des poids softmax appris, projetés, puis rééchantillonnés du taux d’images du modèle de langage au taux d’images latent par interpolation au plus proche voisin.

#### forward[[diffusers.MiniMaxMusic3ConditionEncoder.forward]]

```python
forward(hidden_states: Tensor)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_minimax_music3.py#L48)

**Paramètres :**

hidden_states (`torch.Tensor` de forme `(batch, frames, num_condition_layers * condition_hidden_dim)`) : États cachés par image concaténés issus de l'étape autorégressive.

**Retourne :** `torch.Tensor` de forme `(batch, latent_length, out_dim)`

la séquence de conditionnement alignée sur les latents.

## MiniMaxMusic3RVQDepthDecoder[[diffusers.MiniMaxMusic3RVQDepthDecoder]]

#### diffusers.MiniMaxMusic3RVQDepthDecoder[[diffusers.MiniMaxMusic3RVQDepthDecoder]]

```python
diffusers.MiniMaxMusic3RVQDepthDecoder(hidden_size: int = 4096, num_layers: int = 4, num_attention_heads: int = 16, intermediate_size: int = 6144, audio_vocab_size: int = 1024, num_codebooks: int = 8, max_position_embeddings: int = 16)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/minimax_music3_rvq_depth_decoder.py#L91)

Le modèle de langage local de MiniMax Music 3. Au sein de chaque trame audio, il prédit de manière autorégressive les sept codebooks RVQ résiduels (c1..c7) à partir de l'état caché du modèle de langage global et du code sémantique de la trame, et expose les états cachés par étape qui conditionnent le transformateur de flow-matching.

Il possède également la table d'incorporation pour les codebooks résiduels, que le pipeline utilise pour incorporer des images complètes dans la boucle de rétroaction du modèle de langage global.

#### forward[[diffusers.MiniMaxMusic3RVQDepthDecoder.forward]]

```python
forward(inputs_embeds: Tensor)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/minimax_music3_rvq_depth_decoder.py#L127)

**Paramètres :**

inputs_embeds (`torch.Tensor` de forme `(batch, steps, hidden_size)`) : Embeddings de séquences de profondeur projetés : l'état caché global suivi des codes intégrés échantillonnés jusqu'à présent, chacun passé à travers `projection`.

**Retourne :** `torch.Tensor` de forme `(batch, steps, hidden_size)`

états cachés normalisés ; la dernière étape alimente la tête de codebook suivante.

## MiniMaxMusic3Vocoder[[diffusers.MiniMaxMusic3Vocoder]]

#### diffusers.MiniMaxMusic3Vocoder[[diffusers.MiniMaxMusic3Vocoder]]

```python
diffusers.MiniMaxMusic3Vocoder(latent_channels: int = 128, decoder_input_dim: int = 1024, decoder_hidden_dim: int = 1536, upsampling_ratios: tuple = (8, 8, 4, 2), sampling_rate: int = 44100)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/minimax_music3_vocoder.py#L71)

Le décodeur d'ondes Flow-VAE de MiniMax Music 3 (un décodeur de type DAC). Il décode des latents appariés par flux de forme `(batch, latent_channels, length)` en ondes stéréo à `sampling_rate` ; les deux canaux audio sont décodés en tant que deux flux pliés de `latent_channels // 2`.

#### forward[[diffusers.MiniMaxMusic3Vocoder.forward]]

```python
forward(latents: Tensor)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/minimax_music3_vocoder.py#L100)

**Paramètres :**

latents (`torch.Tensor` de forme `(batch, latent_channels, length)`) : Latents du Flow-VAE apparié par flux (flow-matched).

**Retourne :** `torch.Tensor` de forme `(batch, 2, samples)`

la forme d'onde stéréo dans `[-1, 1]`.