Hugging Face's logo

Diffusers documentation

MiniMax Music 3

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

MiniMax Music 3

MiniMax Music 3 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 merupakan hibrida dari tahap autoregressive 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 telah digabungkan dari keduanya menjadi kondisi bagi 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.

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 untuk detail lebih lanjut tentang berbagai teknik penghematan memori.

Pipeline lengkap membutuhkan ~23 GB VRAM dalam bfloat16. Dengan offloading CPU otomatis, sebuah generasi berjalan dalam ~23 GB VRAM bebas, dan dengan offloading grup untuk model bahasa, muat dalam 8 GB.

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, kunci, progresi emosional), detail vokal, dan aransemen.
  • audio_duration adalah batas atas — model bahasa dapat mengakhiri lagu lebih awal dengan token berhenti. Tahap autoregresif 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

kelas diffusers.MiniMaxMusic3ModularPipeline

< >

( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )

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

MiniMaxMusic3Blocks

kelas diffusers.MiniMaxMusic3Blocks

< >

( )

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)

Inputs: 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 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

kelas diffusers.MiniMaxMusic3ConditionEncoder

< >

( condition_hidden_dim: int = 4096num_condition_layers: int = 8out_dim: int = 2048input_sampling_rate: int = 24000input_hop_length: int = 960output_sampling_rate: int = 44100output_hop_length: int = 512 )

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 model bahasa dan satu untuk setiap langkah residual codebook). Mereka dicampur dengan bobot softmax yang dipelajari, diproyeksikan, dan diresample dari laju frame model bahasa ke laju frame laten dengan interpolasi nearest-neighbor.

forward

< >

( hidden_states: Tensor ) → torch.Tensor of shape (batch, latent_length, out_dim)

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

kelas diffusers.MiniMaxMusic3RVQDepthDecoder

< >

( hidden_size: int = 4096num_layers: int = 4num_attention_heads: int = 16intermediate_size: int = 6144audio_vocab_size: int = 1024num_codebooks: int = 8max_position_embeddings: int = 16 )

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

< >

( inputs_embeds: Tensor ) → torch.Tensor of shape (batch, steps, hidden_size)

Parameter

  • inputs_embeds (torch.Tensor dengan bentuk (batch, steps, hidden_size)) — Embedding urutan kedalaman yang diproyeksikan: keadaan tersembunyi global diikuti oleh kode ter-embed 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

kelas diffusers.MiniMaxMusic3Vocoder

< >

( latent_channels: int = 128decoder_input_dim: int = 1024decoder_hidden_dim: int = 1536upsampling_ratios: tuple = (8, 8, 4, 2)sampling_rate: int = 44100 )

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; kedua kanal audio didekode sebagai dua aliran terlipat latent_channels // 2.

forward

< >

( latents: Tensor ) → torch.Tensor of shape (batch, 2, samples)

Parameter

  • latents (torch.Tensor dengan bentuk (batch, latent_channels, length)) — Latents Flow-VAE yang cocok dengan aliran (flow-matched).

Mengembalikan

torch.Tensor dengan bentuk (batch, 2, samples)

bentuk gelombang stereo dalam [-1, 1].

Update on GitHub

←LTXVideo MiniMax-H3→