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

# 音轨分离（Stems）

> 在现有项目上触发音轨分离任务

Stems 是从源音频中提取出来的人声与器乐轨道。创建项目时 Youka 会自动分离 stems，但你也可以在需要时使用不同的模型重新运行分离。

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

为项目启动一次新的音轨分离操作。

```ts theme={null}
const operation = await client.projects.separateStems("prj_abc123", {
  splitModel: "audioshakeai",
});

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

### Parameters

<ParamField path="projectId" type="string" required>
  要重新处理的项目。
</ParamField>

<ParamField path="splitModel" type="SplitModel">
  音轨分离模型。参见 [Split model reference](/zh/desktop/split-model)
  获取选择建议。
</ParamField>

### Available models

| 值                                             | 描述                    |
| --------------------------------------------- | --------------------- |
| `mdx23c`                                      | 默认。质量与速度平衡。           |
| `audioshakeai`                                | 高质量的 AudioShake 分离。   |
| `audioshake_vocals_lead`                      | 仅人声与主唱人声。             |
| `musicai_instrumental_only`                   | 仅器乐输出。                |
| `musicai_lead_backing_other`                  | 主唱、和声与其他 stems。       |
| `musicai_with_backing_vocals`                 | 包含和声轨道的人声。            |
| `musicai_without_backing_vocals`              | 仅主唱人声。                |
| `uvr_mdxnet_kara_2`                           | 为卡拉 OK 调校的 UVR 模型。    |
| `bs_roformer`                                 | BS-Roformer 模型。       |
| `mel_band_roformer_instrumental_becruily`     | Mel-band Roformer 器乐。 |
| `mel_band_roformer_instrumental_instv7_gabox` | 备选的 mel-band 器乐。      |
| `demucs`                                      | Facebook Demucs。      |

## 端到端示例

```ts theme={null}
import { YoukaClient, YoukaTaskError } from "@youka/zh/sdk";

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

async function reRunStems(projectId: string) {
  const operation = await client.projects.separateStems(projectId, {
    splitModel: "audioshakeai",
  });

  try {
    const { project } = await client.projects.wait(operation);
    console.log("New stems:", project.stems);
  } catch (error) {
    if (error instanceof YoukaTaskError) {
      console.error("Stem separation failed:", error.code, error.message);
      throw error;
    }
    throw error;
  }
}
```

<Tip>
  仅当你明确需要低层级的 task 访问时，才使用 `client.tasks.get(taskId)` 或 `client.tasks.wait(taskId)`。大多数调用方应当使用
  `client.projects.wait(operation)`。
</Tip>

## `client.projects.downloadStem(projectId, selector, options?)`

下载单个 stem，不将其转换为其他格式。通过 ID 或类型精确选择一个
stem：

```ts theme={null}
await client.projects.downloadStem(
  "prj_abc123",
  { type: "instrumental" },
  { output: "./stems" },
);

await client.projects.downloadStem(
  "prj_abc123",
  { stemId: "stm_abc123" },
  { output: "./stems/original.wav" },
);
```

支持的类型为 `original`、`instrumental`、`vocals` 和
`backing_vocals`。

## `client.projects.downloadStems(projectId, selector?, options?)`

下载多个 stems。传入 `types`、传入 `stemIds`，或省略 selector 以
下载所有可用的 stems：

```ts theme={null}
await client.projects.downloadStems(
  "prj_abc123",
  { types: ["original", "instrumental", "vocals"] },
  { output: "./stems" },
);

await client.projects.downloadStems("prj_abc123", undefined, {
  output: "./stems",
});
```

对于多 stem 下载，请使用输出目录。SDK 会写出原始存储的 stem 文件，并且不会对其进行转码。

## 下一步

* [Lyrics sync](/zh/sdk/lyrics-sync) — 替换 stems 后重新同步歌词
* [Tasks](/zh/sdk/tasks) — operation 句柄与高级 task 轮询
* [Split model reference](/zh/desktop/split-model) — 选择合适的模型