> ## 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` और `@youka/cli` का संस्करण 0.2.0 या बाद का उपयोग करें। API के माध्यम से बनाए गए प्रोजेक्ट आपकी Youka लाइब्रेरी में उपलब्ध रहते हैं।

## वर्कफ़्लो और मॉडल चुनें

`kind` प्रोजेक्ट वर्कफ़्लो चुनता है। `karaoke` स्टेम्स अलग करता है। `lyric-video` मूल ऑडियो का उपयोग करता है और separation के लिए शुल्क नहीं लेता। `kind` छोड़ने पर मौजूदा karaoke व्यवहार बना रहता है। Lyrics processing, alignment, transcription, या no processing में से अलग विकल्प है।

मॉडल चुनने से पहले मॉडल और अकाउंट eligibility खोजें।

```sh theme={null}
youka capabilities --json
```

```ts theme={null}
const capabilities = await client.capabilities.get();
const eligibleModels = capabilities.models.filter(
  (model) => model.eligible && model.workflows.includes("lyric-video"),
);
```

रिस्पॉन्स में model IDs, operations, audio inputs, supplied-text semantics, workflows, language support, और required features का वर्णन होता है। `suppliedTextHandling` alignment, provider keyterms, और transcription के बाद correction में अंतर बताता है। Eligibility authenticated अकाउंट को दर्शाती है। Discovery configured support बताता है, provider uptime की गारंटी नहीं। Request validation और price quotes ही authoritative रहते हैं।

जिन मॉडलों को isolated vocals चाहिए, वे no-separation lyric video प्रोसेस नहीं कर सकते। उन्हें karaoke वर्कफ़्लो में ऐसे separation मॉडल के साथ उपयोग करें जो vocals बनाता हो। Wav2Vec2 एक alignment मॉडल है। ElevenLabs Scribe एक transcription मॉडल है। Supplied transcription text मार्गदर्शन है, समान आउटपुट टेक्स्ट की गारंटी नहीं।

## प्रोजेक्ट बनाएं और quote लें

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

const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! });
const operation = await client.projects.create(
  {
    kind: "lyric-video",
    source: { type: "path", path: "./song.wav" },
    title: "Example song",
    lyricsSource: {
      type: "transcribe",
      syncModel: AlignmentModel.ElevenLabsTranscription,
      lyrics: "Optional reference lyrics",
    },
  },
  { idempotencyKey: "example-song-create-v1" },
);
const { project } = await client.projects.wait(operation);
```

lyric videos के लिए advertised किसी मॉडल से supplied lyrics align करें।

```sh theme={null}
youka project create ./song.wav --kind lyric-video --mode align \
  --sync-model audioshake-alignment --lyrics 'Line one
Line two' --json
```

karaoke प्रोजेक्ट्स के लिए separation रखें। `--kind` छोड़ें या `--kind karaoke` पास करें और `--split-model` चुनें। Lyrics processing के बिना बनाने के लिए `--mode none` उपयोग करें। Lyric-video requests separation options अस्वीकार करते हैं।

Creation से पहले उसी source, workflow, और processing options का quote लें।

```sh theme={null}
youka project quote ./song.wav --kind lyric-video --mode transcribe \
  --sync-model elevenlabs-transcription --json
```

Quote, creation की तरह ही model compatibility, language policy, account features, duration, और storage rules जांचता है। उसके credit breakdown में lyric videos के लिए zero separation credits होते हैं। Quote capacity या credits reserve नहीं करता; creation से पहले अकाउंट state बदल सकती है।

## processing jobs के बिना timings सुधारें

`GET /projects/{projectId}/alignments` के जरिए alignments पढ़ें, फिर चुना हुआ resource `GET /projects/{projectId}/alignments/{alignmentId}` से लें। सूची में `alignments`, `selectedAlignmentId`, और `selectionRevision` होते हैं। हर resource में timing payload, `revision`, `selected`, और `selectionRevision` शामिल होते हैं।

Updates पूरा `alignment` object replace करते हैं। वे synchronization नहीं चलाते और processing credit hold नहीं बनाते। Edit करते समय IDs, text, line/word/subword indexes, singer information, और translations बनाए रखें। Times absolute decimal seconds होते हैं। सबमिट किए गए values में वांछित correction एक बार ही लागू करें। उसी correction को export offset के रूप में फिर से न जोड़ें।

```ts theme={null}
const snapshot = await client.projects.alignments.list(project.id);
const current = snapshot.alignments.find(
  (alignment) => alignment.id === snapshot.selectedAlignmentId,
);
if (!current) throw new Error("Project has no alignment to edit");

const corrected = structuredClone(current.alignment);
corrected.items[0]!.start = 0.75;
corrected.items[0]!.end = 1.25;

const saved = await client.projects.alignments.update(project.id, current.id, {
  alignment: corrected,
  expectedRevision: current.revision,
  select: true,
  expectedSelectionRevision: snapshot.selectionRevision,
});
```

Atomically save और select करने के लिए `select: true` उपयोग करें। मौजूदा timings को replace किए बिना select करने के लिए `client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision })` कॉल करें।

Alignment revision timing contents को सुरक्षित रखता है। Selection revision यह सुरक्षित रखता है कि कौन-सा alignment active है। Stale token पर HTTP 409 मिलता है। नवीनतम resource fetch करें, edits की तुलना करें, और जानबूझकर replacement सबमिट करें। Token को अपने-आप refresh करके किसी अन्य editor के बदलाव overwrite न करें।

CLI JSON file या standard input स्वीकार करता है। Import file में `{ "alignment": { "items": [...] }, "expectedRevision": "..." }` होता है। Atomically select करते समय `select` और `expectedSelectionRevision` शामिल करें। Exported resources में response metadata भी होता है, इसलिए import से पहले request fields निकाल लें।

```sh theme={null}
youka project timings list proj_example --json
youka project timings get proj_example aln_example --json > timing-resource.json
youka project timings import proj_example aln_example --body corrected-request.json --json
youka project timings select proj_example aln_example \
  --expected-revision "$ALIGNMENT_REVISION" \
  --expected-selection-revision "$SELECTION_REVISION" --json
```

Imports अधिकतम 100,000 items स्वीकार करते हैं। हर end time अपने start से strictly greater होना चाहिए। Invalid numbers, negative times, invalid indexes, zero-length या reversed ranges, और किसी ज्ञात project duration से आगे की timings अस्वीकार की जाती हैं। Legitimate overlaps और duet timing समर्थित रहते हैं। External edit के बाद पहले से open app project को reopen या refresh करें।

## चुना हुआ वर्ज़न एक्सपोर्ट करें

```sh theme={null}
youka project versions proj_example --json
youka export create proj_example --version-id ver_example --local \
  --transparent --mute-all --fps 30 --output ./overlay.mov --json
```

`versionId` export requests और settings updates में, और settings GET query में optional है। इसे छोड़ने पर primary-version व्यवहार बना रहता है। Selected alignment प्रोजेक्ट से संबंधित होता है, जबकि styling और settings चुने गए version से संबंधित होते हैं।

```ts theme={null}
const versions = await client.projects.versions.list(project.id);
const versionId = versions[0]!.id;
const stemVolumes = Object.fromEntries(
  project.stems.map((stem) => [stem.id, 0]),
);
const payload = await client.exports.prepareLocal(project.id, {
  versionId,
  transparent: true,
  stemVolumes,
  fps: 30,
});
console.log(payload.versionId, payload.alignmentId, payload.alignmentRevision);

await client.exports.create(project.id, {
  target: "local",
  versionId,
  transparent: true,
  stemVolumes,
  fps: 30,
  outputPath: "./overlay.mov",
});
```

Cloud export operation handles और local payloads में `versionId`, `alignmentId`, और `alignmentRevision` शामिल होते हैं। ये फ़ील्ड उस timing snapshot की पहचान करते हैं जिसका उपयोग उस export या prepared payload के लिए हुआ। हर preparation current state पढ़ता है, इसलिए बाद का अलग export नए edits देख सकता है। जब external renderer को ठीक वही prepared snapshot render करना हो, तो returned payload सेव करें, और signed media URLs expire होने पर इसे refresh करें।

Transparent local output MOV container में ProRes 4444 उपयोग करता है। `--mute-all` सभी project stems को zero volume पर मैप करता है। Silence और absent audio stream अलग output properties हैं; यदि downstream tool को इनमें से किसी एक की आवश्यकता हो तो rendered file inspect करें। Local rendering cloud export credits consume नहीं करता और मौजूदा feature eligibility के अधीन रहता है।

Word timing, global audio offsets, और lyric anticipation अलग settings हैं। मौजूदा layouts line visibility नियंत्रित करते हैं। यह release हर line के लिए fixed reveal interval का वादा नहीं करता और न ही अलग backing-track attachment API जोड़ता है।

## कैटलॉग सुरक्षित रूप से ऑपरेट करें

Stable item ID, source fingerprint, operation settings, idempotency key, project/task IDs, और अंतिम terminal result के साथ एक manifest रखें। किसी key का reuse केवल उसी request के retries के लिए करें। Completion का इंतज़ार करने से पहले creation results persist करें ताकि restart पर polling resume हो सके। Uploads और local file preparation का अपना lifecycle होता है; create idempotency key हर upload को deduplicate नहीं करता।

Runnable [catalogue example](/examples/catalogue.js) preuploaded input file IDs स्वीकार करता है और प्रति item एक checkpoint persist करता है। Manifest कुछ ऐसा दिखता है।

```json theme={null}
[
  {
    "id": "song-001",
    "request": {
      "kind": "lyric-video",
      "inputFileId": "owned-upload-id",
      "title": "Example song",
      "lyricsSource": {
        "type": "transcribe",
        "syncModel": "elevenlabs-transcription"
      }
    }
  }
]
```

उदाहरण को `catalogue.ts` के रूप में डाउनलोड करें। इसकी dependencies install करें और `YOUKA_API_KEY` सेट करें। अपने `package.json` में `"type": "module"` वाले Node.js प्रोजेक्ट का उपयोग करें।

```sh theme={null}
npm install @youka/sdk@^0.2.0 tsx
npx tsx ./catalogue.ts ./manifest.json ./catalogue-state 1
```

Accepted jobs की polling resume करने के लिए या uncertain submission को उसकी original key के साथ retry करने के लिए उसी manifest और state directory के साथ दोबारा चलाएं। Completed और failed jobs रिकॉर्ड होकर skip हो जाते हैं। बदली हुई requests के लिए नए item IDs चाहिए। Directory lock दो processes को एक साथ वही manifest submit करने से रोकता है। Hard crash के बाद stale `.lock` केवल तभी हटाएं जब यह पुष्टि हो जाए कि उसमें stored PID अब running नहीं है।

एक in-flight item से शुरू करें। अपने अकाउंट के लिए processing latency और rate-limit responses मापने के बाद ही bounded worker count बढ़ाएं। Transport errors और rate limits को `Retry-After` का सम्मान करते हुए backoff के साथ retry करें। Validation errors, timing conflicts, या terminal processing failures को अंधाधुंध retry न करें। Authentication errors के लिए वैध credentials चाहिए; उनका मतलब यह नहीं कि processing job failed हुआ।

Existing cloud task polling और failure-credit handling बनाए रखें। यहां कोई batch endpoint, webhook promise, pricing change, licensing change, या retention policy introduced नहीं की गई है।