# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) は、歌詞と音楽の記述から、表現力豊かなボーカルと長尺の構造を備えた最大5分間の完成曲を生成する音楽生成モデルです。

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

## 使用方法

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

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

## メモリ使用量の削減

メモリ使用量の削減に関する詳細については、[メモリ使用量の削減](../../optimization/memory)ガイドを参照してください。

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

## ヒント

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

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

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

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

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

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

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

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

コンポーネント: トークナイザー (`Qwen2Tokenizer`) language_model (`Qwen3ForCausalLM`) rvq_depth_decoder (`MiniMaxMusic3RVQDepthDecoder`) condition_encoder (`MiniMaxMusic3ConditionEncoder`) transformer (`MiniMaxMusic3Transformer1DModel`) スケジューラー (`FlowMatchEulerDiscreteScheduler`) ガイダー (`ClassifierFreeGuidance`) ボコーダー (`MiniMaxMusic3Vocoder`)

Inputs: 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[[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)
```

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

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

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

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

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

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

**パラメータ:**

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

**戻り値:** `torch.Tensor`、形状 `(batch, latent_length, out_dim)`

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

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

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

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

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

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

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

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

**パラメータ:**

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

**戻り値:** `torch.Tensor`、形状は `(batch, steps, hidden_size)`

正規化された隠れ状態;最後のステップが次のコードブックヘッドに供給されます。

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

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

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

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

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

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

**パラメータ:**

latents (`torch.Tensor`、shape `(batch, latent_channels, length)`) : Flow-matched Flow-VAE の latents。

**戻り値:** `torch.Tensor`、形状 `(batch, 2, samples)`

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