Lyrics sync - Youka Docs

Lyrics sync aligns lyric text to the audio so words highlight at the right moment. Use client.projects.syncLyrics(...) to re-run sync on any project with updated lyrics, a different model, or a new language.

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

Start a new lyrics sync operation.

const operation = await client.projects.syncLyrics("prj_abc123", {
  lyricsSource: {
    type: "align",
    lyrics: "First line\nSecond line\n...",
    syncModel: "audioshake-alignment",
  },
});

const { project } = await client.projects.wait(operation);
console.log(project.alignments);

Lyrics source

Pass a lyricsSource object in the request body:

transcribe
align

Let the model transcribe lyrics from the audio.

{
  lyricsSource: {
    type: "transcribe",
    syncModel: "audioshake-transcription",
    language: "en",
  },
}

Pass exact lyrics. The model aligns them to the audio.

{
  lyricsSource: {
    type: "align",
    lyrics: "First line\nSecond line\n...",
    syncModel: "audioshake-alignment",
    language: "en",
  },
}

Sync models

Alignment models (use with align when you have accurate lyrics):

audioshake-alignment
musicai-alignment
musicai-alignment-subword
wav2vec2

Transcription models (use with transcribe):

audioshake-transcription
elevenlabs-transcription
musicai-transcription
whisper

See Choose a lyrics sync model for guidance.

End-to-end example

import { YoukaClient } from "@youka/sdk";
import { readFile } from "node:fs/promises";

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

async function reAlignLyrics(projectId: string) {
  const lyrics = await readFile("./lyrics.txt", "utf8");

  const operation = await client.projects.syncLyrics(projectId, {
    lyricsSource: {
      type: "align",
      lyrics,
      syncModel: "audioshake-alignment",
      language: "en",
    },
  });

  const { project } = await client.projects.wait(operation);
  console.log("Updated lyrics with", project.lyrics?.length, "lines");
}

What’s next

Stems — re-run stem separation before re-syncing
Tasks — operation handles and abort patterns
Choose a lyrics sync model — pick the right model

Discover supported models

client.capabilities.get() returns configured model support and authenticated account eligibility. Each model describes its operation, inputAudio, supported workflows, language policy, required features, and suppliedTextHandling. Availability is not a provider uptime guarantee. Transcription accepts optional lyrics as reference text. The capability response distinguishes provider keyterms from correction after transcription. Reference text does not guarantee identical output. For exact supplied text, choose an eligible alignment model.

Edit existing timings

Use client.projects.alignments.list(projectId) and .get(projectId, alignmentId) to read typed timing resources. .update(projectId, alignmentId, body) replaces timings without a synchronization job or processing credit hold. The update body requires the complete alignment and expectedRevision. Add select: true and expectedSelectionRevision to select the saved alignment atomically. .select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision }) selects existing timings. Both revisions protect against concurrent edits. A stale revision returns HTTP 409. Keep item IDs, text, indexes, singers, and translations when editing. Times are absolute seconds. Every end must be greater than its start. Invalid, negative, or out-of-duration timings are rejected. Legitimate overlapping and duet timings are supported. See Automate lyric videos for a complete timing edit and conflict handling.

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

​Lyrics source

​Sync models

​End-to-end example

​What’s next

​Discover supported models

​Edit existing timings