# Stable Audio 3

نموذج Stable Audio 3 (SA3) هو نموذج لتحويل النص إلى صوت من [Stability AI](https://stability.ai/) يولّد صوتًا ستيريو عالي الجودة بمعدل 44.1 kHz. يستخدم DiT من نوع rectified-flow مشروطًا بإشارتين:

* **النص** — يُرمَّز بواسطة مُرمِّز T5Gemma ثابت ويُحقن عبر الانتباه المتقاطع.
* **المدة** — قيمة عشرية (بالثواني) تُضمَّن بواسطة [StableAudio3DurationEmbedder](/docs/diffusers/main/ar/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder) وتُستخدم كمتجه تكييف عام لتطبيع الطبقات التكيفية.

يتم فك ترميز الصوت بواسطة مُرمِّز الترميز التلقائي SAME (المُرمِّز الموسيقي المُحاذاة دلاليًا)، [AutoencoderSAME](/docs/diffusers/main/ar/api/models/autoencoder_same#diffusers.AutoencoderSAME).

تستخدم كلا نقطتي التفتيش [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ar/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) مع جدول سيجما موحّد على مقياس log-SNR، ولا يختلفان إلا في `stochastic_sampling` وعدد الخطوات الافتراضي:

| نقطة التفتيش | `diffusion_objective` | `stochastic_sampling` | `num_inference_steps` |
|---|---|---|---|
| `stable-audio-3-medium-base` | `rectified_flow` | `False` (أويلر الحتمي) | **100** (غير مُقطَّرة) |
| `stable-audio-3-medium` (مُقطَّر) | `rf_denoiser` | `True` (إعادة الضوضاء بنظام التنس الطاولة) | **8** (مُقطَّر على 8 خطوات) |

يتم تضمين إعدادات المجدول الصحيحة في كل نقطة تحقق محوّلة، لذا فإن `num_inference_steps` يتخذ القيمة الصحيحة افتراضيًا عندما تتركه غير مضبوط. مرّره فقط لتجاوز القيمة الافتراضية.

قاعدة الكود الأصلية: [Stability-AI/stable-audio-3](https://github.com/Stability-AI/stable-audio-3).

## تحويل نقاط التفتيش الأصلية

نقاط التفتيش الخاصة بـ Stability AI غير منشورة بتنسيق diffusers، لذا قم بتحويلها محليًا. يقوم السكربت بتنزيل `model_config.json` الخاص بنقطة التفتيش واختيار المجدول من `diffusion_objective` الخاص بها:

```bash
python scripts/convert_stable_audio_3_to_diffusers.py \
  --checkpoint_path stabilityai/stable-audio-3-medium-base \
  --text_encoder_repo google/t5gemma-b-b-ul2 \
  --output_dir /tmp/sa3-diffusers-euler \
  --dtype float32
```

> [!TIP]
> `stable-audio-3-medium-base` مستودع **مقيّد**. نفّذ `hf auth login` بحساب لديه صلاحية الوصول قبل التحويل، وإلا سيفشل التنزيل برمز 401.

## مثال على الاستخدام

حمّل نقطة التحويل المحوّلة من مجلد الإخراج المحلي الخاص بها (ثبّت [`soundfile`](https://pypi.org/project/soundfile/) باستخدام `pip install soundfile`):

```py
import torch
import soundfile as sf
from diffusers import StableAudio3Pipeline

pipe = StableAudio3Pipeline.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

generator = torch.Generator("cuda").manual_seed(0)
audio = pipe(
    "A gentle piano melody with soft strings in a concert hall",
    duration=10.0,  # seconds; latent length is computed automatically
    generator=generator,
).audios

sf.write("sa3_output.wav", audio[0].T.cpu().float().numpy(), samplerate=44100)
```

يُسجَّل خط الأنابيب أيضًا مع [AutoPipelineForText2Audio](/docs/diffusers/main/ar/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio)، والذي يحلّ نقطة التفتيش تلقائيًا إلى `StableAudio3Pipeline`:

```py
from diffusers import AutoPipelineForText2Audio

pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)
```

> [!NOTE]
> تستخدم الأمثلة مسارًا محليًا لأن `stabilityai/stable-audio-3-medium` و`stable-audio-3-medium-base` لم تُنشر بعد بصيغة diffusers (فإن التحميل عبر معرف المستودع يعيد خطأ 404). بمجرد النشر، يعمل معرف المستودع بدلًا من المسار المحلي.

## نصائح

* استخدم `torch.float32` على المعالج المركزي (CPU) أو وحدة معالجة الإشارات (MPS) (Apple Silicon) — فاستخدام `torch.float16` على MPS ينتج ضوضاء.
* النموذج المُصغَّر (`stable-audio-3-medium`) هو **مُصغَّر خصوميًا** — فالتوجيه مُدمج في الأوزان. اترك `guidance_scale=1.0` (القيمة الافتراضية) ولا تُمرِّر `negative_prompt` لذلك نقطة الفحص؛ فكلاهما لا يُفيد إلا في نقطة الفحص غير المُصغَّرة `stable-audio-3-medium-base`.
* `silence_padding_duration` (الافتراضي `0.0`) يضيف مساحة صامتة في نهاية تسلسل الكمون. اتركه عند `0.0` ما لم يكن النموذج مدرَّبًا على إخفاء تلك الحشوة — وإلا فإن الإطارات الإضافية تستنزف طاقة الإخراج ويصبح الناتج هادئًا.
* اضبط `num_waveforms_per_prompt > 1` لتوليد مقاطع متعددة لكل موجه.

## StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]]

#### diffusers.StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]]

```python
diffusers.StableAudio3Pipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L157)

**المعاملات:**

vae ([*AutoencoderSAME*]) : مُشفِّر-مفكِّك SAME المستخدم لتشفير وفك تشفير الكامنات الصوتية.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : مُشفِّر نصوص T5Gemma مجمّد (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : مُجزِّئ (Tokenizer) لمُشفِّر النص.

duration_embedder ([*StableAudio3DurationEmbedder*]) : يحوّل `duration` بالثواني إلى متجه تكييف عام لـ AdaLN في كل كتلة DiT.

transformer ([*StableAudio3DiTModel*]) : نموذج DiT للتنبؤ بسرعة التدفق المُصحَّح.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : مُجدول لحلقة إزالة الضوضاء التكرارية. يستخدم نقطة التفتيش (المُقطّرة) SA3 Medium للإنتاج *stochastic_sampling=True* لخطوات ذهاب وإياب عشوائية بالضبط 8 خطوات؛ بينما تستخدم نقطة التفتيش الأساسية غير المُقطّرة *stochastic_sampling=False* لحوالي 100 خطوة أويلر حتمية.

خط أنابيب لتوليد الصوت من النص باستخدام Stable Audio 3.

يستخدم SA3 نموذج DiT مُقطّر لتدفق مُصحح مع أخذ عينات بنظام ping-pong. لا حاجة إلى التوجيه بدون مُصنّف (`guidance_scale` / `negative_prompt`) للنقطة الفاحصة المُقطّرة (اترك `guidance_scale=1.0`، وهو الافتراضي)، لكنه ذو معنى للنقطة الفاحصة غير المُقطّرة `stable-audio-3-medium-base`.

يرث هذا النموذج من [*DiffusionPipeline*]. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب.

#### __call__[[diffusers.StableAudio3Pipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, guidance_scale: float = 1.0, negative_prompt: typing.Union[str, typing.List[str], NoneType] = None, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt')
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L398)

**المعاملات:**

prompt (*str* أو *list[str]*، *اختياري*) : موجهات النص. مرّر `prompt_embeds` بدلاً من ذلك لتخطي الترميز والتشفير.

duration (*float*، القيمة الافتراضية 10.0) : المدة المطلوبة للمخرجات بالثواني.

num_inference_steps (*int*, *optional*) : عدد خطوات إزالة الضوضاء. عند تعيين `None` (الافتراضي)، يتم اختيار عدد الخطوات من إعداد *stochastic_sampling* في المجدول: **8** عند *True* (نقطة الحفظ المُقطّرة بنمط ping-pong) و**100** عند *False* (نقطة الحفظ الأساسية غير المُقطّرة). مرّر قيمة صريحة للتجاوز.

logsnr_min (*float*، القيمة الافتراضية -6.2) : الحد الأدنى لقيمة log-SNR في جدول الضوضاء — يتوافق مع بداية الجدول ذات الضوضاء العالية.

logsnr_max (*float*، القيمة الافتراضية 2.0) : القيمة القصوى لـ log-SNR في جدول الضوضاء — تُطابق الطرف منخفض الضوضاء من الجدول.

silence_padding_duration (*float*، القيمة الافتراضية 0.0) : عدد ثوانٍ إضافي من السياق الكامن (latent) الذي يتم توليده بما يتجاوز المحتوى المستهدف، مما يمنح النموذج مساحة عمل عند الحدّ؛ حيث يتم اقتطاع المخرجات لتعود إلى *duration*. القيمة الافتراضية هي 0.0 (معطّل). قم بزيادة القيمة فقط إذا كان النموذج مدرَّبًا أو مُقطَّرًا (distilled) على إخفاء هذا الحشو — وإلا فإن الإطارات الإضافية ستُستنزف طاقة المخرجات.

guidance_scale (*float*، القيمة الافتراضية 1.0) : مقياس التوجيه الحر من التصنيف. تعطّل القيمة `1.0` التوجيه (وهي القيمة الافتراضية، والقيمة الوحيدة المعقولة لنقطة التفتيش المُقطّرة SA3 Medium، حيث يكون التوجيه الحر من التصنيف مدمجًا في الأوزان). القيم `> 1.0` ذات معنى لنقطة التفتيش غير المُقطّرة `stable-audio-3-medium-base`؛ فالقيم الأعلى تتبع الموجّه عن قرب أكبر على حساب التنوع.

negative_prompt (*str* أو *list[str]*، *اختياري*) : موجه (موجّهات) تصف ما يجب تجنّبه عند `guidance_scale > 1.0`. الافتراضي هو نص فارغ (غير مشروط) عند `guidance_scale > 1.0` إذا لم يُقدَّم هذا ولا *negative_prompt_embeds*. يُتجاهل عند `guidance_scale <= 1.0`.

num_waveforms_per_prompt (*int*، القيمة الافتراضية 1) : عدد الموجات الصوتية التي سيتم توليدها لكل موجه.

generator (*torch.Generator* أو *list[torch.Generator]*، *اختياري*) : لتوليد حتمي وإعادة ضجيج قابلة للتكرار في حلقة ping-pong.

latents (*torch.Tensor*، *اختياري*) : قيم البداية الكامنة المُولَّدة مسبقًا. إذا كانت `None` يتم أخذ عينة من متجه غاوسي جديد.

prompt_embeds (*torch.Tensor*، *اختياري*) : تمثيلات نصية محسوبة مسبقًا `(batch, seq_len, 768)`.

encoder_attention_mask (*torch.LongTensor*، *اختياري*) : قناع منطقي للتضمينات المحسوبة مسبقًا.

negative_prompt_embeds (*torch.Tensor*، *اختياري*) : تمثيلات نصية سالبة محسوبة مسبقًا، كبديل لـ *negative_prompt*.

negative_encoder_attention_mask (*torch.LongTensor*، *اختياري*) : قناع منطقي للتضمينات السالبة المحسوبة مسبقًا.

return_dict (*bool*، القيمة الافتراضية *True*) : إرجاع *AudioPipelineOutput* أو tuple عادي.

callback_on_step_end (*Callable*، *اختياري*) : يُستدعى في نهاية كل خطوة إزالة ضوضاء مع *(self, step_idx, timestep, callback_kwargs)*، حيث يحتوي *callback_kwargs* على المصفوفات المدرجة في *callback_on_step_end_tensor_inputs*. يجب أن يعيد قاموسًا يحتوي على المصفوفات (المعدّلة اختياريًا) لاستخدامها في بقية الحلقة.

callback_on_step_end_tensor_inputs (*list[str]*، الافتراضي *["latents"]*) : المصفوفات التي تُمرَّر إلى *callback_on_step_end*. يجب أن تكون مجموعة فرعية من *self._callback_tensor_inputs*.

output_type (*str*، القيمة الافتراضية هي `"pt"`) : `"pt"` لمصفوفة PyTorch، أو `"np"` لمصفوفة NumPy، أو `"latent"` لتخطي فك الترميز وإرجاع القيم الكامنة الخام.

**يعيد:** [*~pipelines.AudioPipelineOutput*] أو *tuple*

`.audios` هو متجه / مصفوفة بأبعاد `(batch * num_waveforms_per_prompt, audio_channels, samples)`.

توليد صوت من نص.

أمثلة:
```py
>>> import torch
>>> import soundfile as sf
>>> from diffusers import StableAudio3Pipeline

>>> pipe = StableAudio3Pipeline.from_pretrained("stabilityai/stable-audio-3-medium", torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)
```

#### encode_duration[[diffusers.StableAudio3Pipeline.encode_duration]]

```python
encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L289)

**المعاملات:**

duration : المدة بالثواني، تُطبَّق على كل عينة في الدفعة.

device : جهاز الهدف.

num_waveforms_per_prompt : معامل البلاطات.

batch_size : عدد الأوامر.

**يعيد:**

مصفوفة `(batch * num_waveforms_per_prompt, output_dim)`.

Embed قيمة المدة في متجه الشروط العام.

#### encode_prompt[[diffusers.StableAudio3Pipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L223)

**المعاملات:**

prompt : موجه نصي أو قائمة من الموجهات. يتم تجاهله عند توفير `prompt_embeds`.

device : جهاز الهدف.

num_waveforms_per_prompt : عدد موجات الإخراج التي سيتم توليدها لكل موجه؛ حيث يتم تكرار متجهات الشرط (conditioning tensors) وفقًا لذلك.

prompt_embeds : تمثيلات نصية محسوبة مسبقًا `(batch, seq_len, hidden_size)`.

encoder_attention_mask : قناع منطقي `(batch, seq_len)` للتضمينات المحسوبة مسبقًا؛ `1` = رمز حقيقي، `0` = حشو.

**يعيد:**

`(prompt_embeds, encoder_attention_mask)` كلاهما مُوسَّع إلى `batch * num_waveforms_per_prompt`.

ترميز موجهات النص إلى متجهات شروط الانتباه المتقاطع.

#### prepare_cross_attention[[diffusers.StableAudio3Pipeline.prepare_cross_attention]]

```python
prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L313)

**يعيد:**

`(context, context_mask)` بأشكال `(batch, T_text + 1, dim)` و`(batch, T_text + 1)`.

قم ببناء سياق الانتباه المتقاطع (cross-attention context) عن طريق إضافة تضمين المدة (duration embedding) كرمز إضافي.

يوجّه SA3 مُشكّل `seconds_total` إلى *كلا* المدخل العام (AdaLN) وسياق الانتباه المتقاطع (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). يتم دمج تضمين المدة بعد رموز النص، ويُمدَّد قناع الانتباه بإدخال صالح واحد.

## StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]]

#### diffusers.StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]]

```python
diffusers.StableAudio3InpaintPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L158)

**المعاملات:**

vae ([*AutoencoderSAME*]) : مُشفِّر-مفكِّك SAME المستخدم لتشفير وفك تشفير الكامنات الصوتية.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : مُشفِّر نصوص T5Gemma مجمّد (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : مُجزِّئ (Tokenizer) لمُشفِّر النص.

duration_embedder ([*StableAudio3DurationEmbedder*]) : يحوّل `duration` بالثواني إلى متجه تكييف عام لـ AdaLN في كل كتلة DiT.

transformer ([*StableAudio3DiTModel*]) : نموذج DiT للتنبؤ بسرعة التدفق المُصحَّح.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : مُجدول لحلقة إزالة الضوضاء التكرارية. يستخدم نقطة التفتيش (المُقطّرة) SA3 Medium للإنتاج *stochastic_sampling=True* لخطوات ذهاب وإياب عشوائية بالضبط 8 خطوات؛ بينما تستخدم نقطة التفتيش الأساسية غير المُقطّرة *stochastic_sampling=False* لحوالي 100 خطوة أويلر حتمية.

خط أنابيب معالجة الصوت (Inpainting) لنموذج Stable Audio 3.

Shares its text-to-audio logic with [*StableAudio3Pipeline*] (kept in sync via *# Copied from*). When `audio` and `mask` are provided, encodes the reference audio with the frozen SAME encoder and injects `masked_latent ∥ mask` as local-additive conditioning into each DiT block via the transformer's `local_add_cond` pathway (`to_local_embed`).

توقيع الاستدعاء الموسّع (انظر `__call__`): الصوت (*torch.Tensor* من الشكل `(batch, channels, samples)`): موجة الصوت المرجعية عند `vae.config.sampling_rate` هرتز. القناع (*torch.Tensor* من الشكل `(batch, 1, latent_length)`): قناع ثنائي لكل إطار في الفضاء الكامن. `1` = الحفاظ على الصوت الأصلي؛ `0` = المنطقة التي سيتم استكمالها.

#### __call__[[diffusers.StableAudio3InpaintPipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, audio: typing.Optional[torch.Tensor] = None, mask: typing.Optional[torch.Tensor] = None, mask_start_seconds: typing.Union[float, typing.List[float], NoneType] = None, mask_end_seconds: typing.Union[float, typing.List[float], NoneType] = None, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt')
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L455)

**المعاملات:**

prompt (*str* أو *list[str]*، *اختياري*) : موجهات النص.

duration (*float*، القيمة الافتراضية 10.0) : مدة الإخراج بالثواني. يجب أن تتطابق مع الصوت المرجعي.

audio (*torch.Tensor*، *اختياري*) : الموجة المرجعية `(batch, channels, samples)` عند `vae.config.sampling_rate` هرتز. مطلوب لإعادة التلوين (inpainting).

mask (*torch.Tensor*، *اختياري*) : قناع فضاء الكمون لكل إطار `(batch, 1, L)` حيث 0 = منطقة إعادة الرسم، و1 = الحفظ. يجب تقديم `mask` أو `mask_start_seconds` / `mask_end_seconds`.

mask_start_seconds (*float* أو *list[float]*، *اختياري*) : وقت(أوقات) بداية منطقة إعادة الرسم بالثواني.

mask_end_seconds (*float* أو *list[float]*، *اختياري*) : وقت(أوقات) نهاية منطقة إعادة الرسم (يجب أن يقترن مع `mask_start_seconds`).

num_inference_steps (*int*، *اختياري*) : عدد خطوات إزالة الضوضاء. عند تعيين `None` (الافتراضي)، يتم اختيار عدد الخطوات من إعداد *stochastic_sampling* الخاص بمجدول التنفيذ، بما يتوافق مع [*StableAudio3Pipeline*].

logsnr_min (*float*، القيمة الافتراضية -6.2) : الحد الأدنى لقيمة log-SNR في جدول الضوضاء — يتوافق مع بداية الجدول ذات الضوضاء العالية.

logsnr_max (*float*، القيمة الافتراضية 2.0) : القيمة القصوى لـ log-SNR في جدول الضوضاء — تُطابق الطرف منخفض الضوضاء من الجدول.

silence_padding_duration (*float*، القيمة الافتراضية 0.0) : مساحة إضافية في الرأس الكامن بعد المحتوى المستهدف.

num_waveforms_per_prompt (*int*، القيمة الافتراضية 1) : عدد الموجات الصوتية لكل موجه.

generator : مولّد الأرقام العشوائية (RNG) لضمان قابلية التكرار.

latents : ضوضاء البداية المُولَّدة مسبقًا (`None` → عيّنة جديدة).

prompt_embeds : تمثيلات نصية محسوبة مسبقًا.

encoder_attention_mask : قناع للتضمينات المحسوبة مسبقًا.

return_dict (*bool*، القيمة الافتراضية *True*) : إرجاع *AudioPipelineOutput* أو tuple.

callback_on_step_end (*Callable*، *اختياري*) : يُستدعى في نهاية كل خطوة إزالة ضوضاء مع *(self, step_idx, timestep, callback_kwargs)*. يجب أن يعيد قاموسًا يحتوي على المصفوفات (المعدّلة اختياريًا) لاستخدامها في بقية الحلقة.

callback_on_step_end_tensor_inputs (*list[str]*، الافتراضي *["latents"]*) : المصفوفات التي تُمرَّر إلى *callback_on_step_end*. يجب أن تكون مجموعة فرعية من *self._callback_tensor_inputs*.

output_type (*str*، الافتراضي `"pt"`) : `"pt"` / `"np"` / `"latent"`.

**يعيد:**

[*~pipelines.AudioPipelineOutput*] مع `.audios`.

إنشاء صوت مُعالَج مشروط على موجه نصي ومرجع.

أمثلة:
```py
>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3InpaintPipeline

>>> pipe = StableAudio3InpaintPipeline.from_pretrained(
...     "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     audio=audio,
...     mask_start_seconds=4.0,
...     mask_end_seconds=6.0,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)
```

#### encode_duration[[diffusers.StableAudio3InpaintPipeline.encode_duration]]

```python
encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L290)

**المعاملات:**

duration : المدة بالثواني، تُطبَّق على كل عينة في الدفعة.

device : جهاز الهدف.

num_waveforms_per_prompt : معامل البلاطات.

batch_size : عدد الأوامر.

**يعيد:**

مصفوفة `(batch * num_waveforms_per_prompt, output_dim)`.

Embed قيمة المدة في متجه الشروط العام.

#### encode_prompt[[diffusers.StableAudio3InpaintPipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L223)

**المعاملات:**

prompt : موجه نصي أو قائمة من الموجهات. يتم تجاهله عند توفير `prompt_embeds`.

device : جهاز الهدف.

num_waveforms_per_prompt : عدد موجات الإخراج التي سيتم توليدها لكل موجه؛ حيث يتم تكرار متجهات الشرط (conditioning tensors) وفقًا لذلك.

prompt_embeds : تمثيلات نصية محسوبة مسبقًا `(batch, seq_len, hidden_size)`.

encoder_attention_mask : قناع منطقي `(batch, seq_len)` للتضمينات المحسوبة مسبقًا؛ `1` = رمز حقيقي، `0` = حشو.

**يعيد:**

`(prompt_embeds, encoder_attention_mask)` كلاهما مُوسَّع إلى `batch * num_waveforms_per_prompt`.

ترميز موجهات النص إلى متجهات شروط الانتباه المتقاطع.

#### prepare_cross_attention[[diffusers.StableAudio3InpaintPipeline.prepare_cross_attention]]

```python
prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L315)

**يعيد:**

`(context, context_mask)` بأشكال `(batch, T_text + 1, dim)` و`(batch, T_text + 1)`.

قم ببناء سياق الانتباه المتقاطع (cross-attention context) عن طريق إضافة تضمين المدة (duration embedding) كرمز إضافي.

يوجّه SA3 مُشكّل `seconds_total` إلى *كلا* المدخل العام (AdaLN) وسياق الانتباه المتقاطع (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). يتم دمج تضمين المدة بعد رموز النص، ويُمدَّد قناع الانتباه بإدخال صالح واحد.

## StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]]

يولّد نسخة متغيّرة من مقطع صوتي مرجعي: يُضاف ضجيج إلى المرجع بأكمله بمستوى `init_noise_level` ثم يُزال الضجيج منه، على عكس [StableAudio3InpaintPipeline](/docs/diffusers/main/ar/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline) الذي يستخدم تكييفًا محليًا إضافيًا لكل إطار يحافظ على إطارات محددة بدقة.

#### diffusers.StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]]

```python
diffusers.StableAudio3AudioToAudioPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L154)

**المعاملات:**

vae ([*AutoencoderSAME*]) : مُشفِّر-مفكِّك SAME المستخدم لتشفير وفك تشفير الكامنات الصوتية.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : مُشفِّر نصوص T5Gemma مجمّد (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : مُجزِّئ (Tokenizer) لمُشفِّر النص.

duration_embedder ([*StableAudio3DurationEmbedder*]) : يحوّل `duration` بالثواني إلى متجه تكييف عام لـ AdaLN في كل كتلة DiT.

transformer ([*StableAudio3DiTModel*]) : نموذج DiT للتنبؤ بسرعة التدفق المُصحَّح.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : مُجدول لحلقة إزالة الضوضاء التكرارية. يستخدم نقطة التفتيش (المُقطّرة) SA3 Medium للإنتاج *stochastic_sampling=True* لخطوات ذهاب وإياب عشوائية بالضبط 8 خطوات؛ بينما تستخدم نقطة التفتيش الأساسية غير المُقطّرة *stochastic_sampling=False* لحوالي 100 خطوة أويلر حتمية.

خط أنابيب لتوليد تنويعات صوتية من صوت إلى صوت لنموذج Stable Audio 3.

تشارك منطق النص إلى الصوت مع [*StableAudio3Pipeline*] (يُحافظ على مزامنتها عبر *# Copied from*). تشفّر الصوت المرجعي باستخدام مُشفّر SAME المُجمّد، وتخلطه مع ضوضاء جديدة وفقاً لـ`init_noise_level`، ثم تُزيل الضوضاء من هناك — الإشارة بأكملها تخضع لإضافة الضوضاء وإزالتها على مستوى شامل، على عكس التكييف الإضافي المحلي لكل إطار في [*StableAudio3InpaintPipeline*].

توسيع توقيع الاستدعاء (انظر إلى `__call__`): الصوت (*torch.Tensor* من الشكل `(batch, channels, samples)`): موجة الصوت المرجعية عند `vae.config.sampling_rate` هرتز. init_noise_level (*float*): مقدار الضوضاء التي يجب خلطها مع الإشارة المرجعية قبل إزالة الضوضاء. `1.0` = ضوضاء كاملة (ما يعادل النص إلى الصوت)؛ القيم الأقل تحتفظ بمزيد من الإشارة المرجعية.

#### __call__[[diffusers.StableAudio3AudioToAudioPipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, audio: typing.Optional[torch.Tensor] = None, init_noise_level: float = 1.0, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt')
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L424)

**المعاملات:**

prompt (*str* أو *list[str]*، *اختياري*) : موجهات النص.

duration (*float*، القيمة الافتراضية 10.0) : مدة الإخراج بالثواني. يجب أن تتطابق مع الصوت المرجعي.

audio (*torch.Tensor*، *اختياري*) : موجة مرجعية `(batch, channels, samples)` عند `vae.config.sampling_rate` هرتز. مطلوب.

init_noise_level (*float*، القيمة الافتراضية 1.0) : مستوى الضوضاء (ضمن `(0, 1]`) الذي يُخلط مع المرجع قبل إزالة الضوضاء: `x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise`. القيمة `1.0` تتخلّى عن المرجع بالكامل (ما يعادل [*StableAudio3Pipeline*])؛ بينما القيم الأقل تحتفظ تدريجياً بمزيد من بنية المرجع مع الاستمرار في تنفيذ العدد الكامل من الخطوات.

num_inference_steps (*int*، *اختياري*) : عدد خطوات إزالة الضوضاء. عند تعيين `None` (الافتراضي)، يتم اختيار عدد الخطوات من إعداد *stochastic_sampling* الخاص بمجدول التنفيذ، بما يتوافق مع [*StableAudio3Pipeline*].

logsnr_min (*float*، القيمة الافتراضية -6.2) : الحد الأدنى لقيمة log-SNR في جدول الضوضاء — يتوافق مع بداية الجدول ذات الضوضاء العالية.

logsnr_max (*float*، القيمة الافتراضية 2.0) : القيمة القصوى لـ log-SNR في جدول الضوضاء — تُطابق الطرف منخفض الضوضاء من الجدول.

silence_padding_duration (*float*، القيمة الافتراضية 0.0) : مساحة إضافية في الرأس الكامن بعد المحتوى المستهدف.

num_waveforms_per_prompt (*int*، القيمة الافتراضية 1) : عدد الموجات الصوتية لكل موجه.

generator : مولّد الأرقام العشوائية (RNG) لضمان قابلية التكرار.

latents : ضوضاء البداية المُولَّدة مسبقًا (`None` → عيّنة جديدة).

prompt_embeds : تمثيلات نصية محسوبة مسبقًا.

encoder_attention_mask : قناع للتضمينات المحسوبة مسبقًا.

return_dict (*bool*، القيمة الافتراضية *True*) : إرجاع *AudioPipelineOutput* أو tuple.

callback_on_step_end (*Callable*، *اختياري*) : يُستدعى في نهاية كل خطوة إزالة ضوضاء مع *(self, step_idx, timestep, callback_kwargs)*. يجب أن يعيد قاموسًا يحتوي على المصفوفات (المعدّلة اختياريًا) لاستخدامها في بقية الحلقة.

callback_on_step_end_tensor_inputs (*list[str]*، الافتراضي *["latents"]*) : المصفوفات التي تُمرَّر إلى *callback_on_step_end*. يجب أن تكون مجموعة فرعية من *self._callback_tensor_inputs*.

output_type (*str*، الافتراضي `"pt"`) : `"pt"` / `"np"` / `"latent"`.

**يعيد:**

[*~pipelines.AudioPipelineOutput*] مع `.audios`.

أنشئ تنويعًا صوتيًا مشروطًا على موجه نصي وموجة مرجعية.

أمثلة:
```py
>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3AudioToAudioPipeline

>>> pipe = StableAudio3AudioToAudioPipeline.from_pretrained(
...     "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     audio=audio,
...     init_noise_level=0.6,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)
```

#### encode_duration[[diffusers.StableAudio3AudioToAudioPipeline.encode_duration]]

```python
encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L287)

**المعاملات:**

duration : المدة بالثواني، تُطبَّق على كل عينة في الدفعة.

device : جهاز الهدف.

num_waveforms_per_prompt : معامل البلاطات.

batch_size : عدد الأوامر.

**يعيد:**

مصفوفة `(batch * num_waveforms_per_prompt, output_dim)`.

Embed قيمة المدة في متجه الشروط العام.

#### encode_prompt[[diffusers.StableAudio3AudioToAudioPipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L220)

**المعاملات:**

prompt : موجه نصي أو قائمة من الموجهات. يتم تجاهله عند توفير `prompt_embeds`.

device : جهاز الهدف.

num_waveforms_per_prompt : عدد موجات الإخراج التي سيتم توليدها لكل موجه؛ حيث يتم تكرار متجهات الشرط (conditioning tensors) وفقًا لذلك.

prompt_embeds : تمثيلات نصية محسوبة مسبقًا `(batch, seq_len, hidden_size)`.

encoder_attention_mask : قناع منطقي `(batch, seq_len)` للتضمينات المحسوبة مسبقًا؛ `1` = رمز حقيقي، `0` = حشو.

**يعيد:**

`(prompt_embeds, encoder_attention_mask)` كلاهما مُوسَّع إلى `batch * num_waveforms_per_prompt`.

ترميز موجهات النص إلى متجهات شروط الانتباه المتقاطع.

#### prepare_cross_attention[[diffusers.StableAudio3AudioToAudioPipeline.prepare_cross_attention]]

```python
prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L312)

**يعيد:**

`(context, context_mask)` بأشكال `(batch, T_text + 1, dim)` و`(batch, T_text + 1)`.

قم ببناء سياق الانتباه المتقاطع (cross-attention context) عن طريق إضافة تضمين المدة (duration embedding) كرمز إضافي.

يوجّه SA3 مُشكّل `seconds_total` إلى *كلا* المدخل العام (AdaLN) وسياق الانتباه المتقاطع (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). يتم دمج تضمين المدة بعد رموز النص، ويُمدَّد قناع الانتباه بإدخال صالح واحد.

## StableAudio3DurationEmbedder[[diffusers.StableAudio3DurationEmbedder]]

#### diffusers.StableAudio3DurationEmbedder[[diffusers.StableAudio3DurationEmbedder]]

```python
diffusers.StableAudio3DurationEmbedder(output_dim: int = 768, fourier_dim: int = 256, min_val: float = 0.0, max_val: float = 384.0, min_freq: float = 0.5, max_freq: float = 10000.0)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L43)

**المعاملات:**

output_dim (*int*، القيمة الافتراضية 768) : بُعد التضمين الناتج. يجب أن يتطابق مع `global_cond_dim` الخاص بـ DiT.

fourier_dim (*int*، القيمة الافتراضية 256) : بُعد ميزات فورييه الداخلية (يجب أن يكون زوجيًا).

min_val (*float*، القيمة الافتراضية 0.0) : الحد الأدنى لقيمة المدة المستخدمة في التقييد أثناء التطبيع.

max_val (*float*، القيمة الافتراضية 384.0) : القيمة القصوى للمدة المستخدمة في التقييد أثناء التطبيع. تُقيَّد القيم التي تتجاوز هذا الحد. يمثل 384 ثانية الحد الأعلى لمنتج SA3 Medium الشرطي `seconds_total`.

min_freq (*float*، القيمة الافتراضية 0.5) : الحد الأدنى للتردد في الأساس الأسي لدالة فورييه.

max_freq (*float*، القيمة الافتراضية 10000.0) : التردد الأقصى للأسس الأربعة (Fourier) الأسية.

يُضمّن قيمة المدة (بالثواني) في متجه شروط عام لنموذج Stable Audio 3 DiT (يُستخدم كمدخل `global_hidden_states` لـ AdaLN).

ينسخ `NumberConditioner(fourier_features_type="expo")` من التنفيذ المرجعي لـ SA3.

#### forward[[diffusers.StableAudio3DurationEmbedder.forward]]

```python
forward(seconds: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L90)

**المعاملات:**

seconds (`torch.Tensor` من الشكل `(batch,)`) : قيم المدد بالثواني.

**يعيد:**

`torch.Tensor` من الشكل `(batch, output_dim)` — تضمينات المدة.