Lyrics sync

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

Overview

Reference

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

Lyrics source

Sync models

End-to-end example

What’s next

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

​Lyrics source

​Sync models

​End-to-end example

​What’s next

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

Lyrics source

Sync models

End-to-end example

What’s next