pyVideoTrans 命令行工具使用手册

本文档详细说明了 pyVideoTrans 视频翻译工具的命令行（CLI）使用方法。该工具支持语音转录（STT）、文字配音（TTS）、字幕翻译（STS）和全自动视频翻译（VTV）四大核心功能。

⚠️ 重要提示：开始之前

运行方式：本文档基于 uv run cli.py 方式运行。
文件路径：参数 --name 必须使用文件的绝对路径。
路径引用：如果路径中包含空格，必须使用英文双引号 "" 包裹路径。
- ✅ 正确：--name "C:\My Videos\test file.mp4"
- ❌ 错误：--name C:\My Videos\test file.mp4
获取配音角色：请在软件ui界面中选择对应的配音渠道和目标语言后，查看对应可用的发音角色，限于篇幅和可读性，这里不一一展示

1. 语音转录 (STT)

从视频或音频文件中提取语音并生成 SRT 字幕文件。

基本命令格式

bash

uv run cli.py --task stt --name "文件绝对路径" [可选参数]

参数详解

参数名	类型	必选	默认值	说明
`--task`	str	是	`stt`	任务类型标识
`--name`	str	是	-	音视频文件的绝对路径
`--recogn_type`	int	否	0	语音识别渠道ID（见附录1）
`--model_name`	str	否	`tiny`	模型大小（`tiny`, `small`, `base`, `medium`, `large-v2` 等，请在软件ui中根据所选语音识别渠道，查看可用的具体模型名称）
`--detect_language`	str	否	`auto`	源音频语言代码，默认自动检测
`--cuda`	bool	否	False	加上此标记启用 GPU (CUDA) 加速
`--remove_noise`	bool	否	False	加上此标记启用音频降噪
`--enable_diariz`	bool	否	False	加上此标记启用说话人识别（区分不同角色）
`--nums_diariz`	int	否	-1	指定说话人数量（仅在启用说话人识别时有效）
`--fix_punc`	bool	否	False	加上此标记尝试恢复标点符号

使用示例

使用 Faster-Whisper (tiny模型) 进行转录：

bash

uv run cli.py --task stt --name "D:\videos\demo.mp4" --recogn_type 0 --model_name tiny

使用 GPU 加速并指定源语言为中文：

bash

uv run cli.py --task stt --name "D:\videos\demo.mp4" --detect_language zh-cn --cuda

2. 文字配音 (TTS)

将 SRT 字幕文件或文本转换为语音音频。

基本命令格式

bash

uv run cli.py --task tts --name "SRT文件绝对路径" --voice_role "音色名" [可选参数]

参数详解

参数名	类型	必选	默认值	说明
`--task`	str	是	`tts`	任务类型标识
`--name`	str	是	-	SRT 字幕文件的绝对路径
`--tts_type`	int	否	0	配音渠道ID（见附录2）
`--voice_role`	str	是	-	音色名称 (请在软件ui中根据所选配音渠道，查看可用的具体角色名称)
`--voice_rate`	str	否	`+0%`	语速调整 (如 `+10%`, `-10%`)
`--volume`	str	否	`+0%`	音量调整
`--pitch`	str	否	`+0Hz`	音调调整
`--target_language_code`	str	否	-	目标语言代码（部分TTS引擎需要）
`--voice_autorate`	bool	否	False	自动加速音频以对齐字幕时间轴
`--align_sub_audio`	bool	否	False	强制修改字幕时间轴以适应音频长度

使用示例

使用 Edge-TTS (中文男声) 进行配音：

bash

uv run cli.py --task tts --name "C:\subs\movie.srt" --tts_type 0 --voice_role "zh-CN-YunyangNeural" --target_language_code zh-cn

3. 字幕翻译 (STS)

将 SRT 字幕文件翻译为另一种语言。

基本命令格式

bash

uv run cli.py --task sts --name "SRT文件绝对路径" --target_language_code "目标语言" [可选参数]

参数详解

参数名	类型	必选	默认值	说明
`--task`	str	是	`sts`	任务类型标识
`--name`	str	是	-	SRT 字幕文件的绝对路径
`--translate_type`	int	否	0	翻译渠道ID（见附录3）
`--target_language_code`	str	是	-	目标语言代码（见附录4）
`--source_language_code`	str	否	`auto`	原始语言代码

使用示例

将字幕翻译为英文（使用 Google 翻译）：

bash

uv run cli.py --task sts --name "D:\subs\source.srt" --target_language_code en --translate_type 0

4. 视频翻译 (VTV)

全流程处理：识别 -> 翻译 -> 配音 -> 合成，直接生成翻译后的视频。

基本命令格式

bash

uv run cli.py --task vtv --name "视频路径" --source_language_code "源语言" --target_language_code "目标语言" [可选参数]

参数详解

VTV 模式集成了上述所有功能的参数，以下列出不在上述内的其他参数。

参数名	类型	必选	默认值	说明
`--task`	str	是	`vtv`	任务类型标识
`--name`	str	是	-	视频文件的绝对路径
`--source_language_code`	str	是	-	发音语言 (VTV模式不可设为auto)
`--target_language_code`	str	是	-	目标语言
`--subtitle_type`	int	否	1	字幕嵌入方式 (见下方说明)
`--video_autorate`	bool	否	False	自动慢速处理视频画面以对齐配音
`--is_separate`	bool	否	False	是否分离人声与背景声 (保留背景音)
`--recogn2pass`	bool	否	False	是否进行二次语音识别 (提高准确率)
`--clear_cache`	bool	否	True	是否清理临时文件 (默认清理)
`--no-clear-cache`	flag	否	-	加上此标记则不清理缓存

关于 --subtitle_type 的值：

0: 不嵌入字幕
1: 硬字幕 (默认)
2: 软字幕
3: 硬双语字幕
4: 软双语字幕

使用示例

中译英视频，保留背景音，嵌入硬字幕，使用 GPU 加速：

bash

uv run cli.py --task vtv --name "E:\movies\clip.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --is_separate --cuda --subtitle_type 1

附录：渠道与代码代码对照表

附录1: 语音识别渠道列表 (`--recogn_type`)

在软件ui中，对应着具体的语音识别渠道顺序号，从0开始

0=faster-whisper(本地)
1=openai-whisper(本地)
2=Qwen-ASR(本地)
3=阿里FunASR(本地)
4=Huggingface_ASR
5=OpenAI语音识别API
6=Gemini大模型识别
7=阿里百炼 Qwen3-ASR
8=字节语音大模型极速版
9=智谱AI GLM-ASR
10=Deepgram.com
11=Parakeet-tdt
12=Whisper.cpp
13=Faster-Whisper-XXL.exe
14=WhisperX
15=302.AI
16=ElevenLabs.io
17=Google识别API(免费)
18=STT语音识别(本地)
19=Whisper.NET
20=CAMB AI
21=自定义识别API

支持的模型名称,仅适用于 faster-whisper和openai-whisper渠道，其他渠道请查看软件 (--model_name): tiny, small, base, medium, large-v3-turbo, large-v1, large-v2, large-v3

附录2: 配音渠道列表 (`--tts_type`)

在软件ui中，对应着具体的配音渠道顺序号，从0开始

选择目标语言和配音渠道后，将在软件ui中显示可用的具体角色名称

0=Edge-TTS(免费)

1=Qwen3-TTS(本地内置)
2=OmniVoice(本地API)
3=Piper(本地内置)
4=VITS(本地内置)
5=GPT-SoVITS(本地API)
6=F5-TTS(本地API)
7=Index-TTS(本地API)
8=CosyVoice(本地API)
9=Supertonic(本地内置)
10=VoxCPM(本地API)
11=ChatterBox(本地API)
12=豆包语音合成模型2.0
13=Qwen3-TTS
14=XiaoMi-TTS
15=GLM-TTS 智谱AI
16=Minimaxi-TTS
17=OpenAI-TTS
18=Gemini TTS
19=Elevenlabs.io
20=X.AI TTS
21=Azure-TTS
22=302.AI
23=ChatTTS(本地API)
24=Spark-TTS(本地API)
25=Dia-TTS(本地API)
26=kokoro-TTS(本地API)
27=clone-voice(本地API)
28=Fish-TTS(本地API)
29=gTTS(free)
30=CAMB AI TTS
31=MOSS-TTS-Nano
32=自定义TTS API

附录3: 翻译渠道列表 (`--translate_type`)

在软件ui中，对应着具体的翻译渠道顺序号，从0开始

0=Google(免费)
1=微软(免费)
2=M2M100(本地)
3=OpenAI ChatGPT
4=DeepSeek
5=Gemini AI
6=智谱AI
7=AzureGPT AI
8=兼容AI/本地模型
9=OpenRouter
10=硅基流动
11=302.AI
12=阿里百炼
13=字节大模型
14=腾讯翻译
15=百度翻译
16=DeepL
17=DeepLx
18=阿里机器翻译
19=LibreTranslate(本地)
20=MiniMax AI
21=XiaoMi AI
22=CAMB AI
23=自定义翻译API

附录4: 语言代码列表

适用于 --source_language_code 和 --target_language_code

代码	语言	代码	语言	代码	语言
en	英语	zh-cn	简体中文	zh-tw	繁体中文
fr	法语	de	德语	ja	日语
ko	韩语	ru	俄语	es	西班牙语
th	泰语	it	意大利语	pt	葡萄牙语
vi	越南语	ar	阿拉伯语	tr	土耳其语
hi	印地语	hu	匈牙利语	uk	乌克兰语
id	印尼语	ms	马来语	kk	哈萨克语
cs	捷克语	pl	波兰语	nl	荷兰语
sv	瑞典语	he	希伯来语	bn	孟加拉语
fa	波斯语	fil	菲律宾语	ur	乌尔都语
yue	粤语	el	希腊语	km	高棉语
nb	挪威语	ro	罗马尼亚语

pyVideoTrans 命令行工具使用手册 ​

⚠️ 重要提示：开始之前 ​

1. 语音转录 (STT) ​

基本命令格式 ​

参数详解 ​

使用示例 ​

2. 文字配音 (TTS) ​

基本命令格式 ​

参数详解 ​

使用示例 ​

3. 字幕翻译 (STS) ​

基本命令格式 ​

参数详解 ​

使用示例 ​

4. 视频翻译 (VTV) ​

基本命令格式 ​

参数详解 ​

使用示例 ​

附录：渠道与代码代码对照表 ​

附录1: 语音识别渠道列表 (--recogn_type) ​

附录2: 配音渠道列表 (--tts_type) ​

附录3: 翻译渠道列表 (--translate_type) ​

附录4: 语言代码列表 ​

pyVideoTrans 命令行工具使用手册

⚠️ 重要提示：开始之前

1. 语音转录 (STT)

基本命令格式

参数详解

使用示例

2. 文字配音 (TTS)

基本命令格式

参数详解

使用示例

3. 字幕翻译 (STS)

基本命令格式

参数详解

使用示例

4. 视频翻译 (VTV)

基本命令格式

参数详解

使用示例

附录：渠道与代码代码对照表

附录1: 语音识别渠道列表 (`--recogn_type`)

附录2: 配音渠道列表 (`--tts_type`)

附录3: 翻译渠道列表 (`--translate_type`)

附录4: 语言代码列表