# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) adalah model generasi musik yang menghasilkan lagu utuh hingga lima menit dari lirik dan deskripsi musik, dengan vokal yang ekspresif dan struktur jangka panjang.

Model ini adalah hibrida dari tahap autoregresif dan difusi: model bahasa global berbasis Qwen3 8B memprediksi satu token audio semantik per frame, sementara decoder kedalaman kecil mengisi tujuh codebook residual RVQ, dan hidden states yang digabungkan dari keduanya mengondisikan transformer flow-matching 2.4B yang menghasilkan latents Flow-VAE dalam chunk yang tumpang tindih. Decoder bergaya DAC mengubah latents tersebut menjadi audio stereo 44,1 kHz.

## Penggunaan

MiniMax Music 3 tersedia sebagai 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)
```

## Kurangi penggunaan memori

Lihat panduan [Reduce memory usage](../../optimization/memory) untuk detail lebih lanjut tentang berbagai teknik penghematan memori.

Pipeline lengkap membutuhkan ~23 GB VRAM dalam bfloat16. Dengan offloading CPU otomatis, sebuah generasi berjalan di ~22 GB VRAM bebas, dan dengan offloading grup untuk model bahasa, muat di 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
)
```

## Tips

- Tag struktur seperti `[intro]`, `[verse]`, `[pre-chorus]`, `[chorus]`, `[bridge]`, `[instrumental]`, `[solo]`, dan `[outro]` harus masing-masing berada di baris tersendiri dalam `lyrics`. Teks yang berada di baris yang sama dengan tag pembuka akan dihapus oleh kontrak input model.
- Deskripsi musik mengontrol vokal: jelaskan gender dan timbre vokal secara eksplisit (misalnya "warm female vocal") atau model mungkin bergeser menjadi instrumental. Untuk kontrol yang lebih rinci, strukturkan deskripsi menjadi metadata global (genre, BPM, key, progresi emosional), detail vokal, dan aransemen.
- `audio_duration` adalah batas atas — model bahasa dapat mengakhiri lagu lebih awal dengan token berhenti. Tahap autoregressive menghasilkan 25 frame per detik audio dan mendominasi waktu eksekusi.
- Skala panduan tanpa klasifikator (classifier-free guidance) dari tahap flow-matching adalah pengaturan panduan (nilai inferensi acuan adalah 1,7): gantilah dengan `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))`.
- Pipeline mengembalikan output stereo 44,1 kHz asli dari vocoder. Server referensi juga melakukan resampling ke 32 kHz; terapkan resampling Anda sendiri jika Anda membutuhkan laju tersebut secara persis.

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

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

ModularPipeline untuk pembuatan musik yang dikondisikan oleh lirik dan keterangan dengan MiniMax Music 3.

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

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

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

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

Pipeline modular untuk pembuatan musik yang dikondisikan oleh lirik dan keterangan menggunakan MiniMax Music 3. Model bahasa autoregressive Qwen3 menghasilkan kode semantik per-frame dan hidden states dari lirik serta deskripsi musik; transformer flow-matching mengubah hidden states menjadi latents Flow-VAE per chunk; dan vokoder bergaya DAC mendekodekannya menjadi waveform stereo pada 44,1 kHz.

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

Input: prompt (`str`): Deskripsi musik (genre, suasana, vokal, instrumen, aransemen). lyrics (`str`): Lirik yang akan dinyanyikan. Tag struktur seperti `[verse]` atau `[chorus]` harus masing-masing berada di baris tersendiri; teks pada baris yang sama dengan tag pembuka akan dihapus oleh kontrak input checkpoint. audio_duration (`float`, *opsional*, default 60.0): Batas atas panjang audio yang dihasilkan dalam detik. Model bahasa dapat berhenti lebih awal. Dibatasi pada 9000 frame (enam menit). generator (`Generator`, *opsional*): `Generator` Torch untuk generasi deterministik. num_inference_steps (`int`, *opsional*, default 30): Jumlah langkah Euler flow-matching per chunk. output_type (`str`, *opsional*, default np): Format output: 'np' atau 'pt'.

Output: audios (`Tensor | ndarray`): Gelombang stereo yang dihasilkan dengan bentuk `(batch, channels, samples)` dalam `[-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)
```

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

Memproyeksikan hidden states per-frame dari tahap autoregresif ke garis waktu laten Flow-VAE.

Setiap frame yang dihasilkan membawa `num_condition_layers` hidden states berukuran `condition_hidden_dim` (satu dari language model dan satu untuk setiap langkah residual codebook). Mereka dicampur dengan bobot softmax yang dipelajari, diproyeksikan, dan diresample dari frame rate language model ke frame rate laten dengan interpolasi nearest-neighbor.

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

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

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

**Parameter:**

hidden_states (`torch.Tensor` dengan bentuk `(batch, frames, num_condition_layers * condition_hidden_dim)`) : State tersembunyi per-frame yang digabungkan dari tahap autoregresif.

**Mengembalikan:** `torch.Tensor` dengan bentuk `(batch, latent_length, out_dim)`

urutan kondisioning yang selaras dengan laten.

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

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

Model bahasa lokal dari MiniMax Music 3. Di dalam setiap bingkai audio, model ini memprediksi secara autoregresif tujuh kodebuku RVQ residual (c1..c7) dari keadaan tersembunyi model bahasa global dan kode semantik bingkai tersebut, serta mengekspos keadaan tersembunyi per langkah yang menjadi kondisi bagi transformer flow-matching.

It juga memiliki tabel embedding untuk codebook residual, yang digunakan oleh pipeline untuk meng-embed frame lengkap bagi loop umpan balik model bahasa global.

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

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

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

**Parameter:**

inputs_embeds (`torch.Tensor` dengan bentuk `(batch, steps, hidden_size)`) : Embedding urutan kedalaman yang diproyeksikan: keadaan tersembunyi global diikuti oleh kode tertanam yang telah disampel sejauh ini, masing-masing melewati `projection`.

**Mengembalikan:** `torch.Tensor` dengan bentuk `(batch, steps, hidden_size)`

hidden states yang dinormalisasi; langkah terakhir memberi umpan ke kepala codebook berikutnya.

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

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

Dekoder waveform Flow-VAE dari MiniMax Music 3 (dekoder bergaya DAC). Dekoder ini mengubah latens flow-matched dengan bentuk `(batch, latent_channels, length)` menjadi waveform stereo pada `sampling_rate`; dua kanal audio didekode sebagai dua aliran terlipat `latent_channels // 2`.

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

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

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

**Parameter:**

latents (`torch.Tensor` dengan bentuk `(batch, latent_channels, length)`) : Latents Flow-matched Flow-VAE.

**Mengembalikan:** `torch.Tensor` dengan bentuk `(batch, 2, samples)`

bentuk gelombang stereo dalam `[-1, 1]`.