> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# الإعدادات المسبقة

> تكوينات عرض قابلة لإعادة الاستخدام — إنشاء، تحديث، سرد، وتعيين الافتراضي للحساب

الإعداد المسبق هو تكوين عرض قابل لإعادة الاستخدام — الخلفية، نمط الترجمة، التخطيط — يمكنك تطبيقه على أي مشروع أو تصدير. استخدم الإعدادات المسبقة عندما تريد مظهراً متسقاً عبر العديد من المقاطع.

اطّلع على [مرجع إعدادات العرض](/en/render-settings-reference) للحصول على البنية الكاملة لـ
`preset` وكل خيار مدعوم بقيم enum.

## متى تستخدم إعداداً مسبقاً

<Columns cols={2}>
  <Card title="استخدم إعداداً مسبقاً عندما…" icon="check">
    تريد المظهر نفسه عبر العديد من المشاريع وتحتاج إلى تحديثه في مكان واحد.
  </Card>

  <Card title="استخدم إعدادات المشروع عندما…" icon="sliders" href="/ar/api/project-settings">
    تحتاج إلى تجاوزات محلية خاصة بالمشروع لا تستحق مشاركتها.
  </Card>
</Columns>

## نقاط النهاية

| Method   | Path                  | Purpose                                      |
| -------- | --------------------- | -------------------------------------------- |
| `GET`    | `/presets`            | سرد الإعدادات المسبقة للحساب المُصادَق عليه. |
| `POST`   | `/presets`            | إنشاء إعداد مسبق جديد.                       |
| `GET`    | `/presets/{presetId}` | جلب إعداد مسبق واحد.                         |
| `PATCH`  | `/presets/{presetId}` | تحديث الاسم أو المحتوى أو تعيينه كافتراضي.   |
| `DELETE` | `/presets/{presetId}` | حذف إعداد مسبق.                              |

تتوفر مخططات الطلب والاستجابة الكاملة ضمن **API reference** في الشريط الجانبي.

## إنشاء إعداد مسبق

```bash theme={null}
curl -X POST https://api.youka.io/ar/api/v1/presets \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: create-neon-night-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night",
    "preset": {
      "background": {
        "type": "gradient",
        "colors": ["#12001f", "#2f0a57"],
        "angle": 90
      },
      "singerTextStyles": {
        "0": {
          "fontFamily": "Inter",
          "textColor": "#00f5ff",
          "effectColor": "#ff4fd8"
        }
      }
    },
    "isDefault": false
  }'
```

تتضمن الاستجابة قيمة `presetId` الجديدة. خزّنها وأشِر إليها من المشاريع أو عمليات التصدير.

<Tip>
  اربط كل طلب `POST` بمفتاح idempotency. إعادة استخدام المفتاح نفسه مع الحمولة نفسها يُرجع الإعداد المسبق الأصلي بدلاً من إنشاء نسخة مكررة.
</Tip>

## اكتشاف حقول الإعداد المسبق الصالحة

تُتحقَّق الإعدادات المسبقة على جانب الخادم مقابل `KaraokePresetSchema`. تُصدّر SDK هذا المخطط لتتمكن من تحويله إلى JSON Schema وقت التشغيل:

```ts theme={null}
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
```

من خلال CLI:

```bash theme={null}
youka preset schema --json
```

ينبغي لمؤلفي الوكلاء استدعاء هذا قبل تعديل الإعدادات المسبقة حتى يعرف النموذج كل حقل صالح ونوع قيمته.

مرجع سهل القراءة:

* [مرجع إعدادات العرض](/en/render-settings-reference)
* [إعدادات CLI المسبقة](/ar/cli/presets)
* [إعدادات SDK المسبقة](/ar/sdk/presets)

## تحديث إعداد مسبق

```bash theme={null}
curl -X PATCH https://api.youka.io/ar/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night v2",
    "preset": {
      "singerTextStyles": {
        "0": {
          "textColor": "#ff2a2a"
        }
      }
    }
  }'
```

مرّر أي مجموعة فرعية من `name` و`preset`. الحقول التي لا تُضمّنها تبقى دون تغيير.

## تعيين الإعداد المسبق الافتراضي

لكل حساب إعداد مسبق افتراضي واحد كحد أقصى، ويُطبَّق تلقائياً على المشاريع الجديدة.

```bash theme={null}
curl -X PATCH https://api.youka.io/ar/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isDefault": true
  }'
```

يؤدي تعيين افتراضي جديد إلى إلغاء تعيين السابق تلقائياً.

## تطبيق إعداد مسبق

أشِر إلى إعداد مسبق في ثلاثة مواضع:

| Where                 | Field                                                |
| --------------------- | ---------------------------------------------------- |
| عند إنشاء المشروع     | `presetId` في `POST /projects`                       |
| في أي وقت على المشروع | `presetId` في `PATCH /projects/{projectId}/settings` |
| وقت التصدير           | `presetId` في `POST /projects/{projectId}/exports`   |

مثال عند التصدير:

```bash theme={null}
curl -X POST https://api.youka.io/ar/api/v1/projects/prj_abc/exports \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset_abc123",
    "resolution": "1080p",
    "quality": "high"
  }'
```

## حذف إعداد مسبق

```bash theme={null}
curl -X DELETE https://api.youka.io/ar/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"
```

<Warning>
  حذف إعداد مسبق لا يؤثر على المشاريع أو عمليات التصدير التي تم عرضها سابقاً باستخدامه. ستفشل عمليات التصدير المستقبلية التي تشير إلى الإعداد المسبق المحذوف.
</Warning>

## ما التالي

* [مرجع إعدادات العرض](/en/render-settings-reference) — جميع مسارات الحقول المشتركة وقيم enum
* [الوسائط](/ar/api/media) — يُشار إليها من داخل محتويات الإعداد المسبق
* [إعدادات المشروع](/ar/api/project-settings) — تطبيق إعداد مسبق على مشروع
* [إعدادات CLI المسبقة](/ar/cli/presets) — نفس التدفق من الطرفية
* [إعدادات SDK المسبقة](/ar/sdk/presets) — نفس نقاط النهاية في TypeScript