# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) é um modelo de geração de música que produz canções completas de até cinco minutos a partir de letras e uma descrição musical, com vocais expressivos e estrutura de longo alcance.

O modelo é um híbrido de um estágio autoregressivo e um estágio de difusão: um modelo de linguagem global baseado em Qwen3 de 8B prevê um token semântico de áudio por quadro, enquanto um decodificador de profundidade pequeno preenche sete codebooks residuais RVQ, e os estados ocultos fundados deles condicionam um transformer de flow-matching de 2.4B que produz latentes Flow-VAE em blocos sobrepostos. Um decodificador estilo DAC converte os latentes em áudio estéreo de 44,1 kHz.

## Uso

MiniMax Music 3 está disponível como um 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)
```

## Reduzir o uso de memória

Consulte o guia [Reduzir o uso de memória](../../optimization/memory) para mais detalhes sobre as diversas técnicas de economia de memória.

O pipeline completo requer ~23 GB de VRAM em bfloat16. Com o offloading automático para CPU, uma geração é executada em ~22 GB de VRAM livre, e, adicionalmente, o group-offloading do modelo de linguagem cabe em 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
)
```

## Dicas

- Tags de estrutura, como `[intro]`, `[verse]`, `[pre-chorus]`, `[chorus]`, `[bridge]`, `[instrumental]`, `[solo]` e `[outro]`, devem estar cada uma em sua própria linha em `lyrics`. O texto na mesma linha que uma tag inicial é descartado pelo contrato de entrada do modelo.
- A descrição da música controla os vocais: descreva explicitamente o gênero e o timbre vocal (por exemplo, "vocal feminino quente") ou o modelo pode se desviar para uma faixa instrumental. Para um controle mais detalhado, estruture a descrição em metadados globais (gênero, BPM, tonalidade, progressão emocional), detalhes vocais e arranjo.
- `audio_duration` é um limite superior — o modelo de linguagem pode encerrar a música antes com um token de parada. O estágio autoregressivo gera 25 quadros por segundo de áudio e domina o tempo de execução.
- A escala de orientação sem classificador da etapa de correspondência de fluxo é uma configuração de guia (o valor de referência para inferência é 1,7): substitua-a por `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))`.
- O pipeline retorna a saída estéreo nativa de 44,1 kHz do vocoder. O servidor de referência também faz a reamostragem para 32 kHz; aplique sua própria reamostragem se precisar dessa taxa exata.

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

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

Uma ModularPipeline para geração de música condicionada por letras e legendas com MiniMax Music 3.

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

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

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

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

Pipeline modular para geração de música condicionada por letras e descrições usando MiniMax Music 3. Um modelo de linguagem autoregressivo Qwen3 gera códigos semânticos por quadro e estados ocultos a partir das letras e da descrição da música; um transformer de flow-matching converte os estados ocultos em latentes Flow-VAE em blocos; e um vocoder estilo DAC os decodifica em uma forma de onda estéreo a 44,1 kHz.

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

Inputs: prompt (`str`): A descrição da música (gênero, clima, vocais, instrumentação, arranjo). lyrics (`str`): A letra a ser cantada. Tags de estrutura, como `[verse]` ou `[chorus]`, devem estar cada uma em sua própria linha; o texto na mesma linha de uma tag inicial é descartado pelo contrato de entrada do checkpoint. audio_duration (`float`, *opcional*, padrão 60.0): Limite superior para a duração do áudio gerado, em segundos. O modelo de linguagem pode parar antes. Limitado a 9000 frames (seis minutos). generator (`Generator`, *opcional*): Gerador do Torch para geração determinística. num_inference_steps (`int`, *opcional*, padrão 30): Número de etapas de Euler de flow-matching por chunk. output_type (`str`, *opcional*, padrão np): Formato de saída: 'np' ou 'pt'.

Saídas: audios (`Tensor | ndarray`): A forma de onda estéreo gerada, com formato `(batch, channels, samples)` em `[-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)
```

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

Projeta os estados ocultos por quadro da etapa autoregressiva para a linha do tempo latente do Flow-VAE.

Cada quadro gerado carrega `num_condition_layers` estados ocultos de tamanho `condition_hidden_dim` (um do modelo de linguagem e um para cada etapa do codebook residual). Eles são misturados com pesos softmax aprendidos, projetados e reamostrados da taxa de quadros do modelo de linguagem para a taxa de quadros latente com interpolação de vizinho mais próximo.

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

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

[Fonte](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 quadro da etapa autoregressiva.

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

a sequência de condicionamento alinhada ao espaço 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)
```

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

O modelo de linguagem local do MiniMax Music 3. Dentro de cada quadro de áudio, ele prevê autoregressivamente os sete codebooks residuais RVQ (c1..c7) a partir do estado oculto do modelo de linguagem global e do código semântico do quadro, e expõe os estados ocultos por etapa que condicionam o transformer de flow-matching.

Ele também possui a tabela de incorporação para os livros de códigos residuais, que o pipeline usa para incorporar quadros completos para o loop de feedback do modelo de linguagem global.

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

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

[Fonte](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)`) : Embebidos de sequência de profundidade projetados: o estado oculto global seguido pelos códigos embebidos amostrados até o momento, cada um passado por `projection`.

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

estados ocultos normalizados; a última etapa alimenta a próxima cabeça de codebook.

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

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

O decodificador de forma de onda Flow-VAE do MiniMax Music 3 (um decodificador no estilo DAC). Ele decodifica latentes de fluxo compatível de forma `(batch, latent_channels, length)` em formas de onda estéreo em `sampling_rate`; os dois canais de áudio são decodificados como dois fluxos dobrados de `latent_channels // 2`.

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

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

[Fonte](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 do Flow-VAE com correspondência de fluxo (flow-matched).

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

a forma de onda estéreo em `[-1, 1]`.