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

# 项目

> 创建、查看、等待并修改进行中的卡拉 OK 项目

项目是单首卡拉 OK 曲目的进行中资源。它包含源媒体、同步歌词、分离音轨（stems）、渲染设置，以及由此创建的导出内容。

## `project create`

从本地文件或 URL 创建一个新项目。

```bash theme={null}
youka project create <source> [options]
```

<ParamField path="source" type="string" required>
  本地文件路径（`./song.mp3`）或 HTTP/HTTPS URL
  （`https://example.com/song.mp4`）。
</ParamField>

### Options

| Option                          | Description                                |
| ------------------------------- | ------------------------------------------ |
| `--title <title>`               | 项目标题                                       |
| `--mode <mode>`                 | `none`、`transcribe` 或 `align`              |
| `--lyrics <text>`               | 歌词文本                                       |
| `--lang <code>`                 | 语言代码                                       |
| `--sync-model <model>`          | 歌词同步模型                                     |
| `--split-model <model>`         | 音轨分离模型                                     |
| `--max-video-quality <quality>` | URL 来源的最高视频质量：`720p`、`1080p`、`4k` 或 `best` |
| `--preset <presetId>`           | 创建项目时应用预设                                  |
| `--export`                      | 项目就绪后创建一个导出                                |
| `--download`                    | 创建一个导出，等待完成并下载                             |
| `--output <path>`               | `--download` 的输出路径                         |

### Examples

<CodeGroup>
  ```bash local-file theme={null}
  youka project create ./song.mp3 \
    --title "My Song" \
    --mode transcribe \
    --lang en \
    --wait \
    --json
  ```

  ```bash url theme={null}
  youka project create "https://example.com/song.mp4" \
    --max-video-quality 4k \
    --download \
    --output ./karaoke.mp4 \
    --json
  ```

  ```bash align theme={null}
  youka project create ./song.mp3 \
    --mode align \
    --lyrics "$(cat lyrics.txt)" \
    --sync-model audioshake-alignment \
    --wait \
    --json
  ```
</CodeGroup>

规则：

* 如果你传入了歌词但省略 `--mode`，CLI 默认使用 `align`
* `align` 需要歌词
* `transcribe` 和 `none` 不接受歌词
* `--download` 隐含 `--export`
* `--max-video-quality` 仅适用于 HTTP/HTTPS URL 来源。默认值为 `1080p`，会在该上限内使用可用的最佳质量；当平台不提供受限码流时，会回退到可用的最佳格式。

## `project list`

列出已认证账号下的所有项目。

```bash theme={null}
youka project list
youka project list --json
```

## `project quote`

在不创建项目的情况下，估算创建项目所需的 credits。

```bash theme={null}
youka project quote <source> [options]
```

`source` 接受与
`project create` 相同的本地文件路径或 HTTP/HTTPS URL 形式。不带 `--duration` 时，CLI 会上传源文件以便服务器精确测量媒体时长，但不会创建项目。

### Options

| Option                          | Description                                |
| ------------------------------- | ------------------------------------------ |
| `--title <title>`               | 项目标题                                       |
| `--mode <mode>`                 | `none`、`transcribe` 或 `align`              |
| `--lyrics <text>`               | `align` 使用的歌词文本                            |
| `--lang <code>`                 | 语言代码                                       |
| `--sync-model <model>`          | 歌词同步模型                                     |
| `--split-model <model>`         | 音轨分离模型                                     |
| `--max-video-quality <quality>` | URL 来源的最高视频质量：`720p`、`1080p`、`4k` 或 `best` |
| `--duration <seconds>`          | 在已知时长的情况下直接估算，无需上传源文件                      |

Examples:

```bash theme={null}
youka project quote ./song.mp3 --mode transcribe --json
youka project quote https://example.com/song.mp4 --max-video-quality 4k --mode transcribe --json
youka project quote ./song.mp3 --duration 210 --mode none --json
```

## `project show`

获取当前项目状态，包括标准化后的 `state`、`pendingOperation`、stems、settings 和 exports。

```bash theme={null}
youka project show <projectId>
```

<ParamField path="projectId" type="string" required>
  `project create` 返回的项目 ID。
</ParamField>

## `project wait`

轮询项目，直到它达到终态。

```bash theme={null}
youka project wait <projectId> --json
```

## `project delete`

删除项目及其关联的所有 stems、lyrics 和 exports。

```bash theme={null}
youka project delete <projectId> --idempotency-key delete-<projectId>
```

<Warning>
  删除是永久性的。传入 `--idempotency-key` 可确保重试是安全的。
</Warning>

## `project sync`

在现有项目上重新运行歌词转写或对齐。

```bash theme={null}
youka project sync <projectId> [options]
```

| Option                 | Description            |
| ---------------------- | ---------------------- |
| `--mode <mode>`        | `transcribe` 或 `align` |
| `--text <text>`        | 歌词文本                   |
| `--lang <code>`        | 语言代码                   |
| `--sync-model <model>` | 歌词同步模型                 |

Example:

```bash theme={null}
youka project sync $PROJECT_ID \
  --mode align \
  --text "$(cat lyrics.txt)" \
  --wait \
  --json
```

## `project separate`

在现有项目上重新运行音轨分离。

```bash theme={null}
youka project separate <projectId> [--split-model <model>]
```

Example:

```bash theme={null}
youka project separate $PROJECT_ID --split-model audioshakeai --wait --json
```

## `project settings`

读取或更新当前项目设置。

```bash theme={null}
youka project settings <projectId>
youka project settings <projectId> --preset <presetId> --body ./settings.json
```

如果 `--preset` 和 `--body` 都不存在，该命令会返回当前设置；如果存在任意一个，则会执行更新。

Examples:

<CodeGroup>
  ```bash show theme={null}
  youka project settings $PROJECT_ID --json
  ```

  ```bash update theme={null}
  youka project settings $PROJECT_ID \
    --preset preset_abc123 \
    --body ./project-settings.json \
    --json
  ```
</CodeGroup>

## `project stem list`

列出项目的 stems。

```bash theme={null}
youka project stem list <projectId>
youka project stem list <projectId> --json
```

## `project stem download`

将一个或多个 stem 文件下载到磁盘。stems 会以其原始存储格式下载；CLI 不会对其进行转码。

```bash theme={null}
youka project stem download <projectId> <stemId> --output ./stems
youka project stem download <projectId> --type instrumental --output ./stems
youka project stem download <projectId> --type original --type backing-vocals --type vocals --output ./stems
youka project stem download <projectId> --all --output ./stems
```

支持的 `--type` 值为 `original`、`instrumental`、`vocals` 和
`backing_vocals`。CLI 也接受 `backing-vocals`、`backingVocals` 和
`backingvocals` 作为别名。

## 下一步

* [Exports](/zh/cli/exports) - 渲染完成的卡拉 OK
* [Presets](/zh/cli/presets) - 管理可复用的渲染配置
* [Render settings reference](/en/render-settings-reference) - 共享的 preset 与 settings 字段参考