# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) هو نموذج لتوليد الموسيقى ينتج أغاني كاملة تصل مدتها إلى خمس دقائق انطلاقًا من كلمات الأغنية ووصف موسيقي، مع أصوات غنائية معبّرة وهيكل موسيقي ممتد.

النموذج هو هجين من مرحلة توليد ذاتية التراجع ومرحلة انتشار: نموذج لغة عالمي مبني على Qwen3 بحجم 8B يتنبأ برمز صوتي دلالي واحد لكل إطار، بينما يملأ مُفكك عمق صغير سبعة كتل رموز 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) لمزيد من التفاصيل حول تقنيات توفير الذاكرة المختلفة.

يتطلب خط الأنابيب الكامل حوالي 23 غيغابايت من ذاكرة الفيديو (VRAM) في وضع bfloat16. مع التفريغ التلقائي إلى وحدة المعالجة المركزية (CPU)، يتم تنفيذ عملية التوليد في حوالي 22 غيغابايت من ذاكرة الفيديو المتاحة، بالإضافة إلى ذلك، فإن التفريغ الجماعي لنموذج اللغة يتسع في 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`. يتم تجاهل النص الموجود في نفس السطر مع وسم البداية بموجب عقد إدخال النموذج.
- يتحكم وصف الموسيقى في الغناء: صف جنس الصوت ونبرته بوضوح (مثلًا "صوت أنثوي دافئ") وإلا قد ينحرف النموذج نحو موسيقى بدون غناء. للتحكم الدقيق، قسّم الوصف إلى بيانات وصفية عامة (النوع الموسيقي، الإيقاس، المفتاح، التقدم العاطفي)، وتفاصيل الغناء، والترتيب.
- `audio_duration` هو حد أقصى — فقد ينهي نموذج اللغة الأغنية مبكرًا باستخدام رمز إيقاف. تولّد المرحلة التلقائية التوليدية 25 إطارًا لكل ثانية من الصوت، وهي المهيمنة على وقت التشغيل.
- مقياس التوجيه الحر من التصنيف في مرحلة مطابقة التدفق هو إعداد موجّه (القيمة المرجعية للاستدلال هي 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/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 transformer) الحالات الخفية إلى كامنات Flow-VAE على شكل مقاطع متتالية؛ وأخيرًا يفكك مُصوِّغ (vocoder) بنمط DAC هذه الكامنات إلى موجة صوتية مجسّمة بمعدل عينة 44.1 kHz.

المكوّنات: مُجزّئ (`Qwen2Tokenizer`) نموذج اللغة (`Qwen3ForCausalLM`) مٌفكّك عمق RVQ (`MiniMaxMusic3RVQDepthDecoder`) مٌشفّر الشروط (`MiniMaxMusic3ConditionEncoder`) محوّل (`MiniMaxMusic3Transformer1DModel`) مٌجدول (`FlowMatchEulerDiscreteScheduler`) مٌوجّه (`ClassifierFreeGuidance`) مٌولّد الصوت (`MiniMaxMusic3Vocoder`)

المدخلات: prompt (`str`): وصف الموسيقى (النوع، المزاج، الغناء، الآلات، التوزيع). lyrics (`str`): الكلمات التي سيتم غناؤها. يجب أن تكون وسوم الهيكل مثل `[verse]` أو `[chorus]` كلٌّ منها في سطر مستقل؛ فأي نص يقع في نفس السطر مع وسم في البداية يُهمل بموجب عقد مدخلات نقطة التفتيش. audio_duration (`float`, *اختياري*, الافتراضي 60.0): الحد الأقصى لطول الصوت المولّد بالثواني. قد يتوقف نموذج اللغة قبل ذلك. يُقيَّد بـ 9000 إطار (ست دقائق). generator (`Generator`, *اختياري*): مولّد Torch لتوليد حتمي. num_inference_steps (`int`, *اختياري*, الافتراضي 30): عدد خطوات Euler لمطابقة التدفق لكل شريحة. output_type (`str`, *اختياري*, الافتراضي np): صيغة الإخراج: 'np' أو 'pt'.

المخرجات: الأصوات (`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) من حالة الخفاء الخاصة بالنموذج اللغوي العام والرمز الدلالي للإطار، ويعرض حالات الخفاء لكل خطوة التي تشترط محول مطابقة التدفق.

كما أنه يمتلك جدول التضمين (embedding table) لدفاترم الشيفرة المتبقية (residual codebooks)، والذي تستخدمه خط المعالجة لتضمين الإطارات الكاملة لحلقة تغذية راجعة لنموذج اللغة العام.

#### 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-matched latents) ذات الشكل `(batch, latent_channels, length)` إلى موجات صوتية مجسّمة (stereo) بمعدل أخذ عينات `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-VAE المطابقة للتدفق.

**يعيد:** `torch.Tensor` من الشكل `(batch, 2, samples)`

الموجة الصوتية المجسّمة في `[-1, 1]`.