@fxt-voice/vtx-cli

VTX CLI 是一个命令行工具，用于将音频或视频文件提交到 Voice-Transcribe Server，生成基于声纹识别（Speaker Diarization）的逐字稿。

服务端会自动完成以下处理：

• 从视频中提取音频
• 识别不同说话人（声纹分离）
• 对每位说话人的语音进行逐字转录
• 输出带有说话人标注和时间戳的 Markdown 逐字稿

VTX CLI 负责文件上传、任务轮询和结果获取，所有转录工作由远程服务端完成。

安装

npm install -g @fxt-voice/vtx-cli

需要 Node.js >= 20。

更新

npm install -g @fxt-voice/vtx-cli@latest

确认当前版本：

vtx --version

第一次使用

初始化配置文件：

vtx config init

也可以指定配置文件路径：

vtx config init --path /path/to/config.json

设置服务端地址和 API Key：

vtx config set base_url http://your-server/api
vtx config set api_key your-api-key

查看当前配置：

vtx config get

查看单个配置项：

vtx config get base_url

配置文件默认保存在 ~/.vtx/config.json。

常用用法

上传文件并等待转录结果

vtx upload ./meeting.mp4 --pretty

支持的音频和视频格式：mp3、wav、mp4、m4a、mov、flac、wma、aac。服务端会自动提取音频并转录。

只提交任务，不等待完成

vtx upload ./meeting.mp4 --no-wait --pretty

强制重新转录（忽略缓存）

vtx upload ./meeting.mp4 --force-retranscribe --pretty

查询任务状态

vtx status TASK_ID --pretty

删除任务

vtx delete TASK_ID --pretty

强制删除正在处理中的任务：

vtx delete TASK_ID --force --pretty

检查服务端是否可用

vtx doctor --pretty

查看配置文件路径

vtx config path

修改配置

vtx config set base_url http://your-server/api
vtx config set api_key your-api-key

使用自定义配置文件

所有命令都支持 --config 参数来指定配置文件路径，而非使用默认的 ~/.vtx/config.json：

vtx upload ./meeting.mp4 --config /path/to/config.json --pretty
vtx status TASK_ID --config /path/to/config.json
vtx delete TASK_ID --config /path/to/config.json
vtx doctor --config /path/to/config.json
vtx config get --config /path/to/config.json
vtx config set base_url http://example.com/api --config /path/to/config.json

可配置项

| 字段 | 说明 | 默认值 | |------|------|--------| | base_url | 服务端 API 地址 | http://127.0.0.1:8000/api | | api_key | 认证密钥 | - | | endpoint | 上传接口路径 | /upload | | status_endpoint | 状态查询接口路径 | /status/{task_id} | | health_endpoint | 健康检查接口路径 | /health/ready | | poll_interval_seconds | 轮询间隔（秒） | 2 | | request_timeout_seconds | 请求超时（秒） | 300 | | wait | 上传后是否默认等待结果 | true |