المشاريع

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

إنشاء مشروع

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

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

أنواع المصدر

path
bytes
url

يقرأ ملفًا من القرص.

source: {
  type: "path",
  path: "./song.mp3",
  contentType: "audio/mpeg", // optional, inferred if omitted
}

Blob أو File أو ArrayBuffer أو Uint8Array داخل الذاكرة.

source: {
  type: "bytes",
  data: fileBuffer,
  filename: "song.mp3",
  contentType: "audio/mpeg", // optional
}

عنوان URL بعيد عبر HTTP أو HTTPS.تعتمد صفحات الاستضافة المدعومة على yt-dlp. راجع قائمة عناوين URL المدعومة.

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

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

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

حقول أخرى

string

عنوان المشروع. الافتراضي هو اسم ملف المصدر.

SplitModel

نموذج فصل المسارات (stems). الافتراضي هو mdx23c. راجع مرجع نموذج الفصل.

string

طبّق إعدادًا مسبقًا قابلًا لإعادة الاستخدام عند وقت الإنشاء.

LyricsSource

إعداد مزامنة كلمات الأغاني. انظر أدناه.

مصادر كلمات الأغاني

// 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 لملف تم رفعه.

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?)`

قدّر الاعتمادات المطلوبة لإنشاء مشروع دون إنشائه.

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 منخفضة المستوى:

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

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

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

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 الموقّع.

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

FetchBody

required

أي جسم متوافق مع fetch: Blob أو File أو ArrayBuffer أو Uint8Array أو ReadableStream أو string.

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

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

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

const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);

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

حدّث بيانات تعريف المشروع (Patch).

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

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

`client.projects.list(options?)`

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

const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));

تُرجع مصفوفة من عناصر قائمة المشاريع (بصيغة أخف من getProject).

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

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

await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});

الحذف نهائي. اقترن بمفتاح idempotency حتى تكون إعادة المحاولة آمنة.

ما التالي

Stems — أعد تشغيل فصل المسارات (stems)
Lyrics sync — أعد مزامنة كلمات الأغاني
Exports — اعرض الفيديوهات النهائية
Tasks — انتظر عمليات المشروع باستخدام client.projects.wait

Overview

How To

Customization

Audio

Settings

Exporting

Account

إنشاء مشروع

أنواع المصدر

حقول أخرى

مصادر كلمات الأغاني

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

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

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

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

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

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

`client.projects.list(options?)`

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

ما التالي

​إنشاء مشروع

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

​حقول أخرى

​مصادر كلمات الأغاني

​client.projects.create(input, options?)

​client.projects.quote(input, options?)

​client.uploads.create(body, options?)

​client.uploads.upload(uploadUrl, body, options?)

​client.projects.get(projectId, options?)

​client.projects.update(projectId, body, options?)

​client.projects.list(options?)

​client.projects.delete(projectId, options?)

​ما التالي

إنشاء مشروع

أنواع المصدر

حقول أخرى

مصادر كلمات الأغاني

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

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

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

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

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

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

`client.projects.list(options?)`

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

ما التالي