> ## 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.

# المشاريع

> ارفع الوسائط وأنشئ مشاريع الكاريوكي وتفقّدها واعرضها واحذفها

المشاريع هي المورد الأعلى مستوى في Youka. يمتلك كل مشروع ملفه المصدر، والمسارات المفصولة (stems)، وكلمات الأغاني المتزامنة، وعمليات التصدير، وإعدادات المشروع.

## إنشاء مشروع

في معظم الحالات، استخدم `client.projects.create()` — فهو يتولى رفع الملفات نيابةً عنك.

```ts theme={null}
const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
});
// => ProjectOperation
```

### أنواع المصدر

<Tabs>
  <Tab title="path">
    يقرأ ملفًا من القرص.

    ```ts theme={null}
    source: {
      type: "path",
      path: "./song.mp3",
      contentType: "audio/mpeg", // optional, inferred if omitted
    }
    ```
  </Tab>

  <Tab title="bytes">
    `Blob` أو `File` أو `ArrayBuffer` أو `Uint8Array` في الذاكرة.

    ```ts theme={null}
    source: {
      type: "bytes",
      data: fileBuffer,
      filename: "song.mp3",
      contentType: "audio/mpeg", // optional
    }
    ```
  </Tab>

  <Tab title="url">
    عنوان URL بعيد عبر HTTP أو HTTPS.

    تعتمد الصفحات المستضافة المدعومة على yt-dlp. راجع [قائمة عناوين URL المدعومة](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md).

    ```ts theme={null}
    source: {
      type: "url",
      url: "https://example.com/song.mp4",
      maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
    }
    ```

    يتحكم `maxVideoQuality` في الحد الأقصى لجودة الفيديو التي يتم تنزيلها لمصادر
    URL. القيمة الافتراضية هي `1080p`. يستخدم الـ SDK أفضل جودة متاحة حتى
    ذلك الحد، ويعود إلى أفضل تنسيق متاح إذا لم توفر المنصة بثًا
    محدودًا. استخدم `best` بدون حد.

    <Note>
      على Node.js و Bun، يضمن الـ SDK تلقائيًا توفر ملفات الاعتماد الثنائية المطلوبة لمصادر URL
      (`ffmpeg`, `ffprobe`, `yt-dlp`) عند أول استخدام. المعادل في
      CLI هو `youka deps ensure --for url`.
    </Note>
  </Tab>
</Tabs>

### حقول أخرى

<ParamField path="title" type="string">
  عنوان المشروع. القيمة الافتراضية هي اسم ملف المصدر.
</ParamField>

<ParamField path="splitModel" type="SplitModel">
  نموذج فصل المسارات (stems). الافتراضي هو `mdx23c`. راجع [مرجع نموذج
  الفصل](/ar/desktop/split-model).
</ParamField>

<ParamField path="presetId" type="string">
  تطبيق إعداد مسبق قابل لإعادة الاستخدام وقت الإنشاء.
</ParamField>

<ParamField path="lyricsSource" type="LyricsSource">
  إعداد مزامنة الكلمات. انظر أدناه.
</ParamField>

### مصادر الكلمات

```ts theme={null}
// Transcribe lyrics from the audio
lyricsSource: {
  type: "transcribe",
  syncModel: "audioshake-transcription", // optional
  language: "en",                        // optional
}

// Align exact lyrics to the audio
lyricsSource: {
  type: "align",
  lyrics: "First line\nSecond line\n...",
  syncModel: "audioshake-alignment",
}

```

## `client.projects.create(input, options?)`

يدعم `client.projects.create()` أيضًا مصدرًا منخفض المستوى من نوع `inputFile` عندما يكون لديك بالفعل `inputFileId` لملف تم رفعه مسبقًا.

```ts theme={null}
const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: buffer.byteLength,
});

await client.uploads.upload(upload.uploadUrl, buffer, {
  contentType: "audio/mpeg",
});

const operation = await client.projects.create({
  source: {
    type: "inputFile",
    inputFileId: upload.inputFileId,
    filename: "song.mp3",
  },
  title: "My Song",
});
```

## `client.projects.quote(input, options?)`

احسب رصيد الاعتمادات المطلوب لإنشاء مشروع دون إنشائه.

```ts theme={null}
const quote = await client.projects.quote({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe", language: "en" },
  splitModel: "mdx23c",
});

console.log(quote.creditsRequired, quote.sufficientBalance);
```

يقبل `client.projects.quote(...)` نفس أشكال `source` التي يقبلها
`client.projects.create(...)`، بما في ذلك `maxVideoQuality` لمصادر URL. إذا كنت
تعرف مدة الوسائط مسبقًا ولا تريد رفع الملف فقط لغرض التسعير، مرّر
الشكل منخفض المستوى الخاص بـ REST:

```ts theme={null}
const quote = await client.projects.quote({
  durationSeconds: 210,
  lyricsSource: null,
  splitModel: "mdx23c",
});
```

## `client.uploads.create(body, options?)`

خصّص خانة رفع واحصل على عنوان URL موقّع.

```ts theme={null}
const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }
```

## `client.uploads.upload(uploadUrl, body, options?)`

نفّذ PUT لبايتات الملف إلى عنوان URL الموقّع.

```ts theme={null}
await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});
```

<ParamField path="body" type="FetchBody" required>
  أي جسم متوافق مع `fetch`: `Blob`, `File`, `ArrayBuffer`, `Uint8Array`,
  `ReadableStream`, أو `string`.
</ParamField>

يرمي `YoukaRequestError` بالرمز `UPLOAD_FAILED` إذا أعادت عملية الرفع حالة ليست 2xx.

## `client.projects.get(projectId, options?)`

اجلب حالة المشروع كاملة، بما في ذلك المسارات (stems) والكلمات وعمليات التصدير.

```ts theme={null}
const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);
```

## `client.projects.update(projectId, body, options?)`

طبّق Patch على بيانات تعريف المشروع.

```ts theme={null}
const project = await client.projects.update("prj_abc123", {
  title: "Updated title",
  artists: ["Artist name"],
});
```

مرّر واحدًا على الأقل من `title` أو `artists`.

## `client.projects.list(options?)`

اعرض كل مشروع مملوك للحساب الذي تمّت مصادقته.

```ts theme={null}
const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));
```

يعيد مصفوفة من عناصر قائمة المشاريع (ببنية أخف من `getProject`).

## `client.projects.delete(projectId, options?)`

احذف مشروعًا وكل ما يرتبط به من مسارات (stems) وكلمات وعمليات تصدير.

```ts theme={null}
await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});
```

<Warning>
  الحذف نهائي. اربطه بمفتاح idempotency لكي تكون إعادة المحاولة آمنة.
</Warning>

## ما التالي

* [المسارات (Stems)](/ar/sdk/stems) — أعد تشغيل فصل المسارات
* [مزامنة الكلمات](/ar/sdk/lyrics-sync) — أعد مزامنة الكلمات
* [عمليات التصدير](/ar/sdk/exports) — اعرض الفيديوهات النهائية
* [المهام](/ar/sdk/tasks) — انتظر عمليات المشروع باستخدام `client.projects.wait`