Hugging Face's logo

Diffusers documentation

MiniMax Music 3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
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 は、歌詞と音楽の記述から、表現力豊かなボーカルと長尺の構造を備えた最大5分間の完全な楽曲を生成する音楽生成モデルです。

モデルは、自己回帰ステージと拡散ステージのハイブリッド構成です。8BのQwen3ベースのグローバル言語モデルがフレームごとに1つのセマンティックオーディオトークンを予測し、小型の深度デコーダーが7つの残差RVQコードブックを補完します。これら融合された隠れ状態が条件となり、2.4Bのフローマッチングトランスフォーマーが、重複するチャンク単位でFlow-VAEの潜在変数を生成します。DACスタイルのデコーダーが、これらの潜在変数を44.1 kHzのステレオオーディオに変換します。

使用方法

MiniMax Music 3 は、モジュール化されたパイプラインとして利用できます。

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)

メモリ使用量の削減

メモリ使用量の削減に関する詳細については、メモリ使用量の削減ガイドを参照してください。

完全なパイプラインには、bfloat16 で約 23 GB の VRAM が必要です。自動 CPU オフロードを使用すると、生成は約 22 GB の空き VRAM で実行でき、さらに言語モデルのグループオフロードを使用すれば 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
)

ヒント

  • [intro]、[verse]、[pre-chorus]、[chorus]、[bridge]、[instrumental]、[solo]、[outro] などの構造タグは、lyrics 内でそれぞれ独立した行に配置する必要があります。先頭のタグと同じ行にあるテキストは、モデルの入力仕様により破棄されます。
  • 音楽の説明はボーカルを制御します。ボーカルの性別や音色を明示的に記述してください（例: “warm female vocal”）。そうしないと、モデルがインストゥルメンタルに逸脱する可能性があります。より細かな制御を行うには、説明をグローバルなメタデータ（ジャンル、BPM、キー、感情の進行）、ボーカルの詳細、アレンジメントの3つの部分に構造化してください。
  • audio_duration は上限値です。言語モデルは停止トークンにより、より早く曲を終了する場合があります。 自己回帰ステージは、1秒の音声あたり25フレームを生成し、実行時間の大部分を占めます。
  • フローマッチング段階のclassifier-free guidance scaleはguiderの設定です（参照推定値は1.7）：pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))で置き換えてください。
  • パイプラインは、ボコーダーのネイティブである 44.1 kHz ステレオ出力を返します。参照サーバーでは、さらに 32 kHz にリサンプリングされます。この特定のレートが必要な場合は、ご自身でリサンプリングを適用してください。

MiniMaxMusic3ModularPipeline

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

MiniMax Music 3 による歌詞およびキャプション条件付き音楽生成のための ModularPipeline。

MiniMaxMusic3Blocks

class diffusers.MiniMaxMusic3Blocks

< >

( )

MiniMax Music 3 を用いた、歌詞およびキャプション条件付きの音楽生成のためのモジュラーなパイプラインです。自己回帰型 Qwen3 言語モデルが、歌詞と音楽の説明からフレームごとのセマンティックコードと隠れ状態を生成します。次に、フローマッチング型トランスフォーマーが、隠れ状態をチャンクごとに Flow-VAE の潜在変数に変換します。最後に、DAC 方式のボコーダーがそれらを 44.1 kHz のステレオ波形にデコードします。

コンポーネント: tokenizer (Qwen2Tokenizer) language_model (Qwen3ForCausalLM) rvq_depth_decoder (MiniMaxMusic3RVQDepthDecoder) condition_encoder (MiniMaxMusic3ConditionEncoder) transformer (MiniMaxMusic3Transformer1DModel) scheduler (FlowMatchEulerDiscreteScheduler) guider (ClassifierFreeGuidance) vocoder (MiniMaxMusic3Vocoder)

入力: prompt (str): 音楽の記述（ジャンル、ムード、ボーカル、楽器編成、アレンジ）。 lyrics (str): 歌う歌詞。構造タグ（[verse] や [chorus] など）は、それぞれ独立した行に配置する必要があります。先頭のタグと同じ行にあるテキストは、チェックポイントの入力規約により破棄されます。 audio_duration (float, 任意, デフォルト値 60.0): 生成される音声の長さの上限（秒）。言語モデルはこれより早く停止する場合があります。上限は 9000 フレーム（6 分）です。 generator (Generator, 任意): 決定論的な生成のための Torch ジェネレーター。 num_inference_steps (int, 任意, デフォルト値 30): チャンクごとの flow-matching Euler ステップ数。 output_type (str, 任意, デフォルト値 np): 出力形式: ‘np’ または ‘pt’。

出力: audios (Tensor | ndarray): [-1, 1] の範囲で、形状が (batch, channels, samples) の生成されたステレオ波形。

MiniMaxMusic3ConditionEncoder

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

自己回帰ステージのフレームごとの隠れ状態を、Flow-VAEの潜在タイムラインに射影します。

各生成フレームには、num_condition_layers 個の、サイズが condition_hidden_dim の隠れ状態（言語モデル由来の 1 個と、残差コードブックステップごとの 1 個）が含まれます。これらは学習された softmax 重みで混合され、射影された後、最近傍補間により言語モデルのフレームレートから潜在フレームレートへリサンプリングされます。

forward

< >

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

パラメータ

  • hidden_states (torch.Tensor、形状 (batch, frames, num_condition_layers * condition_hidden_dim)) — 自己回帰ステージからのフレームごとの隠れ状態を連結したもの。

戻り値

torch.Tensor、形状 (batch, latent_length, out_dim)

潜在変数に整列された条件付けシーケンス。

MiniMaxMusic3RVQDepthDecoder

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

MiniMax Music 3 のローカル言語モデルです。各オーディオフレーム内で、グローバル言語モデルの隠れ状態とフレームのセマンティックコードから、7 つの残差 RVQ コードブック（c1..c7）を自己回帰的に予測し、フローマッチングトランスフォーマーを条件づける各ステップの隠れ状態を公開します。

また、残差コードブック用の埋め込みテーブルも保持しており、パイプラインはこれを使用して完全なフレームを埋め込み、グローバル言語モデルのフィードバックループに利用します。

forward

< >

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

パラメータ

  • inputs_embeds (torch.Tensor、shape (batch, steps, hidden_size)) — 射影された深度シーケンス埋め込み: グローバルな隠れ状態に、これまでにサンプリングされた埋め込みコードを続けたもので、それぞれがprojectionを通過しています。

戻り値

torch.Tensor、形状 (batch, steps, hidden_size)

正規化された隠れ状態;最後のステップは次のcodebook headに供給されます。

MiniMaxMusic3Vocoder

class diffusers.MiniMaxMusic3Vocoder

< >

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

MiniMax Music 3 の Flow-VAE ウェーブフォームデコーダー（DAC 形式のデコーダー）です。(batch, latent_channels, length) の形状を持つ flow-matched 潜在変数を sampling_rate のステレオウェーブフォームにデコードします。2 つのオーディオチャネルは、それぞれ latent_channels // 2 のストリームとして折り畳まれてデコードされます。

forward

< >

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

パラメータ

  • latents (torch.Tensor、形状 (batch, latent_channels, length)) — Flow-matched Flow-VAE の潜在変数です。

戻り値

torch.Tensor、形状 (batch, 2, samples)

[-1, 1] 範囲のステレオ波形。

Update on GitHub

←LongCat-AudioDiT Stable Audio→