VoxCPM CLI 是一个轻量的本地 VoxCPM2 文本转语音命令行工具，靠 OpenVINO 跑在本机，不用服务器，运行时也不需要 PyTorch。CLI 默认输出 JSON，退出码方便机器判断，还附带一个 Agent Skill，放在终端、脚本或 LLM Agent 里都能用。

为什么做这个

• 本地运行：语音在你自己的机器上生成，不发给任何第三方 API。
• 方便 Agent 调用：每条命令的 stdout 是结构化 JSON，stderr 是给人看的日志，退出码含义明确。
• 推理不需要 PyTorch：模型转成 OpenVINO IR，合成走轻量的 OpenVINO 运行时（CPU 或 GPU），不拖整套 PyTorch。
• 仓库干净：模型权重和转换产物不进 git；prepare 只在你确认之后才下载和转换。

工作原理

Plain Text

┌────────────┐  download/convert  ┌───────────────────────┐
│ HF + GitHub ──────────────────► │ cache/  models/       │
└────────────┘                     │ (gitignored artifacts)│
                                   └───────────┬───────────┘
                                               │
                          voxcpm              │ synth
                                               ▼
                                   ┌───────────────────────┐
                                   │ OpenVINO pipeline      │
                                   │ (no PyTorch at runtime)│
                                   └───────────┬───────────┘
                                               ▼
                                   output/*.wav  +  JSON result

prepare 下载上游 VoxCPM 源码和 VoxCPM2 权重，转成 OpenVINO IR；synth 用 OpenVINO 加载 IR，往 output/ 写 48 kHz 的 WAV 文件。

环境要求

项目	要求
操作系统	Windows
Python	3.10、3.11 或 3.12
网络	只有第一次跑 prepare 时需要（下载模型和源码）
磁盘	放得下上游源码、原始权重和 OpenVINO IR

运行时依赖（在 pyproject.toml 中声明）：huggingface-hub、librosa、numpy、openvino、soundfile、tokenizers。

只有转换才需要的额外依赖（从精简 checkout 跑 prepare 时必须装）：nncf、safetensors、torch>=2.5.0、transformers>=4.36.2。

安装

在项目根目录执行：

Bash

python -m pip install -e .

还要在本地下载并转换模型的话：

Bash

python -m pip install -e ".[convert]"

快速开始

Bash

# 1. 检查模型和 OpenVINO 是否就绪（不会下载任何东西）
voxcpm status --json

# 2. 没就绪就下载并转换（要联网、占磁盘，先确认）
voxcpm prepare --json

# 3. 合成
voxcpm synth --text "你好" --json

pip install 会注册 voxcpm 命令；包在路径里时，也可以用 python -m voxcpm_cli 调用。

命令参考

所有命令都支持 --json，在 stdout 输出 JSON。进度和日志走 stderr，stdout 始终能被机器解析。

status

报告预期的产物在不在，以及会用哪个 OpenVINO 设备：

Bash

voxcpm status --json

预期的目录：

Plain Text

cache/source/VoxCPM/
models/original/VoxCPM2/
models/openvino/VoxCPM2/

prepare

下载上游源码和 VoxCPM2 权重（Hugging Face），转成 OpenVINO IR，放在 models/openvino/VoxCPM2/ 下：

Bash

voxcpm prepare --json

常用选项：

Bash

voxcpm prepare --json --device AUTO
voxcpm prepare --json --force-convert
voxcpm prepare --json \
  --model-dir models/original/VoxCPM2 \
  --ov-model-dir models/openvino/VoxCPM2

synth

生成 WAV 文件。--text 和 --text-file 必须给一个，也只能给一个：

Bash

# Short text
voxcpm synth --text "你好" --json

# Long text from a file
voxcpm synth --text-file input.txt --json

# Explicit output path (must stay inside output/)
voxcpm synth --text-file input.txt --output output/demo.wav --json

# Voice instruction
voxcpm synth --text-file input.txt \
  --voice-instruction "温柔、自然、语速适中" --json

# Generation parameters
voxcpm synth --text-file input.txt \
  --cfg-value 2.0 --inference-timesteps 10 --max-len 2000 \
  --device AUTO --json

成功时，stdout 输出这段 JSON：

JSON

{
  "ok": true,
  "path": "C:\\project\\voxcpm-cli\\output\\demo.wav",
  "sample_rate": 48000,
  "format": "wav",
  "model": "VoxCPM2 OpenVINO",
  "device": "GPU",
  "duration_ms": 12345
}

--version

Bash

voxcpm --version

错误处理

失败也返回 JSON，并对应一个进程退出码：

JSON

{
  "ok": false,
  "error": { "code": "MODEL_NOT_READY", "message": "Run prepare before synth." }
}

退出码	含义
0	成功
1	参数校验错误
2	模型准备 / 加载错误
3	合成错误
4	文件写入错误

常见错误码：

• NO_TEXT_INPUT
• INVALID_ARGUMENT
• INVALID_OUTPUT_PATH
• MODEL_NOT_READY
• VOXCPM_SOURCE_DOWNLOAD_FAILED
• MODEL_DOWNLOAD_FAILED
• MODEL_CONVERSION_FAILED
• MODEL_LOAD_FAILED
• OPENVINO_DEVICE_UNAVAILABLE
• TTS_GENERATION_FAILED
• AUDIO_WRITE_FAILED

配合 Agent 使用

仓库在 skills/voxcpm-tts/SKILL.md 里带了一个 Agent Skill，工作流是：

1. 运行 voxcpm status --json。
2. 没就绪就先问用户，同意了再跑 voxcpm prepare --json。
3. 把长文本写进一个临时 .txt 文件。
4. 运行 voxcpm synth --text-file <file> --json。
5. 返回 WAV 路径、采样率和格式。

规则：用本地 CLI，别碰服务器；最终回复里不暴露敏感文本；没有明确同意，不下载也不转换模型。

项目结构

Plain Text

voxcpm-cli/
├── pyproject.toml            # Package + dependencies (and the convert extra)
├── LICENSE                   # Apache-2.0
├── assets/logo.svg           # README header logo
├── README.md
├── voxcpm_cli/
│   ├── __main__.py          # voxcpm entry
│   ├── cli.py               # argparse + JSON output, exit codes
│   ├── engine.py            # status / prepare / synthesize orchestration
│   ├── paths.py             # Artifact & output-path resolution
│   └── voxcpm2_tts_helper.py# Conversion + OpenVINO inference pipeline
├── skills/voxcpm-tts/       # Agent Skill instructions
├── cache/                   # Downloaded upstream source (gitignored)
├── models/original/         # Downloaded weights (gitignored)
├── models/openvino/         # Converted OpenVINO IR (gitignored)
└── output/                  # Generated WAVs (gitignored)

项目采用 Apache-2.0 许可证。

相关链接

• GitHub：wuhaostudio/voxcpm-cli
• Agent Skill：skills/voxcpm-tts/SKILL.md
• 作者：wuhaostudio