# Stable Audio

قُدم Stable Audio في [Stable Audio Open](https://huggingface.co/papers/2407.14358) من قِبل Zach Evans وآخرون. يستقبل هذا النموذج نصًا كمدخل ويتنبأ بعينة الصوت أو الموسيقى المقابلة له.

يولّد Stable Audio Open صوتًا ستيريو بطول متغيّر (حتى 47 ثانية) بمعدل عينة 44.1kHz انطلاقًا من أوامر نصية. يتكوّن من ثلاثة مكوّنات: مُشفِّر ذاتي (autoencoder) يضغط الموجات الصوتية إلى طول تسلسل قابل للإدارة، وتضمين نصي مبني على T5 لتكييف النص، ونموذج انتشار (diffusion) مبني على محوّل (transformer) (DiT) يعمل في الفضاء الكامن (latent space) للمُشفِّر الذاتي.

يتم تدريب Stable Audio على مجموعة بيانات تضم حوالي 48 ألف تسجيل صوتي، حيث أن حوالي 47 ألفًا منها من Freesound والباقي من Free Music Archive (FMA). جميع الملفات الصوتية مرخصة بموجب CC0 أو CC BY أو CC Sampling+. تُستخدم هذه البيانات لتدريب مُشفِّر-مُفكِّك الترميز التلقائي (autoencoder) و DiT.

ملخص الورقة البحثية هو التالي: *تُعدّ النماذج التوليدية المفتوحة ذات أهمية حيوية للمجتمع، إذ تتيح إجراء الضبط الدقيق وتعمل كخطوط أساس عند تقديم نماذج جديدة. ومع ذلك، فإن معظم نماذج النص إلى الصوت الحالية خاصة وغير متاحة للفنانين والباحثين لبناء أعمالهم عليها. هنا، نصف بنية وعملية تدريب نموذج نص إلى صوت جديد مفتوح الأوزان، تم تدريبه باستخدام بيانات مرخصة بموجب المشاع الإبداعي. تُظهر تقييماتنا أن أداء النموذج تنافسي مع أحدث التقنيات عبر مقاييس متنوعة. ومن اللافت للنظر أن نتائج FDopenl3 المُبلَّغ عنها (والتي تقيس واقعية المخرجات) تُبرز إمكاناته في توليد صوت ستيريو عالي الجودة بمعدل عينة 44.1kHz.*

تمت مساهمة خط المعالجة هذا من قِبل [Yoach Lacombe](https://huggingface.co/ylacombe). يمكن العثور على قاعدة الكود الأصلية في [Stability-AI/stable-audio-tools](https://github.com/Stability-AI/stable-audio-tools).

## نصائح

عند إنشاء موجه، ضع في اعتبارك:

* تعمل مدخلات الأوامر الوصفية بشكل أفضل؛ استخدم الصفات لوصف الصوت (على سبيل المثال، "جودة عالية" أو "واضح") واجعل الأمر محددًا في سياقه قدر الإمكان (على سبيل المثال، "تكنو إيقاعي بإيقاع سريع وسينث" يعمل بشكل أفضل من "تكنو").
* يمكن أن يحسّن استخدام *موجّه سلبي* بشكل كبير من جودة الصوت المولّد. جرّب استخدام موجّه سلبي هو "low quality, average quality".

أثناء الاستدلال:

* يمكن التحكم في _الجودة_ لعينة الصوت المولّدة عبر الحجة `num_inference_steps`؛ فزيادة عدد الخطوات تمنح صوتاً بجودة أعلى على حساب بطء الاستدلال.
* يمكن توليد عدة موجات صوتية دفعة واحدة: اضبط `num_waveforms_per_prompt` على قيمة أكبر من 1 لتفعيل ذلك. سيتم إجراء تقييم تلقائي بين الموجات الصوتية المولّدة ونص الأمر، ثم ترتيب المقاطع الصوتية من الأفضل إلى الأسوأ بناءً على ذلك.

## التكميم

يساعد التكميم (Quantization) في تقليل متطلبات الذاكرة للنماذج الكبيرة جدًا من خلال تخزين أوزان النموذج في نوع بيانات بدقة أقل. ومع ذلك، قد يكون للتكميم تأثير متباين على جودة الفيديو اعتمادًا على نموذج الفيديو المستخدم.

راجع نظرة عامة حول [التكميم](../../quantization/overview) لمعرفة المزيد حول محركات التكميم المدعومة واختيار محرك تكميم يدعم حالتك الاستخدامية. يوضح المثال أدناه كيفية تحميل [StableAudioPipeline](/docs/diffusers/main/ar/api/pipelines/stable_audio#diffusers.StableAudioPipeline) مُكمَّم للاستدلال باستخدام bitsandbytes.

```py
import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, StableAudioDiTModel, StableAudioPipeline
from diffusers.utils import export_to_video
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    subfolder="text_encoder",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = StableAudioDiTModel.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = StableAudioPipeline.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "The sound of a hammer hitting a wooden surface."
negative_prompt = "Low quality."
audio = pipeline(
    prompt,
    negative_prompt=negative_prompt,
    num_inference_steps=200,
    audio_end_in_s=10.0,
    num_waveforms_per_prompt=3,
    generator=generator,
).audios

output = audio[0].T.float().cpu().numpy()
sf.write("hammer.wav", output, pipeline.vae.sampling_rate)
```

## StableAudioPipeline[[diffusers.StableAudioPipeline]]

#### diffusers.StableAudioPipeline[[diffusers.StableAudioPipeline]]

```python
diffusers.StableAudioPipeline(vae: AutoencoderOobleck, text_encoder: T5EncoderModel, projection_model: StableAudioProjectionModel, tokenizer: T5Tokenizer, transformer: StableAudioDiTModel, scheduler: EDMDPMSolverMultistepScheduler)
```

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

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

vae ([AutoencoderOobleck](/docs/diffusers/main/ar/api/models/autoencoder_oobleck#diffusers.AutoencoderOobleck)) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير الصور إلى تمثيلات كامنة ومنها.

text_encoder ([T5EncoderModel](https://huggingface.co/docs/transformers/main/en/model_doc/t5#transformers.T5EncoderModel)) : مُشفِّر نص ثابت. يستخدم StableAudio مُشفِّر [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel)، وتحديداً النسخة [google-t5/t5-base](https://huggingface.co/google-t5/t5-base).

projection_model (`StableAudioProjectionModel`) : نموذج مُدرَّب يُستخدم لإسقاط الحالات المخفية (hidden-states) من نموذج مُشفِّر النص، وكذلك ثواني البداية والنهاية، إسقاطًا خطيًا. يتم دمج الحالات المخفية المُسقطة من المُشفِّر مع ثواني الشرط (conditional seconds) لتكوين مدخلات نموذج الترانسفورمر.

tokenizer ([T5Tokenizer](https://huggingface.co/docs/transformers/main/en/model_doc/t5#transformers.T5Tokenizer)) : مُجزِّئ (Tokenizer) لتجزئة النص الخاصّ بمُشفِّر النص (text-encoder) المُجمَّد.

transformer ([StableAudioDiTModel](/docs/diffusers/main/ar/api/models/stable_audio_transformer#diffusers.StableAudioDiTModel)) : نموذج `StableAudioDiTModel` لإزالة الضوضاء من الكائنات الصوتية المشفّرة.

scheduler ([EDMDPMSolverMultistepScheduler](/docs/diffusers/main/ar/api/schedulers/edm_multistep_dpm_solver#diffusers.EDMDPMSolverMultistepScheduler)) : مُجدول يُستخدم بالاقتران مع `transformer` لإزالة الضوضاء من الكامنات الصوتية المُرمّزة.

خط أنابيب لتوليد الصوت من النص باستخدام StableAudio.

يرث هذا النموذج من [DiffusionPipeline](/docs/diffusers/main/ar/api/pipelines/overview#diffusers.DiffusionPipeline). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).

#### __call__[[diffusers.StableAudioPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, audio_end_in_s: float | None = None, audio_start_in_s: float | None = 0.0, num_inference_steps: int = 100, guidance_scale: float = 7.0, negative_prompt: str | list[str] | None = None, num_waveforms_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, initial_audio_waveforms: typing.Optional[torch.Tensor] = None, initial_audio_sampling_rate: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, negative_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: int | None = 1, output_type: str | None = 'pt')
```

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

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

prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر الموجِّهة لتوليد الصوت. إذا لم يُعرَّف، يجب عليك تمرير `prompt_embeds`.

audio_end_in_s (`float`، *اختياري*، القيمة الافتراضية 47.55) : مؤشر نهاية الصوت بالثواني.

audio_start_in_s (`float`، *اختياري*، القيمة الافتراضية 0) : فهرس بداية الصوت بالثواني.

num_inference_steps (`int`، *اختياري*، القيمة الافتراضية 100) : عدد خطوات إزالة الضوضاء. تؤدي زيادة عدد خطوات إزالة الضوضاء عادةً إلى جودة صوتية أعلى على حساب بطء الاستدلال.

guidance_scale (`float`، *اختياري*، القيمة الافتراضية 7.0) : كلما ارتفعت قيمة مقياس التوجيه، شجّع النموذج على توليد صوت مرتبط ارتباطًا وثيقًا بنص `prompt` على حساب انخفاض جودة الصوت. يتم تفعيل مقياس التوجيه عندما يكون `guidance_scale > 1`.

negative_prompt (`str` أو `list[str]`، *اختياري*) : الأمر أو الأوامر التي توجّه ما يجب عدم تضمينه في توليد الصوت. إذا لم يُعرَّف، يجب عليك تمرير `negative_prompt_embeds` بدلاً من ذلك. يتم تجاهله عند عدم استخدام التوجيه (`guidance_scale < 1`).

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

eta (`float`، *اختياري*، القيمة الافتراضية 0.0) : يتوافق مع المعامل eta (η) من ورقة [DDIM](https://huggingface.co/papers/2010.02502). ينطبق فقط على [DDIMScheduler](/docs/diffusers/main/ar/api/schedulers/ddim#diffusers.DDIMScheduler)، ويُتجاهل في جدولة أخرى.

generator (`torch.Generator` أو `list[torch.Generator]`، *اختياري*) : [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) لجعل التوليد حتميًا.

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

initial_audio_waveforms (`torch.Tensor`، *اختياري*) : موجات صوتية أولية اختيارية لاستخدامها كموجة صوتية أولية للتوليد. يجب أن تكون من الشكل `(batch_size, num_channels, audio_length)` أو `(batch_size, audio_length)`، حيث يتوافق `batch_size` مع عدد الأوامر (prompts) الممررة إلى النموذج.

initial_audio_sampling_rate (`int`, *اختياري*) : معدل أخذ العينات لـ`initial_audio_waveforms`، إذا تم توفيرها. يجب أن يكون مطابقًا لنموذج.

prompt_embeds (`torch.Tensor`، *اختياري*) : تمثيلات نصية محسوبة مسبقًا من نموذج مُرمِّز النص. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم حساب التمثيلات النصية من معامل الإدخال `prompt`.

negative_prompt_embeds (`torch.Tensor`, *اختياري*) : تمثيلات نصية سالبة محسوبة مسبقًا من نموذج ترميز النص. يمكن استخدامها لتعديل مدخلات النص بسهولة، *مثلًا* وزن الأوامر. إذا لم تُقدَّم، فسيتم حساب negative_prompt_embeds من معامل الإدخال `negative_prompt`.

attention_mask (`torch.LongTensor`، *اختياري*) : قناع الانتباه المُحسب مسبقًا الذي سيُطبَّق على `prompt_embeds`. إذا لم يُوفَّر، فسيتم حساب قناع الانتباه من معامل الإدخال `prompt`.

negative_attention_mask (`torch.LongTensor`، *اختياري*) : قناع الانتباه المُحسب مسبقًا الذي سيُطبَّق على `negative_text_audio_duration_embeds`.

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [StableDiffusionPipelineOutput](/docs/diffusers/main/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) بدلاً من tuple عادي.

callback (`Callable`، *اختياري*) : دالة تُستدعى كل `callback_steps` خطوات أثناء الاستدلال. تُستدعى الدالة بالحجج التالية: `callback(step: int, timestep: int, latents: torch.Tensor)`.

callback_steps (`int`، *اختياري*، القيمة الافتراضية 1) : التكرار الذي تُستدعى فيه دالة `callback`. إذا لم يُحدد، تُستدعى الدالة في كل خطوة.

output_type (`str`، *اختياري*، القيمة الافتراضية `"pt"`) : صيغة مخرجات الصوت المولّد. اختر بين `"np"` لإرجاع مصفوفة NumPy `np.ndarray` أو `"pt"` لإرجاع كائن PyTorch `torch.Tensor`. اضبطه على `"latent"` لإرجاع مخرجات نموذج الانتشار الكامن (LDM).

**يعيد:** [StableDiffusionPipelineOutput](/docs/diffusers/main/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) أو `tuple`

إذا كان `return_dict` هو `True`، يُعاد [StableDiffusionPipelineOutput](/docs/diffusers/main/ar/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)، وإلا يُعاد `tuple` حيث يكون العنصر الأول قائمة تحتوي على الصوت المولّد.

دالة الاستدعاء call لخط الأنابيب pipeline الخاص بالتوليد.

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

>>> repo_id = "stabilityai/stable-audio-open-1.0"
>>> pipe = StableAudioPipeline.from_pretrained(repo_id, torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")

>>> # define the prompts
>>> prompt = "The sound of a hammer hitting a wooden surface."
>>> negative_prompt = "Low quality."

>>> # set the seed for generator
>>> generator = torch.Generator("cuda").manual_seed(0)

>>> # run the generation
>>> audio = pipe(
...     prompt,
...     negative_prompt=negative_prompt,
...     num_inference_steps=200,
...     audio_end_in_s=10.0,
...     num_waveforms_per_prompt=3,
...     generator=generator,
... ).audios

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