# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) es un modelo de generación de música que produce canciones completas de hasta cinco minutos a partir de letras y una descripción musical, con voces expresivas y estructura de largo alcance.

El modelo es un híbrido de una etapa autoregresiva y una etapa de difusión: un modelo de lenguaje global basado en Qwen3 de 8B predice un token semántico de audio por cuadro, mientras que un decodificador de profundidad pequeño completa siete libros de códigos RVQ residuales, y sus estados ocultos fusionados condicionan un transformer de flow-matching de 2.4B que produce latentes de Flow-VAE en fragmentos superpuestos. Un decodificador de estilo DAC convierte los latentes en audio estéreo de 44.1 kHz.

## Uso

MiniMax Music 3 está disponible como un pipeline modular.

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

## Reducir el uso de memoria

Consulte la guía [Reduce memory usage](../../optimization/memory) para obtener más detalles sobre las diversas técnicas de ahorro de memoria.

El pipeline completo requiere ~23 GB de VRAM en bfloat16. Con el descargado automático a CPU, una generación se ejecuta en ~22 GB de VRAM libre, y además, el descargado por grupos del modelo de lenguaje cabe en 8 GB.

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

## Consejos

- Las etiquetas de estructura, como `[intro]`, `[verse]`, `[pre-chorus]`, `[chorus]`, `[bridge]`, `[instrumental]`, `[solo]` y `[outro]`, deben ir cada una en su propia línea dentro de `lyrics`. El texto que aparezca en la misma línea que una etiqueta inicial se descarta según el contrato de entrada del modelo.
- La descripción de la música controla las voces: describe explícitamente el género y el timbre vocal (p. ej., "voz femenina cálida") o el modelo podría derivar hacia una pieza instrumental. Para un control más detallado, estructura la descripción en metadatos globales (género, BPM, tonalidad, progresión emocional), detalles vocales y arreglo.
- `audio_duration` es un límite superior: el modelo de lenguaje puede terminar la canción antes mediante un token de parada. La etapa autoregresiva genera 25 fotogramas por segundo de audio y domina el tiempo de ejecución.
- La escala de guía sin clasificador de la etapa de flow-matching es una configuración de guider (el valor de referencia para la inferencia es 1.7): cámbiala con `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))`.
- El pipeline devuelve la salida estéreo nativa de 44,1 kHz del vocoder. El servidor de referencia, además, realiza una re-muestreo a 32 kHz; aplique su propio re-muestreo si necesita esa tasa exacta.

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

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

Un ModularPipeline para la generación de música condicionada por letras y descripciones con MiniMax Music 3.

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

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

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

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

Pipeline modular para la generación de música condicionada por letras y descripciones, que utiliza MiniMax Music 3. Un modelo de lenguaje autoregresivo Qwen3 genera códigos semánticos por cuadro y estados ocultos a partir de las letras y la descripción musical; un transformer de flow-matching convierte los estados ocultos en latentes de Flow-VAE, trozo a trozo; y un vocodificador de estilo DAC los decodifica en una forma de onda estéreo a 44,1 kHz.

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

Entradas: prompt (`str`): La descripción de la música (género, estado de ánimo, voces, instrumentación, arreglo). lyrics (`str`): La letra para cantar. Las etiquetas de estructura, como `[verse]` o `[chorus]`, deben estar cada una en su propia línea; el texto en la misma línea que una etiqueta inicial se descarta según el contrato de entrada del checkpoint. audio_duration (`float`, *opcional*, valor predeterminado 60.0): Límite superior de la duración del audio generado, en segundos. El modelo de lenguaje puede detenerse antes. Limitado a 9000 fotogramas (seis minutos). generator (`Generator`, *opcional*): Generador de Torch para una generación determinista. num_inference_steps (`int`, *opcional*, valor predeterminado 30): Número de pasos de Euler de flow-matching por bloque. output_type (`str`, *opcional*, valor predeterminado np): Formato de salida: 'np' o 'pt'.

Salidas: audios (`Tensor | ndarray`): La forma de onda estéreo generada de forma `(batch, channels, samples)` en `[-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)
```

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

Proyecta los estados ocultos por marco de la etapa autoregresiva sobre la línea temporal latente de Flow-VAE.

Cada cuadro generado lleva `num_condition_layers` estados ocultos de tamaño `condition_hidden_dim` (uno del modelo de lenguaje y uno por cada paso de libro de códigos residual). Se mezclan con pesos softmax aprendidos, se proyectan y se remuestrean desde la tasa de cuadros del modelo de lenguaje a la tasa de cuadros latente mediante interpolación de vecino más cercano.

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

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

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

**Parámetros:**

hidden_states (`torch.Tensor` de forma `(batch, frames, num_condition_layers * condition_hidden_dim)`) : Estados ocultos concatenados por cuadro de la etapa autorregresiva.

**Devuelve:** `torch.Tensor` de forma `(batch, latent_length, out_dim)`

la secuencia de condicionamiento alineada con el espacio latente.

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

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

El modelo de lenguaje local de MiniMax Music 3. Dentro de cada cuadro de audio, predice de forma autoregresiva los siete libros de códigos RVQ residuales (c1..c7) a partir del estado oculto del modelo de lenguaje global y del código semántico del cuadro, y expone los estados ocultos por paso que condicionan el transformador de flow-matching.

También posee la tabla de incrustaciones para los libros de códigos residuales, que la tubería utiliza para incrustar cuadros completos para el bucle de retroalimentación del modelo de lenguaje global.

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

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

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

**Parámetros:**

inputs_embeds (`torch.Tensor` de forma `(batch, steps, hidden_size)`) : Incrustaciones de secuencias de profundidad proyectadas: el estado oculto global seguido por los códigos incrustados muestreados hasta ahora, cada uno pasado a través de `projection`.

**Devuelve:** `torch.Tensor` de forma `(batch, steps, hidden_size)`

estados ocultos normalizados; el último paso alimenta la siguiente cabeza de libro de códigos.

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

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

El decodificador de forma de onda Flow-VAE de MiniMax Music 3 (un decodificador de estilo DAC). Decodifica latentes de flujo ajustado de forma `(batch, latent_channels, length)` en formas de onda estéreo a `sampling_rate`; los dos canales de audio se decodifican como dos flujos plegados de `latent_channels // 2`.

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

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

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

**Parámetros:**

latents (`torch.Tensor` de forma `(batch, latent_channels, length)`) : Latentes de Flow-VAE con Flow-matched.

**Devuelve:** `torch.Tensor` de forma `(batch, 2, samples)`

la forma de onda estéreo en `[-1, 1]`.