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

# 歌词同步

> 在现有项目上重新运行歌词同步

歌词同步会将歌词文本与音频对齐，让单词在正确的时刻高亮显示。使用 `client.projects.syncLyrics(...)` 可在任何项目上重新运行同步：当歌词已更新、想换用不同模型或使用新语言时都适用。

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

启动一个新的歌词同步操作。

```ts theme={null}
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);
```

### 歌词来源

在请求体中传入一个 `lyricsSource` 对象：

<Tabs>
  <Tab title="transcribe">
    让模型从音频中转写歌词。

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

  <Tab title="align">
    传入准确歌词，模型会将其与音频对齐。

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

### 同步模型

**对齐模型**（当你有准确歌词时，配合 `align` 使用）：

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

**转写模型**（配合 `transcribe` 使用）：

* `audioshake-transcription`
* `elevenlabs-transcription`
* `musicai-transcription`
* `whisper`

参考 [Choose a lyrics sync model](/zh/web/lyrics-sync-models) 获取选择建议。

## 端到端示例

```ts theme={null}
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");
}
```

## 接下来做什么

* [Stems](/zh/sdk/stems) — 在重新同步前重新运行音轨分离
* [Tasks](/zh/sdk/tasks) — 操作句柄与中止模式
* [Choose a lyrics sync model](/zh/web/lyrics-sync-models) — 选择合适的模型