# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3)는 가사와 음악 설명을 입력받아 표현력 있는 보컬과 긴 호흡의 구조를 갖춘 최대 5분 길이의 완성된 곡을 생성하는 음악 생성 모델입니다.

모델은 자기회귀 단계와 확산 단계의 하이브리드입니다: 8B Qwen3 기반의 전역 언어 모델이 프레임당 하나의 의미론적 오디오 토큰을 예측하는 동안, 작은 깊이 디코더가 7개의 잔차 RVQ 코드북을 채우며, 이들의 융합된 은닉 상태는 겹치는 청크로 Flow-VAE 잠재 변수를 생성하는 2.4B flow-matching transformer를 조건화합니다. 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`에서 각각 별도의 줄에 위치해야 합니다. 시작 태그와 같은 줄에 있는 텍스트는 모델의 입력 계약에 의해 제거됩니다.
- 음악 설명은 보컬을 제어합니다. 보컬의 성별과 음색을 명시적으로 설명(예: "따뜻한 여성 보컬")하지 않으면 모델이 악기 연주 중심으로 벗어날 수 있습니다. 세밀한 제어를 위해 설명을 전체 메타데이터(장르, BPM, 톤, 감정 진행), 보컬 세부 사항, 편곡으로 구성하세요.
- `audio_duration`은 상한선입니다. 언어 모델은 stop token을 사용하여 곡을 더 일찍 종료할 수 있습니다. 자기 회귀 단계는 초당 25프레임의 오디오를 생성하며 런타임의 대부분을 차지합니다.
- Flow-matching 단계의 classifier-free guidance scale은 guider 설정입니다(참고 추론 값은 1.7): `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))`로 교체하세요.
- pipeline은 vocoder의 네이티브 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 generator. num_inference_steps (`int`, *선택 사항*, 기본값 30): 청크당 flow-matching Euler 단계 수. output_type (`str`, *선택 사항*, 기본값 np): 출력 형식: 'np' 또는 'pt'.

Outputs: 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 잠재 타임라인으로 오토레그레시브 단계의 프레임별 숨겨진 상태를 투영합니다.

각 생성된 프레임은 `num_condition_layers`개의 숨겨진 상태를 가지며, 그 크기는 `condition_hidden_dim`입니다(언어 모델에서 하나, 잔차 코드북 단계마다 하나씩). 이들은 학습된 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`, shape `(batch, frames, num_condition_layers * condition_hidden_dim)`) : 자기회귀 단계에서 생성된 프레임별 숨겨진 상태(hidden states)를 연결한 값.

**반환값:** `torch.Tensor`, shape `(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`, shape `(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)` 형태의 flow-matched latents를 `sampling_rate`의 스테레오 웨이브폼으로 디코딩하며, 두 오디오 채널은 두 개의 접힌 `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`, shape `(batch, 2, samples)`

`[-1, 1]` 범위의 스테레오 웨이브폼.