> ## 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.

# Lyrics sync

> Re-run lyrics synchronization on an existing project

Lyrics sync aligns lyric text to the audio so words highlight at the right moment. Youka runs sync automatically when you create a project. Use this endpoint to re-run sync with a different model, updated lyrics, or a different language.

## When to use

<Columns cols={2}>
  <Card title="Re-sync when…" icon="arrows-rotate">
    Timings are off, you edited the lyrics, you changed sync models, or you
    corrected the language.
  </Card>

  <Card title="Skip this endpoint when…" icon="xmark">
    You're creating a new project — pass `lyricsSource` to `POST /projects`
    instead of running sync twice.
  </Card>
</Columns>

## Endpoint

```
POST /projects/{projectId}/tasks/lyrics-sync
```

Returns a `taskId` you can poll at `GET /tasks/{taskId}`. The original project state is untouched until the new task finishes.

## Request

```bash theme={null}
curl -X POST https://api.youka.io/api/v1/projects/prj_abc/tasks/lyrics-sync \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: resync-prj_abc-v2" \
  -H "Content-Type: application/json" \
  -d '{
    "lyricsSource": {
      "type": "align",
      "lyrics": "First line\nSecond line\n...",
      "syncModel": "audioshake-alignment",
      "language": "en"
    }
  }'
```

### Lyrics source

Pass one of two source types via `lyricsSource`:

<Tabs>
  <Tab title="transcribe">
    Let the model transcribe lyrics from the audio.

    ```json theme={null}
    {
      "type": "transcribe",
      "syncModel": "audioshake-transcription",
      "language": "en"
    }
    ```
  </Tab>

  <Tab title="align">
    You pass exact lyrics. The model aligns them to the audio.

    ```json theme={null}
    {
      "type": "align",
      "lyrics": "First line\nSecond line",
      "syncModel": "audioshake-alignment",
      "language": "en"
    }
    ```
  </Tab>
</Tabs>

### Sync models

**Alignment models** — use when you already have accurate lyrics (`align`):

* `audioshake-alignment`
* `musicai-alignment`
* `musicai-alignment-subword`

**Transcription models** — use when the model should extract lyrics from the audio (`transcribe`):

* `audioshake-transcription`
* `musicai-transcription`
* `wav2vec2`
* `whisper`

See [Sync model reference](/en/desktop/sync-model) for guidance.

## Polling

```bash theme={null}
# Poll the task
curl https://api.youka.io/api/v1/tasks/tsk_abc \
  -H "Authorization: Bearer yk_..."

# Once the task is in a terminal state, re-read the project
curl https://api.youka.io/api/v1/projects/prj_abc \
  -H "Authorization: Bearer yk_..."
```

The updated `project.lyrics` contains the new word-level timings.

<Tip>
  Pair every request with an idempotency key so retries don't queue duplicate
  sync jobs.
</Tip>

## What's next

* [Stems](/en/api/stems) — re-run stem separation before re-syncing
* [Async jobs](/en/api/async-jobs) — polling pattern
* [SDK lyrics sync](/en/sdk/lyrics-sync) — the same endpoint in TypeScript
* [Sync model reference](/en/desktop/sync-model) — pick the right model