# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) — это модель генерации музыки, которая создает полноценные треки длительностью до пяти минут на основе текста песни и описания музыкального стиля, с выразительным вокалом и продуманной структурой.

Модель представляет собой гибрид авто-регрессивного и диффузионного этапов: глобальная языковая модель на базе Qwen3 объёмом 8B предсказывает один семантический аудиотокен на кадр, в то время как небольшой декодер глубины заполняет семь остаточных RVQ-кодовых книг, а их объединённые скрытые состояния задают условия для трансформера flow-matching объёмом 2.4B, который генерирует латенты Flow-VAE в перекрывающихся фрагментах. Декодер в стиле DAC преобразует латенты в стереоаудио с частотой дискретизации 44,1 кГц.

## Использование

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) для получения подробной информации о различных техниках экономии памяти.

Полный пайплайн требует ~23 ГБ VRAM в bfloat16. При автоматическом выгрузке на CPU генерация выполняется в ~22 ГБ свободной VRAM, а при дополнительном group-offloading языковой модели она помещается в 8 ГБ.

```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` — это верхняя граница: языковая модель может завершить песню раньше с помощью токена остановки. Авто регрессионный этап генерирует 25 кадров в секунду аудио и определяет общее время выполнения.
- Масштаб classifier-free guidance для этапа flow-matching является параметром guider (ссылочное значение при выводе — 1.7): замените его с помощью `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))`.
- Пайплайн возвращает стерео-выход вокодера с частотой дискретизации 44,1 кГц. Справочный сервер дополнительно выполняет ресемплинг до 32 кГц; при необходимости получить именно эту частоту примените собственный ресемплинг.

## 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/v0.43.0/src/diffusers/modular_pipelines/minimax_music3/modular_pipeline.py#L22)

ModularPipeline для генерации музыки по условиям в виде текста песни и описания с использованием MiniMax Music 3.

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_music3/modular_blocks_minimax_music3.py#L130)

Модульный конвейер для генерации музыки по текстам песен и описаниям с использованием MiniMax Music 3. Авто регрессионная языковая модель Qwen3 генерирует семантические коды и скрытые состояния для каждого кадра на основе текста песни и описания музыки; трансформер с потоковым соответствием (flow-matching) преобразует скрытые состояния в латенты Flow-VAE по частям; а вокодер в стиле DAC декодирует их в стерео-волну с частотой дискретизации 44,1 кГц.

Компоненты: токенизатор (`Qwen2Tokenizer`) language_model (`Qwen3ForCausalLM`) rvq_depth_decoder (`MiniMaxMusic3RVQDepthDecoder`) condition_encoder (`MiniMaxMusic3ConditionEncoder`) transformer (`MiniMaxMusic3Transformer1DModel`) планировщик (`FlowMatchEulerDiscreteScheduler`) guider (`ClassifierFreeGuidance`) вокодер (`MiniMaxMusic3Vocoder`)

Входные данные: prompt (`str`): Описание музыки (жанр, настроение, вокал, инструменты, аранжировка). lyrics (`str`): Текст песни. Структурные теги, такие как `[verse]` или `[chorus]`, должны находиться каждый на отдельной строке; текст на той же строке, что и ведущий тег, отбрасывается в соответствии с контрактом входных данных чекпоинта. audio_duration (`float`, *необязательный*, по умолчанию 60.0): Верхняя граница длительности генерируемого аудио в секундах. Языковая модель может остановиться раньше. Ограничено 9000 кадрами (шесть минут). generator (`Generator`, *необязательный*): Генератор Torch для детерминированной генерации. num_inference_steps (`int`, *необязательный*, по умолчанию 30): Количество шагов Эйлера для flow-matching на каждый чанк. output_type (`str`, *необязательный*, по умолчанию np): Формат вывода: 'np' или 'pt'.

Выводы: audios (`Tensor | ndarray`): сгенерированная стерео-волновая форма формы `(batch, channels, samples)` в диапазоне `[-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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/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/v0.43.0/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/v0.43.0/src/diffusers/models/transformers/minimax_music3_rvq_depth_decoder.py#L91)

Локальная языковая модель MiniMax Music 3. В каждом аудиокадре она авто регрессивно предсказывает семь остаточных RVQ-кодовых книг (c1..c7) на основе скрытого состояния глобальной языковой модели и семантического кода кадра, а также предоставляет скрытые состояния на каждом шаге, которые задают условия для трансформера flow-matching.

Он также содержит таблицу эмбеддингов для остаточных кодовых книг, которую конвейер использует для встраивания полных кадров в контуре обратной связи глобальной языковой модели.

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/minimax_music3_rvq_depth_decoder.py#L127)

**Параметры:**

inputs_embeds (`torch.Tensor` формы `(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/v0.43.0/src/diffusers/models/autoencoders/minimax_music3_vocoder.py#L71)

Декодер волновых форм Flow-VAE в MiniMax Music 3 (декодер в стиле DAC). Он декодирует латенты, полученные с помощью flow-matching, формы `(batch, latent_channels, length)` в стереоволновые формы с частотой дискретизации `sampling_rate`; два аудиоканала декодируются как два свёрнутых потока `latent_channels // 2`.

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

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/minimax_music3_vocoder.py#L100)

**Параметры:**

latents (`torch.Tensor` формы `(batch, latent_channels, length)`) : Латенты Flow-matched Flow-VAE.

**Возвращает:** `torch.Tensor` формы `(batch, 2, samples)`

стереосигнал в диапазоне `[-1, 1]`.