# @youka/cli 中文文档

规范地址：https://npmcn.com/package/%40youka/cli/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T22:47:55.910Z
中文译文更新时间：2026-11-02T23:39:32.605Z
软件包许可：UNLICENSED

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40youka/cli
原文对照：https://npmcn.com/package/%40youka/cli/?lang=original
项目主页：https://docs.youka.io/en/cli
源码仓库：https://github.com/adam-technology/youka-online

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：930 kB，3 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：0 个
- 首次发布：2026-04-11T22:33:22.481Z
- 最新版本发布：2026-11-02T22:47:55.743Z
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

Youka REST API的官方命令行客户端。

## 安装

```sh
npm install @youka/cli
```

也可以使用：`pnpm add @youka/cli`、`yarn add @youka/cli`、`bun add @youka/cli`

## README

# @youka / cli

Youka REST API的官方命令行客户端。

使用此软件包从您的终端创建卡拉ok视频：上传音频或视频，同步或转录歌词，创建卡拉ok项目，渲染最终视频，并下载MP4。

## 安装

```bash
npm install -g @youka/cli
```

## API密匙

创建一个API密钥 [online.youka.io /账户](https://online.youka.io/account) 下 **API密钥**.

登录一次：

```bash
youka login "yk_..."
```

或者把钥匙放在你的环境中：

```bash
export YOUKA_API_KEY="yk_..."
```

检查哪个帐户、密钥源和API URL是活动的：

```bash
youka whoami --json
```

## 制作卡拉ok视频

从本地歌曲创建一个项目，同步您的歌词，导出卡拉ok视频，并下载MP4：

```bash
youka project create ./song.mp3 \
  --title "Artist - Song" \
  --mode align \
  --lyrics "$(cat lyrics.txt)" \
  --sync-model audioshake-alignment \
  --split-model mdx23c \
  --wait \
  --json
```

然后导出完成的项目：

```bash
youka export create proj_123 \
  --resolution 1080p \
  --quality high \
  --wait \
  --download \
  --output ./karaoke.mp4 \
  --json
```

或者在一个命令中完成整个流程：

```bash
youka project create ./song.mp3 \
  --mode align \
  --lyrics "$(cat lyrics.txt)" \
  --download \
  --output ./karaoke.mp4 \
  --json
```

## 自动转录歌词

使用转录时，你还没有歌词文本：

```bash
youka project create ./song.mp3 \
  --mode transcribe \
  --download \
  --output ./karaoke.mp4 \
  --json
```

## 使用托管媒体URL

```bash
youka project create https://example.com/song.mp4 \
  --mode align \
  --lyrics "$(cat lyrics.txt)" \
  --download \
  --output ./karaoke.mp4 \
  --json
```

当需要URL下载和本地渲染时，安装本地helper二进制文件：

```bash
youka deps status --json
youka deps ensure --for all --json
youka deps ensure --for render --update --json
youka deps path ffmpeg
```

## 文档

-   CLI指南: [https://docs.youka.io/en/cli](https://docs.youka.io/en/cli)
-   JavaScript SDK: [https://docs.youka.io/en/sdk](https://docs.youka.io/en/sdk)

## 发现功能和创建抒情视频

```bash
youka capabilities --json
youka project quote ./reference.wav --duration 120 --kind lyric-video --mode transcribe --sync-model elevenlabs-transcription --lyrics "Optional recognition hints" --json
youka project create ./reference.wav --kind lyric-video --mode align --sync-model audioshake-alignment --lyrics "Supplied lyrics" --wait --json
```

`--kind lyric-video` 跳过分离和拒绝 `--split-model`。省略了类 保留卡拉ok行为。所有支持的模型都通过工作流和 输入要求;需要独立人声的模型无法处理原声 直接追踪。 `--mode transcribe` 通过接收识别提示 `--lyrics` (或 `--text` 用于 `project sync`）。 `--language-hint-mode auto|explicit` 控制 语言政策。Wav2Vec2是一个对齐模型。

## 时间安排和版本选择

```bash
youka project timings list proj_123 --json
youka project timings get proj_123 alignment_123 --json
youka project timings import proj_123 alignment_123 --body corrected-timings.json --json
youka project timings select proj_123 alignment_123 --expected-revision REVISION --expected-selection-revision SELECTION_REVISION --json
youka project versions proj_123 --json
youka project settings proj_123 --version-id version_123 --json
youka export create proj_123 --local --version-id version_123 --transparent --mute-all --fps 30 --output ./overlay.mov --json
```

`corrected-timings.json` 包含 `{ "alignment": { "items": [...] }, "expectedRevision": "...", "select": true, "expectedSelectionRevision": "..." }`. 使用 `--body -` 从stdin中读取JSON对象。计时取代了完整 对齐，使用绝对秒，并保留文本和支持的元数据。 无效的时间间隔和过时的修订失败，而不是被静默修复。 读取结果使用正常的CLI JSON信封；构造从的导入对象 它的 `data` 字段，而不是把整个信封传回去。

计时编辑和选择不启动AI任务。 `--mute-all` 所有存在的沉默 茎和优先于音量覆盖；它不承诺消除 音频流。透明的本地导出使用ProRes 4444，不会引发 云导出或对齐费用。现有的功能资格仍然适用。 行预判取决于所选的布局。

在发布更新后的CLI之前，部署匹配的API端点。

## 常见问题

### @youka/cli 是什么？

Youka REST API的官方命令行客户端。

### 如何安装 @youka/cli？

在项目目录运行 npm install @youka/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 youka，可以用 npx youka 直接运行。

### @youka/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/youka\_\_cli 是否存在。

### @youka/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @youka/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @youka/cli 可以商用吗？

@youka/cli 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @youka/cli 还在维护吗？

最新版本 0\.3\.0 发布于 2026/11/03（今天）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/04/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。