Automate lyric videos

Use @youka/sdk and @youka/cli version 0.2.0 or later for these examples. Projects created through the API remain available in your Youka library.

Choose a workflow and model

kind selects the project workflow. karaoke separates stems. lyric-video uses the original audio and does not charge for separation. Omitted kind retains the existing karaoke behavior. Lyrics processing is a separate choice of alignment, transcription, or no processing. Discover models and account eligibility before choosing a model.

youka capabilities --json

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

The response describes model IDs, operations, audio inputs, supplied-text semantics, workflows, language support, and required features. suppliedTextHandling distinguishes alignment, provider keyterms, and correction after transcription. Eligibility reflects the authenticated account. Discovery describes configured support, not a provider uptime guarantee. Request validation and price quotes remain authoritative. Models that require isolated vocals cannot process a no-separation lyric video. Use them in a karaoke workflow with a separation model that produces vocals. Wav2Vec2 is an alignment model. ElevenLabs Scribe is a transcription model. Supplied transcription text is guidance, not a guarantee of identical output text.

Create and quote projects

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);

Align supplied lyrics with a model advertised for lyric videos.

youka project create ./song.wav --kind lyric-video --mode align \
  --sync-model audioshake-alignment --lyrics 'Line one
Line two' --json

Keep separation for karaoke projects. Omit --kind or pass --kind karaoke and choose --split-model. Use --mode none to create without lyric processing. Lyric-video requests reject separation options. Quote the same source, workflow, and processing options before creation.

youka project quote ./song.wav --kind lyric-video --mode transcribe \
  --sync-model elevenlabs-transcription --json

A quote checks the same model compatibility, language policy, account features, duration, and storage rules as creation. Its credit breakdown has zero separation credits for lyric videos. A quote does not reserve capacity or credits; account state can change before creation.

Correct timings without processing jobs

Read alignments through GET /projects/{projectId}/alignments, then get the chosen resource through GET /projects/{projectId}/alignments/{alignmentId}. The list contains alignments, selectedAlignmentId, and selectionRevision. Each resource includes the timing payload, revision, selected, and selectionRevision. Updates replace the complete alignment object. They do not run synchronization or create a processing credit hold. Keep IDs, text, line/word/subword indexes, singer information, and translations when editing. Times are absolute decimal seconds. Apply any desired correction once in the submitted values. Do not add the same correction again as an export offset.

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,
});

Use select: true to save and select atomically. To select existing timings without replacing them, call client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision }). The alignment revision protects timing contents. The selection revision protects which alignment is active. A stale token produces HTTP 409. Fetch the latest resource, compare the edits, and submit a deliberate replacement. Do not automatically refresh the token and overwrite another editor’s changes. The CLI accepts a JSON file or standard input. An import file contains { "alignment": { "items": [...] }, "expectedRevision": "..." }. Include select and expectedSelectionRevision when selecting atomically. Exported resources also contain response metadata, so extract the request fields before importing.

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 accept up to 100,000 items. Every end time must be strictly greater than its start. Invalid numbers, negative times, invalid indexes, zero-length or reversed ranges, and timings past a known project duration are rejected. Legitimate overlaps and duet timing remain supported. Reopen or refresh an already open app project after an external edit.

Export a chosen version

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 is optional in export requests and settings updates, and in the settings GET query. Omitting it retains primary-version behavior. The selected alignment belongs to the project, while styling and settings belong to the chosen version.

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 and local payloads include versionId, alignmentId, and alignmentRevision. These fields identify the timing snapshot used for that export or prepared payload. Each preparation reads current state, so a separate later export can observe newer edits. Save the returned payload when an external renderer must render exactly that prepared snapshot, and refresh it when signed media URLs expire. Transparent local output uses ProRes 4444 in a MOV container. --mute-all maps all project stems to zero volume. Silence and an absent audio stream are different output properties; inspect the rendered file if a downstream tool requires one of them. Local rendering does not consume cloud export credits and remains subject to existing feature eligibility. Word timing, global audio offsets, and lyric anticipation are separate settings. Existing layouts control line visibility. This release does not promise a fixed reveal interval for every line or add a separate backing-track attachment API.

Operate a catalogue safely

Keep a manifest with a stable item ID, source fingerprint, operation settings, idempotency key, project/task IDs, and the last terminal result. Reuse a key only for retries of the same request. Persist creation results before waiting for completion so a restart can resume polling. Uploads and local file preparation have their own lifecycle; a create idempotency key does not deduplicate every upload. The runnable catalogue example accepts preuploaded input file IDs and persists one checkpoint per item. A manifest looks like this.

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

Download the example as catalogue.ts. Install its dependencies and set YOUKA_API_KEY. Use a Node.js project with "type": "module" in its package.json.

npm install @youka/sdk@^0.2.0 tsx
npx tsx ./catalogue.ts ./manifest.json ./catalogue-state 1

Rerun with the same manifest and state directory to resume polling accepted jobs or retry an uncertain submission with its original key. Completed and failed jobs are recorded and skipped. Changed requests require new item IDs. The directory lock prevents two processes from submitting the same manifest concurrently. After a hard crash, remove a stale .lock only after confirming that the PID stored in it is no longer running. Start with one in-flight item. Increase a bounded worker count only after measuring processing latency and rate-limit responses for your account. Retry transport errors and rate limits with backoff, respecting Retry-After. Do not blindly retry validation errors, timing conflicts, or terminal processing failures. Authentication errors require valid credentials; they do not mean a processing job failed. Keep existing cloud task polling and failure-credit handling. No batch endpoint, webhook promise, pricing change, licensing change, or retention policy is introduced here.

Guides

Resources

API Reference

Automate lyric videos

Choose a workflow and model

Create and quote projects

Correct timings without processing jobs

Export a chosen version

Operate a catalogue safely

​Choose a workflow and model

​Create and quote projects

​Correct timings without processing jobs

​Export a chosen version

​Operate a catalogue safely

Choose a workflow and model

Create and quote projects

Correct timings without processing jobs

Export a chosen version

Operate a catalogue safely