vox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vox

使用一个入口覆盖 Vox CLI 全流程能力。始终通过 CLI 执行，不直接写推理代码。

先切到 skill 根目录（

SKILL.md

所在目录）再运行下面脚本，避免相对路径错误。

Use a single entry point to cover the full-process capabilities of Vox CLI. Always execute via CLI, do not write inference code directly.

First switch to the skill root directory (where

SKILL.md

is located) before running the following scripts to avoid relative path errors.

固定流程

Fixed Workflow

先执行初始化与守卫：

bash

undefined

First perform initialization and guarding:

bash

undefined

无副作用预检（推荐先跑）

Side-effect-free pre-check (recommended to run first)

bash scripts/bootstrap.sh --check

真实安装与修复

Actual installation and repair

bash scripts/bootstrap.sh


2. 根据需求匹配意图（见 `references/intents.md`）。
3. 需要模型时先确保模型可用：

```bash
bash scripts/ensure_model.sh <model_id|asr-auto|tts-default>

执行对应
```
vox
```
命令。
交付前强制自检：

bash

bash scripts/self_check.sh [--require-model <...>] [--require-file <...>]

失败时记录样本：

bash

bash scripts/log_failure.sh --stage "<stage>" --command "<cmd>" --error "<msg>" [--retry "<retry-cmd>"]

bash scripts/bootstrap.sh


2. Match intents based on requirements (see `references/intents.md`).
3. When models are needed, first ensure they are available:

```bash
bash scripts/ensure_model.sh <model_id|asr-auto|tts-default>

Execute the corresponding
```
vox
```
command.
Mandatory self-check before delivery:

bash

bash scripts/self_check.sh [--require-model <...>] [--require-file <...>]

Record samples when failure occurs:

bash

bash scripts/log_failure.sh --stage "<stage>" --command "<cmd>" --error "<msg>" [--retry "<retry-cmd>"]

5 条硬标准（必须全部满足）

5 Hard Standards (Must Be Fully Met)

平台必须是
```
Darwin + arm64
```
。
```
vox doctor --json
```
必须
```
ok=true
```
。
本次任务所需模型必须
```
verified=true
```
。
主命令退出码必须是
```
0
```
。
需要文件输出时，目标文件必须存在且路径已回报。

The platform must be
```
Darwin + arm64
```
.
```
vox doctor --json
```
must return
```
ok=true
```
.
The models required for this task must have
```
verified=true
```
.
The exit code of the main command must be
```
0
```
.
When file output is required, the target file must exist and the path must be reported.

执行规则

Execution Rules

优先使用 JSON 输出（
```
--json
```
或
```
--format ndjson
```
）。
执行前先声明将要运行的命令；执行后回报关键结果。
若命令失败，先给重试命令，再调用
```
log_failure.sh
```
记录失败样本。
禁止跳过守卫直接执行重操作（下载模型、克隆、pipeline）。

Prioritize using JSON output (
```
--json
```
or
```
--format ndjson
```
).
Declare the command to be run before execution; report key results after execution.
If the command fails, first provide the retry command, then call
```
log_failure.sh
```
to record the failure sample.
It is forbidden to skip guarding and directly perform heavy operations (model download, cloning, pipeline).

常用命令模板

Common Command Templates

bash

undefined

bash

undefined

环境检查

Environment check

scripts/vox_cmd.sh doctor --json

查看模型状态

Check model status

scripts/vox_cmd.sh model status --json

离线转写

Offline transcription

scripts/vox_cmd.sh asr transcribe --audio ./speech.wav --lang zh --model auto --json

语音克隆

Voice cloning

scripts/vox_cmd.sh tts clone --profile narrator --text "你好" --out ./out.wav --model qwen-tts-1.7b --json

一体化流程

Integrated workflow

scripts/vox_cmd.sh pipeline run --profile narrator --audio ./input.wav --clone-text "把这段内容读出来" --lang zh --json

undefined

scripts/vox_cmd.sh pipeline run --profile narrator --audio ./input.wav --clone-text "把这段内容读出来" --lang zh --json

undefined

依赖与发布约定

Dependencies and Release Conventions

安装优先使用
```
uv
```
。
默认安装系统依赖：
```
ffmpeg
```
、
```
portaudio
```
。
CLI 来源：
- 优先
```
VOX_CLI_PACKAGE_SPEC
```
  （显式指定包）。
- 若设置
```
VOX_CLI_GIT_URL
```
  ，使用
```
git+<url>
```
  安装。
- 默认回退到
```
git+https://github.com/catoncat/vox-cli.git
```
  。

Prioritize using
```
uv
```
for installation.
System dependencies installed by default:
```
ffmpeg
```
,
```
portaudio
```
.
CLI sources:
- Prioritize
```
VOX_CLI_PACKAGE_SPEC
```
  (explicitly specified package).
- If
```
VOX_CLI_GIT_URL
```
  is set, install using
```
git+<url>
```
  .
- Default fallback to
```
git+https://github.com/catoncat/vox-cli.git
```
  .