> ## 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/sdk`.

## قبل أن تبدأ

* Node.js 20 أو أحدث
* مفتاح Youka API في `YOUKA_API_KEY` (أنشئ واحدًا على [online.youka.io/account](https://online.youka.io/account) ضمن **API keys**)
* ملف صوتي محلي (`./song.mp3`) أو رابط URL بعيد

## التثبيت

```bash theme={null}
npm install @youka/sdk
```

## إنشاء، انتظار، تصدير

```ts theme={null}
import { YoukaClient, YoukaRequestError, YoukaTaskError } from "@youka/sdk";

const client = new YoukaClient({
  apiKey: process.env.YOUKA_API_KEY!,
});

async function main() {
  // 1. Create a project from a local file
  const projectOperation = await client.projects.create({
    source: { type: "path", path: "./song.mp3" },
    lyricsSource: { type: "transcribe" },
  });

  // 2. Wait for stems and lyrics sync to finish
  const { project } = await client.projects.wait(projectOperation);
  console.log("Project ready:", project.id, project.title);

  // 3. Start an export
  const exportOperation = await client.exports.create(project.id, {
    resolution: "1080p",
    quality: "high",
  });

  // 4. Wait for the export to finish
  const finishedExport = await client.exports.wait(exportOperation);
  await client.exports.download(finishedExport, {
    output: "./exports",
  });
  console.log("Export ready:", finishedExport.url);
}

main().catch((error) => {
  if (error instanceof YoukaRequestError) {
    console.error("Request failed:", error.code, error.status, error.message);
    process.exit(1);
  }
  if (error instanceof YoukaTaskError) {
    console.error("Task failed:", error.code, error.status, error.message);
    process.exit(1);
  }
  throw error;
});
```

<Note>
  يتولى `client.projects.create()` رفع المصادر من نوع `path` و`bytes` و`url`.
  ولتحكم أدنى مستوى في الرفع، استخدم `client.uploads.*`.
</Note>

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

<Tabs>
  <Tab title="ملف محلي">
    ```ts theme={null}
    const operation = await client.projects.create({
      source: { type: "path", path: "./song.mp3" },
    });
    ```
  </Tab>

  <Tab title="بايتات في الذاكرة">
    ```ts theme={null}
    const fileBuffer = new Uint8Array([/* audio bytes */]);

    const operation = await client.projects.create({
      source: {
        type: "bytes",
        data: fileBuffer,
        filename: "song.mp3",
      },
    });
    ```
  </Tab>

  <Tab title="رابط URL بعيد">
    ```ts theme={null}
    const operation = await client.projects.create({
      source: {
        type: "url",
        url: "https://example.com/song.mp4",
      },
    });
    ```
  </Tab>
</Tabs>

## ماذا بعد

* [Projects](/ar/sdk/projects) — واجهة برمجة التطبيقات الكاملة للمشاريع
* [Exports](/ar/sdk/exports) — الإخراج المحلي و`client.exports.prepareLocal`
* [Errors](/ar/sdk/errors) — التعامل مع `YoukaRequestError` و`YoukaTaskError`
* [AI agents](/ar/agents) — أنماط الاستقصاء وإعادة المحاولة الموصى بها