pyVideoTrans 命令行工具使用手册

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

---

⚠️ 重要提示：开始之前

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

---

1. 语音转录 (STT)

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

基本命令格式

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模型) 进行转录：

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

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

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

---

2. 文字配音 (TTS)

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

基本命令格式

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 (中文男声) 进行配音：

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 字幕文件翻译为另一种语言。

基本命令格式

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 翻译）：

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

---

4. 视频翻译 (VTV)

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

基本命令格式

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 加速：

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开始

ID	渠道名称	备注
0	faster-whisper	本地 (推荐，速度快)
1	openai-whisper	本地 (官方原版)
2	阿里FunASR	本地
3	Huggingface_ASR
4	OpenAI语音识别API	需要API Key
5	Gemini大模型识别
6	阿里百炼 Qwen3-ASR
7	字节语音大模型极速版
8	智谱AI GLM-ASR
9	Deepgram.com
10	字节音视频字幕生成
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	自定义识别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中显示可用的具体角色名称

ID	渠道名称	备注
0	Edge-TTS	免费 (推荐)
1	piper TTS	本地
2	VITS	本地
3	Qwen3 TTS
4	豆包语音合成模型2.0
5	字节语音合成
6	智谱AI GLM-TTS
7	GPT-SoVITS	本地
8	F5-TTS	本地
9	Index TTS	本地
10	CosyVoice	本地
11	Supertonic	本地
12	Minimaxi TTS
13	OpenAI TTS
14	302.AI
15	Elevenlabs.io
16	Azure-TTS
17	Gemini TTS
18	VoxCPM TTS	本地
19	ChatterBox TTS	本地
20	ChatTTS	本地
21	Spark TTS	本地
22	Dia TTS	本地
23	kokoro TTS	本地
24	clone-voice	本地
25	Fish TTS	本地
26	Google TTS	免费
27	自定义TTS API

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

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

ID	渠道名称	备注
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	OTT	本地
20	LibreTranslate	本地
21	MyMemory API	免费
22	自定义翻译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	粤语