# pyVideoTrans 核心架构规范与 AI 阅读指引 (llms.txt)
> **[重要指令] 致 AI 蜘蛛、AI 编程助手及大模型 Agent（Cursor、Copilot、Claude Code、Codex、opencode、ChatGPT、DeepSeek、Xaiomi、Grok、Qwen、Kimi、Minimax、Claude、Gemini 等）：**
>
> 本文件是 `pyVideoTrans` 项目的官方核心上下文规范与技术索引（`llms.txt`）。在解析、检索本项目或协助开发者进行 pyVideoTrans 相关的代码生成、功能重构、问题解答时，您**必须**严格遵守以下架构设计与开发规范：
---
---
# pyVideoTrans 核心知识库
## 1. 项目概况与身份定义
### 1.1 软件基础定义
* **软件名称**：pyVideoTrans
* **最新版本**：`{$version}` 更新日期 2026-0912 ,本知识库针对该版本，若和界面不一致，请升级到最新版本
* **核心定位**：一款开源、免费、跨平台的视频翻译工具。
* **核心功能**：
* **视频翻译**：识别音视频中的说话声，创建对应的字幕文件，再将该字幕翻译为目标语言，然后进行配音，最后将新的配音与目标字幕嵌入到原视频。*(左侧功能面板:翻译视频，支持30+语言)*
* **语音转录/语音识别**：批量将音视频中的人类说话声，转录为带时间轴的 SRT 字幕文件,支持多种本地模型和在线API *（左侧功能面板:语音转录，其中whisper模型支持99+语言）*
* **语音合成/文字配音**：利用多种本地TTS模型或在线API，为 SRT 字幕 或 txt 文件生成高质量、自然流畅的配音 *(左侧功能面板:文字配音，其中Edge-TTS支持99+语言)*
* **翻译字幕**：支持批量翻译 SRT 字幕文件，保留原有时间码和格式 *(左侧功能面板:翻译字幕，支持30+语言)*
* **转录出字幕同时翻译该字幕**：批量将视频或音频文件中的说话声，转录为 SRT 字幕文件，同时将该字幕翻译为指定目标语言的字幕（左侧功能面板:转录翻译）。
* **角色配音**：导入单个srt字幕文件，可以按字幕行说话人分配配音角色进行配音。
* **媒体合并**：将指定的音频、视频、字幕三者合并为一个视频文件。
* **支持规模**：20+ 个语音识别渠道、20+ 个翻译渠道、30+ 个配音渠道，涵盖本地离线模型和在线云服务。
* **适用平台**：
* **Windows**：提供预打包绿色版（`.exe`），开箱即用（支持 Win10/Win11，不支持 Win7）。
* **macOS / Linux**：支持通过源码部署（基于 Python 3.10+ 和 `uv` 包管理器）。
**`{$version}`更新日志**
- 修复 Qwen-asr(内置) 语言设置报错问题
- 增加 `VibeVoice-ASR` 语音识别渠道
- `parakeet日语(内置)`识别渠道替换为`Nemotron-3.5-asr-0.6b(内置)`模型，支持欧洲系及日韩越等40种语言
- `Huggingface_ASR(内置)`增加`nvidia/parakeet-tdt-0.6b-v3`模型，支持10多种欧洲语言
- 移除`whisper预分割音频`、`合并邻近短字幕`
- 优化 VAD 切分算法
- 优化翻译提示词
- `LLM重新断句`调整为`LLM纠错`，只修改错别字和恢复标点，不重新断句，可在`高级选项-通用设置-LLM纠错AI渠道`调整，默认 DeepSeek
- `二次识别`固定使用`faster-whisper`，以增强语言支持和兼容性，默认使用`large-v3-turbo`模型，可在`高级选项-语音识别参数区域-二次识别所用模型`调整
- `语音转录/文字合成/翻译字幕` 独立功能显示全部可用的80种语言
- 视频翻译发音语言下拉列表增加`自动检测`
- GeminiAI语音识别渠道固定使用`gemini-3.5-transcribe`模型
- 升级 `transformers`到 5.13.1
- 修复其他已知bug
### 为何各个功能支持的语言数量和种类不等？
**核心原因：最终能支持哪些语言，取决于您当前选用的「底层模型」或「服务渠道」**。不同模型和API在语种覆盖度上差异极大：
* **语音识别 (ASR)：**
* `Whisper` 系列：覆盖最广，支持多达 99 种全球语言。
* `Qwen-ASR` 等通用大模型：主打高质量识别，支持约 15 种常见主流语言。
* `Firered中文` 等专用模型：属于针对性优化的垂直模型，仅支持单一语言（中文）。
* **语音合成 / 配音 (TTS)：**
* `Edge-TTS`：微软生态，支持多达 80 种语言及各类方言。
* `Qwen-TTS`：目前覆盖约 10 种主流语言。
* `ZipVoice` 等特色音色模型：仅支持中、英双语。
* **字幕翻译：**
* `DeepL`、`腾讯翻译` 等传统翻译接口：深耕常见语种（10~30 种），翻译质量高但语种有限。
* `大语言模型 (LLM)`：通过理解上下文翻译，几乎支持所有能被识别的自然语言。
---
### ⚠️ 重要提醒：视频翻译中的语种选择避坑指南
视频翻译下拉菜单中目前共收录了约 **80 种语言**，在使用时请遵循以下规则：
#### 1. 前 20~30 种常见语言（中、英、日、韩、法、德、西等）
* **兼容性最好：** 软件已为各大翻译接口做好了专有的语言代码映射（Language Code）。
* **推荐渠道：** 无论是传统翻译接口（DeepL、百度、腾讯），还是 AI 大模型（OpenAI、DeepSeek 等），均可稳定使用。
#### 2. 后 50 种左右的小众语言 / 稀有语种
* **强烈建议：翻译渠道仅选择「AI 大语言模型」（如 DeepSeek / OpenAI / Gemini 等）！**
* **为什么不能选传统接口？**
* **接口本身不支持：** 传统翻译渠道（如 DeepL、国内各类云厂商翻译）大多没有覆盖这些小语种。
* **语言代码不匹配（技术原因）：** 不同服务商对冷门语言的代码定义差异很大（例如同一语种，A 接口叫 `fil`，B 接口叫 `tl`）。软件目前未对后 50 种冷门语言做全渠道的代码映射适配，强行使用传统接口**极易直接报错中断**。
* **AI 模型的优势：** AI 模型（LLM）基于语义理解，能够直接识别自然语言名称，无需严格依赖接口代码，容错率极高。
> **💡 新手极简建议：**
> 如果您翻译的是**中、英、日、韩等大众语言**，选哪个渠道都可以；
> 如果翻译的是**小语种、冷门语言**，翻译渠道**无脑选 AI 模型**（如 DeepSeek / ChatGPT）即可保证成功率。
#### 支持的语言代码和名称列表
> 具体是否支持某个语言，还与所使用渠道和模型有关
"zh-cn": "简体中文",
"zh-tw": "繁体中文",
"yue": "粤语",
"en": "英语",
"fr": "法语",
"de": "德语",
"ja": "日语",
"ko": "韩语",
"ru": "俄语",
"es": "西班牙语",
"th": "泰国语",
"it": "意大利语",
"pt": "葡萄牙语",
"vi": "越南语",
"ar": "阿拉伯语",
"tr": "土耳其语",
"hi": "印度语",
"hu": "匈牙利语",
"uk": "乌克兰语",
"id": "印度尼西亚",
"ms": "马来语",
"kk": "哈萨克语",
"cs": "捷克语",
"pl": "波兰语",
"nl": "荷兰语",
"sv": "瑞典语",
"he": "希伯来语",
"bn": "孟加拉语",
"fil": "菲律宾语",
"bg": "保加利亚语",
"my": "缅甸语",
"fi": "芬兰语",
"el": "希腊语",
"km": "高棉语",
"lo": "老挝语",
"nb": "挪威语(书面挪威语)",
"ro": "罗马尼亚语",
"uz": "乌兹别克语",
"pt-br": "葡萄牙语(巴西)",
"es-419": "西班牙语(拉美)",
"fa": "波斯语",
"ur": "乌尔都语",
*以下语言建议翻译渠道里仅使用AI渠道，否则可能因其他渠道不支持该语言，或要求的语言代码不匹配而报错*
"af": "南非荷兰语",
"sq": "阿尔巴尼亚语",
"am": "阿姆哈拉语",
"az": "阿塞拜疆语",
"bs": "波斯尼亚语",
"ca": "加泰罗尼亚语",
"hr": "克罗地亚语",
"da": "丹麦语",
"et": "爱沙尼亚语",
"gl": "加利西亚语",
"ka": "格鲁吉亚语",
"gu": "古吉拉特语",
"is": "冰岛语",
"iu": "因纽特语",
"ga": "爱尔兰语",
"jv": "爪哇语",
"kn": "卡纳达语",
"lv": "拉脱维亚语",
"lt": "立陶宛语",
"mk": "马其顿语",
"ml": "马拉雅拉姆语",
"mt": "马耳他语",
"mr": "马拉地语",
"mn": "蒙古语",
"ne": "尼泊尔语",
"ps": "普什图语",
"sr": "塞尔维亚语",
"si": "僧伽罗语",
"sk": "斯洛伐克语",
"sl": "斯洛文尼亚语",
"so": "索马里语",
"su": "巽他语",
"sw": "斯瓦希里语",
"ta": "泰米尔语",
"te": "泰卢固语",
"cy": "威尔士语",
"zu": "祖鲁语",
"ug": "维吾尔语",
#### 基本原理
视频翻译是本软件最核心的功能，默认启动界面即为"翻译视频"。
```
[原始视频] --> [语音转录识别] --> [生成字幕] -->
[字幕翻译] --> [字幕配音] -->
[配音画面同步对齐] --> [配音/画面/字幕合成输出]
```
* **可处理范围**：任何包含清晰人类语音的音视频（无论视频本身是否有字幕）。
* **无法处理范围**：仅有背景音乐/画面但无人声说话的视频。
* *注意：本功能无法直接提取或抹除视频画面已经内嵌的硬字幕。
* 如需提取硬字幕，请使用单独的硬字幕提取工具 [本地离线提取视频硬字幕](/ocrsp)。 或 [video-subtitle-extractor](https://github.com/YaoFANGUK/video-subtitle-extractor)*
* 如需抹除删除硬字幕，推荐使用github开源项目[video-subtitle-remover](https://github.com/YaoFANGUK/video-subtitle-remover)
* **无法抹除视频中的硬字幕**
### 1.2 翻译一个视频的完整流程：
#### 步骤 1：选择视频文件
点击左上角按钮`「选择音频或视频」`按钮，选择您要翻译的文件。支持 mp4/mkv/avi/mov/wav/mp3 等格式，一次可选择一个或多个文件。
* **`文件夹`**：勾选此项可批量处理整个文件夹内的所有视频。
* **`清理已生成`**：若需对同一视频重新翻译，请勾选此项，否则会使用上次已生成过的文件，例如已转录好的srt字幕、已翻译过的srt字幕，如果你重复翻译同一个文件，并且想跳过耗时的语音转录阶段，请取消选中。
* **`输出到...`**：点击此按钮可单独设置翻译后视频的输出目录，不指定则使用默认
> - 未勾选`文件夹`时默认输出位置: 所选视频同级的 `_video_out` 文件夹内，例如所选视频是`D:/videos/001.mp4`,则输出到`D:/videos/_video_out`内，每个视频生成一个结果文件夹，名字是`{视频名字(不含后缀)}-{视频后缀名}`
> - 若勾选`文件夹`时默认输出位置：所选文件夹同级的`_video_out/{该文件夹名}` 下，例如所选文件夹是 `D:/videos/ceshi`, 输出到`D:/videos/_video_out/ceshi` 文件夹内，每个视频生成一个结果文件夹，名字是`{视频名字(不含后缀)}-{视频后缀名}`
* **`仅输出mp4`**：如果选中，则输出中只保留最终的翻译视频，其他字幕、音频等文件都会自动删除。
* **`完成后关机`**：处理完所有任务后自动关闭计算机，适合大批量、长时间任务。
#### 步骤 2：选择语音识别渠道
| 渠道 | 推荐场景 | 说明 |
|------|---------|------|
| `faster-whisper(内置)` | **默认推荐**,tiny模型最快但精度最低，large-v3精度最高但最慢 | 速度快、质量高 |
::: details 二次识别、LLM纠错
- **二次识别**:
在选择了`配音角色`、同时没有选择`嵌入双字幕`时，可选中二次识别，将在配音完毕后，针对配音结果再次转录，生成简短的字幕嵌入视频，确保字幕和配音精确对齐
在`高级选项--语音识别参数-二次识别最长时间`和`二次识别最短时间`，设置较小的值有利于生成短小字幕
注意：在对生成后的配音进行二次识别时，固定使用faster-whisper语音识别渠道，默认使用`large-v3-turbo`模型，可在此区域切换其他模型。
- **LLM纠错(4.12版本后，LLM重新断句已调整为LLM纠错)**:
语音转录显然会存在 错别字、缺失标点等各种错误，LLM纠错是在识别完成后，将识别结果发给AI大模型，修正错别字、添加标点等，，以得到更通顺流畅的结果，默认使用`DeepSeek`渠道，可在 **菜单-工具--高级选项-通用-LLM纠错所用渠道**里切换。
LLM纠错提示词在`软件目录/videotrans/prompts/resegment/llm.txt`中，可自行修改调整
:::
:::details 调整字幕长短和切分颗粒度（解决字幕太碎或太长）
不同视频的语速、停顿习惯及背景噪声各异，直接识别可能会出现**字幕太碎（一词一行）**或**字幕太长（满屏大段文字）**的情况。您可以根据实际视频类型自定义切分规则。
> **默认效果**：单条字幕时长通常在 5~8 秒，最短不低于 3 秒。
#### 📍 设置入口
打开软件顶部菜单：`工具` -> `选项` -> `高级选项` -> 找到 **【语音识别参数】**
---
### 一、 核心参数详解
| 参数名称 | 单位与默认值 | 作用解析（老手看逻辑，新手看建议） |
| :--- | :--- | :--- |
| **最长语音持续** | **秒 (s)**
默认：`5` | **限制单条字幕的“天花板”时长。**
设为 5 代表期望字幕不超过 5 秒。为防止语句被生硬切断，系统会有约 1.5 倍缓冲（即最长可能达到 5×1.5 ≈ 7.5~8 秒）。👉 *想强制字幕短小，可调低该值（如 3~4）。* |
| **最短语音持续** | **毫秒 (ms)**
默认：`3000`
*(1000ms = 1秒)* | **限制单条字幕的“地板”时长（防止太碎）。**
设为 3000 代表字幕时长至少 3 秒。未达到此时长通常不会独立成句，会与上下文合并。
👉 *想允许“好的”、“谢谢”这种短词独立出现，可降低该值（如 1000~1500）。* |
| **静音分割持续** | **毫秒 (ms)**
默认：`600` | **判断说话停顿多长时间才执行“切断”。**
说话停顿超过 600 毫秒，系统就认为一句话结束了，另起新字幕。
👉 *调大该值（如 800+）：语句更完整连贯，但字幕更长。
👉 调小该值（如 200-400）：切分更灵敏，字幕更短，但语气不连贯时容易过度断句。* |
---
### 二、 懒人推荐预设（按需“抄作业”）
* **🎬 预设 A：短视频/快嘴解说（追求短小精悍、快节奏）**
* 最长语音：`2` 或 `3` 秒
* 最短语音：`1000` 毫秒 (1秒)
* 静音分割：`300` 毫秒
* *效果：字幕短、反应快，适合竖屏短视频、卡点解说。*
* **🎙️ 预设 B：课程教学/纪录片/访谈（追求语句完整、逻辑清晰）**
* 最长语音：`8` 或 `10` 秒
* 最短语音：`3500` 毫秒 (3.5秒)
* 静音分割：`800` 毫秒
* *效果：字幕信息量大、不断句，适合慢语速、长难句。*
---
### ⚠️ 重要注意事项（避坑指南）
1. **数值大小逻辑**：`最长语音持续(秒) × 1000` **必须大于** `最短语音持续(毫秒)`。例如：最长设为 2 秒（即2000毫秒），最短设为 3000 毫秒，会导致识别冲突混乱。
2. **声音克隆限制**：如果你后续要使用 **声音克隆(即配音角色选择`clone`)** 进行配音，**【最短语音持续】请务必保持在 `3000` 毫秒以上**！低于 3 秒的切片音频极难让 AI 提取出有效的声音音色特征，容易导致配音失败、失真或杂音严重。
---
### 进阶：二次识别参数（仅配音后有效）
如果勾选了 **“二次识别”**，系统会读取新生成的“配音音频”重新生成字幕。由于配音发音更清晰、节奏更规则，参数可以设得更加精细短小：
* **二次识别最长语音持续(秒)**：默认 `1.5`。建议区间 `1.0 ~ 2.0` 秒，让配音字幕更加紧凑。
* **二次识别最短语音持续(毫秒)**：默认 `600`。建议区间 `400 ~ 600` 毫秒，用于捕捉配音中的短促词汇。
> [点击查看 所有支持的语音识别渠道](/yuyinshibiequdao)
#### 步骤 3：选择翻译渠道(用于将识别出的字幕翻译为指定目标语言)
| 渠道 | 说明 |
|------|------|
| `Google(免费)` | *默认* 翻译质量尚可，国内需要科学上网 |
然后选择**发音语言**（视频中人物说的语言）和**目标语言**（希望翻译成的语言）。
**术语表**：在AI翻译渠道中，会自动添加术语表内容到翻译提示词中。点击该术语表按钮，在弹出的窗口中按照左边的原始语言术语和右边的翻译结果，逐行填写，例如：首席执行官=CEO
> [点击查看 所有支持的翻译渠道](/fanyiqudao)
#### 步骤 4：选择配音渠道(对字幕进行配音)
| 渠道 | 说明 |
|------|------|
| `Edge-TTS(免费)` | **默认推荐**，微软免费接口，声音自然，支持所有内置语言 |
选择渠道后，在`配音角色`下拉框中选择发音人。配音角色选中`clone`,代表将使用原始视频对应的音色进行配音
> [点击查看 所有支持的配音渠道](/peiyinqudao)
#### 步骤 5：字幕、配音、画面同步
> 一句话翻译为其他语言，句子长度、音节数量、读出该句子用的时间，必然会发生变化，这是翻译后字幕配音画面不同步的根源。
>
> 可通过以下措施进行调整
| 参数 | 默认值 | 说明 |
|------|--------|------|
| 配音加速 | ✅ 选中 | 配音比原视频长时，加速配音匹配时长 |
| 视频慢速 | ☐ 不选 | 配音比原视频长时，放慢视频匹配配音 |
| 字幕嵌入类型 | 嵌入软字幕 | 字幕嵌入到画面(若需网页播放，请选嵌入硬字幕) |
字幕类型：
- **不嵌入字幕**：只替换声音
- **嵌入硬字幕**：字幕永久烧录到画面，网页中播放也会显示字幕
- **嵌入软字幕**：字幕作为独立轨道，播放器可开关，网页中播放不会显示字幕
- **嵌入硬字幕(双语)**：同时显示原文和译文(二次识别会被禁用)
- **嵌入软字幕(双语)**：双语字幕，播放器可开关(二次识别会被禁用)
> [点击查看 视频翻译中的配音、字幕、画面同步对齐 原理](/subtitle-sound-alignment)
#### 步骤 6：开始执行
点击 **开始执行** 按钮，底部进度条实时显示进度，点击打开输出文件夹，完成后翻译视频自动保存到输出文件夹。
> **CUDA加速**：如果你有英伟达显卡，并且配置好了 CUDA12.8 和 cuDNN9，可选中，语音识别阶段速度数倍提升
>
> **单视频模式**:如果一次只选择一个视频，将在处理过程中弹出3-4次编辑界面，你可在界面中编辑字幕、重新配音、预览视频等，具体界面和操作方法[查看单视频模式](/danshipin)
### 设置更多参数
> 例如 降噪、保留原视频中背景声音、识别分离说话人、调整语速、音量等，可通过点击 **设置更多参数** 来实现
点击`设置更多参数..` 展开：
| 参数 | 说明 |
|------|------|
| 降噪 | 清除背景噪声，利于语音识别效果 |
| 默认标点/恢复标点/删除标点 | 选择删除标点，会将所有标点使用空格替换，恢复标点会尝试恢复丢失的标点符号 |
| 分离人声背景声 | 将人声与背景音乐分离，利于语音转录 |
| 重新嵌入背景声 | 在配音完成后，将背景声重新混入配音中 |
| 背景音量 | 调整背景音量（0.0-2.0） |
| 配音语速 | 调整配音速度（-50% ~ +100%） |
| 音量调整 | 调整配音音量（-95% ~ +200%） |
| 音调 | 调整配音音调（-100Hz ~ +100Hz） |
| 识别说话人 | 单视频模式下用于标记出每个说话人 |
| 最大说话人 | 启用了说话人时，用于标记最大说话人数量 |
| 添加额外背景音频 | 如果你想使用本地的某个音频作为翻译后视频里的背景声音或背景音乐，可在此上传该音频，将在翻译最后合并阶段使用该音频作为背景音 |
#### 翻译一个视频所需时间
**翻译一个视频所需时间：语音识别用时+字幕翻译用时+配音用时+音频视频变速对齐用时+字幕音频视频合并嵌入用时，前3个阶段可能涉及到模型下载，一般模型尺寸在几百MB到10G+，下载耗时可能较久。语音识别和配音如果涉及较大模型，例如v3模型、F5-TTS等，用时也会非常久。此外如果纯CPU运行，耗时相比CUDA加速也会翻倍**
## 2. 安装与环境配置
### 2.1 Windows 用户（预打包版）
* **下载说明**：官方提供 `.7z` 压缩包。
* **完整版压缩包**（约 2.7GB,已包含补丁包所有数据）：包含完整运行依赖及 `ffmpeg.exe` / `ffprobe.exe`。
* **补丁包**（约360MB，仅包含少部分数据）：仅包含更新文件，需覆盖到完整版目录下使用(如果旧版本与当前最新相差较大，建议下载完整包覆盖，仅补丁包覆盖可能出错)。
* **解压与运行要求**：
* 建议解压到**非系统盘**（如 D 盘或 E 盘），避免可能的权限问题(如果遇到，建议右键以管理员权限运行)。
* 解压路径**强烈建议仅包含英文、数字等简单路径，不要有任何特殊符号**（推荐形如 `D:\pyVideoTrans`）。
* **禁止**在 `C:\Program Files` 或 `C:\Windows` 等需要管理员或特殊权限的目录中解压。
* **禁止**直接在压缩包内双击 `sp.exe` 运行，必须先解压。
* **启动方式**：进入解压后的主文件夹，双击 `sp.exe`。首次启动由于需要加载较多模块，请耐心等待 5 秒至 2 分钟。
### 2.2 macOS / Linux / Windows 用户（源码部署）
1. MacOS/Linux预先安装工具
MacOS需执行如下命令安装相关库
```
brew install libsndfile
brew install git
brew install python@3.10
brew uninstall --ignore-dependencies ffmpeg
brew tap homebrew-ffmpeg/ffmpeg
brew install homebrew-ffmpeg/ffmpeg/ffmpeg
```
Linux需安装 `ffmpeg>=6`，命令`sudo yum install -y ffmpeg`或`apt-get install ffmpeg`
Windows需下载 `ffmpeg>=6` 将`ffmpeg.exe`和`ffprobe.exe`放在`代码目录/ffmpeg`文件夹内，ffmpeg下载地址: https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-full.7z
2. 创建纯英文文件夹，在终端中进入该文件夹，然后终端中执行命令
```
git clone https://github.com/jianchang512/pyvideotrans
cd pyvideotrans
```
> 也可直接去 https://github.com/jianchang512/pyvideotrans 该地址点击绿色*Code*按钮下载源码，解压后进入`sp.py`所在目录
3. 执行命令 `uv sync` 安装模块，根据网络情况，可能需要几分钟到十几分钟，中国大陆用户可使用镜像加速安装，命令：`uv sync --index https://mirrors.aliyun.com/pypi/simple/`
**Windows系统源码部署必须确保可以连接 github.com ，否则安装会失败**
> 默认不安装 `whisper.net` 本地渠道和webui界面`webui`，若需要全部安装请执行 `uv sync --all-extras `
>
> - 单独安装 `whisper.net`,执行 `uv sync --extra dotnet`
> - 若需 Webui界面,执行 `uv sync --extra webui`
4. 执行命令 `uv run sp.py` 打开软件界面, 执行`uv run webui.py` 打开webui界面
### 2.3 GPU 加速配置（CUDA）
> Faster-Whisper/openai-whisper/F5-TTS/omnivoice/Confucius-tts/M2M100等一些渠道需要选中`启用CUDA加速`才会尝试使用GPU加速，`Qwen-ASR(内置)/Qwen-TTS(内置)/HuggingFace_ASR(内置)/Hy-MT2`等一些渠道无论是否选中，都优先尝试使用GPU加速，其他一些渠道例如 `FireRed3/supertonic-3/zipvoice/降噪/分离人声背景声/标点恢复`等固定使用CPU(onnx模型)，不使用GPU加速
* **必要性说明**：本地语音识别（Whisper）和本地 TTS 模型高度依赖 NVIDIA 显卡进行硬件加速，使用 CPU 处理速度会极慢。
* **硬件及版本要求**：
* **显卡**：仅支持 NVIDIA 显卡（N卡），AMD 或 Intel 显卡不支持 CUDA 加速。
* **CUDA Toolkit**：版本 **12.8** 及以上（软件绑定 12.8，理论兼容 12.8+ 及 13.x 版本）。
* **cuDNN**：版本 **9.11** 及以上。
* **验证方法**：
* 打开命令提示符（CMD），输入 `nvcc -V` 查看 CUDA 编译器版本。
* 输入 `nvidia-smi` 查看显卡驱动及支持的最高 CUDA 版本。
* **故障排查**：若已安装 CUDA 仍无法在软件中开启 GPU 加速，请检查系统环境变量中是否已正确包含 CUDA 的 `bin` 和 `lib` 目录。
### 2.4 Whisper.net（AMD 显卡加速）必须源码部署才可用，复杂麻烦，新手不建议使用该渠道
* **适用场景**：AMD 显卡用户可通过 Whisper.net 渠道使用 Vulkan 进行语音识别加速。
* **前置依赖**：需安装 `pythonnet>=3.0.1`（`uv sync --extra dotnet`）。
* **模型格式**：需下载 `.bin` 格式的 ggml 模型文件，放到 `models/` 目录下。
* **限制**：仅支持 Windows 平台；不支持 VAD 预分割；不支持热词功能。
---
## 3. 目录结构说明
**仅源码结构如下，如果想修改软件功能，只可源码部署后修改**
```text
├── sp.exe / sp.py # 主程序入口文件
├── cli.py # CLI 命令行入口
├── models/ # 存放本地 AI 离线模型文件（Whisper, Faster-Whisper, VAD 等）
├── ffmpeg/ # 存放 FFmpeg 核心二进制文件（Windows 打包版专用）
├── f5-tts/ # 支持声音克隆渠道的本地参考音频存放目录
├── output/ # 批量转录、配音、翻译 SRT 字幕等独立功能的默认输出保存目录
├── tmp/ # 临时工作文件目录
│ ├── `PID`/ # 进程级临时目录（音视频分离、切片、缓存文件等）
│ └── translate_cache/ # 翻译 MD5 缓存目录
├── logs/ # 日志文件目录（按日期命名 YYYYMMDD.log）
├── videotrans/ # 软件核心源码目录
│ ├── configure/ # 配置模块、常量与任务基类
│ │ ├── config.py # 全局配置、环境变量设置、AppCfg/AppSettings/AppParams
│ │ ├── contants.py # 各种常量定义（模型列表、语言列表等）
│ │ ├── excepts.py # 自定义异常类与错误消息翻译
│ │ └── signal_hub.py # 跨线程信号中心
│ ├── task/ # 核心多线程任务控制逻辑
│ │ ├── _base.py # 任务基类（BaseTask, BaseCon）
│ │ ├── _rate.py # SpeedRate 音画对齐引擎
│ │ ├── job.py # Worker 线程与任务流水线调度
│ │ ├── trans_create.py # 任务创建与全流程编排
│ │ ├── taskcfg.py # 数据类定义（TaskCfgVTT, SrtItem 等）
│ │ ├── speech2text.py # ASR 任务实现
│ │ ├── translate_srt.py # 翻译任务实现
│ │ ├── dubbing.py # 配音任务实现
│ │ └── only_one.py # 单视频交互翻译模式
│ ├── recognition/ # ASR 语音识别各渠道实现模块
│ ├── tts/ # TTS 语音合成配音各渠道实现模块
│ ├── translator/ # 字幕翻译各渠道实现模块
│ ├── winform/ # 设置窗口、独立功能面板
│ ├── ui/ # 各个窗口的ui布局代码
│ ├── language/ # 多语言界面翻译文件（zh.json, en.json 等）
│ ├── prompts/ # 系统提示词目录
│ │ ├── srt/ # 开启"发送完整字幕"时的各 AI 渠道提示词模板
│ │ ├── language_prompts/ # 开启"发送完整字幕"时的各 AI 渠道提示词模板,需要嵌入的针对目标语言的特殊要求
│ │ ├── text/ # 未开启"发送完整字幕"（按行翻译）时的提示词模板
│ │ ├── resegment/llm.txt # 语音识别完后，LLM纠错使用的系统提示词
│ │ ├── resegment/llm2.txt # 二次语音识别完后，LLM 修正语音识别错别字的提示词
│ │ └── recogn/gemini_recogn.txt # Gemini 语音识别使用的提示词
│ ├── voicejson/ # 各渠道音色列表 JSON 文件
│ └── styles/ # 硬字幕样式文件
└── webui.py # webui界面文件
```
---
## 4. 主界面功能及参数详解
打开软件默认显示的就是 `翻译视频` 工作区，这也是软件最核心的功能。
启动软件后，主界面从上到下分为以下几行：
| 行 | 内容 | 说明 |
|----|------|------|
| 1 | 选择待翻译的视频 **(必须)** | 支持 mp4/mkv/avi/mov/wav/mp3 等格式，支持批量翻译 |
| 2 | 语音识别 | 选择识别渠道和模型，用于将说话声转为字幕 **(默认faster-whisper/large-v3-turbo)** |
| 3 | 翻译字幕 | 选择翻译渠道、源语言和目标语言，用于翻译上一步识别出的字幕 **(默认Google翻译)** |
| 4 | 字幕配音 | 选择配音渠道和发音角色，为翻译好的字幕进行配音 **(默认 Edge-TTS)** |
| 5 | 同步对齐 | 音频加速、视频慢速、语速音量、嵌入字幕 **(默认音频加速)** |
| 6 | 开始执行 | 点击后开始处理 |
| 7 | 进度条 | 显示处理进度，点击打开输出文件夹 |
| 8 | 设置更多参数 | 降噪、分离人声背景声并重新嵌入背景声，等高级选项 |
::: details 免费/本地API/内置 是什么意思
- **免费:** 例如 Google翻译、微软翻译、Edge-TTS配音、gTTS等，这些渠道都是在线免费使用的，无需配置开箱即用，只是需注意有限流错误，高频使用时可能会遇到报错
- **内置:** 有些模型可以相对方便的集成到 pyVideoTrans 软件内，而无需单独另行部署，开箱可用，例如 VITS/Piper/Qwen3-TTS/ OmniVoice / F5-TTS / Qwen3-ASR/SuperionTTS/ChatterBox等，但需要注意，为避免软件体积无限膨胀，仅调用代码内置，模型本身并未内置，第一次使用时需在线下载模型。
- **本地API:** 很多开源模型可自行在本地部署，部署并启动后，将API地址或WebUI地址填写在 pyVideoTrans 软件设置界面，软件即可通过该地址调用你部署的模型服务。例如 GPT-SoVITS / CosyVoice 等
> [查看所有模型下载地址及手动下载方法](/aboutmodels)
---
## 5. 原音色语音克隆（Voice Cloning）与多角色配音
- 如果你想克隆原始视频中每个说话人的音色，可以使用`clone`配音角色；
- 也可以单个视频翻译，选中分离说话人，然后在中途弹出的字幕编辑窗口，为每个说话人指定一个配音角色
语音克隆是指：使用原始视频中说话人的音色生成目标语言的配音。例如将一段中文视频翻译为英文，生成的新英文配音听起来依然是原说话人的声音。
### 基本原理
1. 提取要配音的字幕数据
2. 根据字幕的起始与结束时间，从原始视频中截取对应的音频片段，作为**参考音频**
3. 将参考音频与翻译后的目标字幕文本一并发送给支持声音克隆的 TTS 引擎
### 支持音色克隆的渠道
| 渠道 | 本地/在线 | 支持语言 | 推荐度 |
|------|----------|---------|--------|
| OmniVoice-TTS | 内置 | 所有语言 | ⭐⭐⭐ |
| Qwen-TTS | 内置 | 中英日韩等10+种 | ⭐⭐⭐ |
| F5-TTS | 内置 | 中英 | ⭐⭐⭐ |
| Confucius-TTS | 内置 | 14种语言 | ⭐⭐⭐ |
| ZipVoice-TTS | 内置 | 中英 | ⭐⭐ |
| ChatterBox | 内置 | 10+种语言 | ⭐⭐ |
| Higgs-audio-v3 | 内置 | 多语言 | ⭐⭐ |
| GPT-SoVITS | 本地API | 中英日韩 | ⭐⭐⭐ |
| Index-TTS | 本地API | 中英 | ⭐⭐⭐ |
| VoxCPM-TTS | 本地API | 10+种语言 | ⭐⭐⭐ |
| CosyVoice | 本地API | 中英日韩等10+种 | ⭐⭐ |
| Spark-TTS | 本地API | 英语 | ⭐⭐ |
### 最佳克隆配置
为获得最佳克隆效果，请在主界面和高级选项中进行如下配置：
1. **强制控制字幕时长**：通常TTS配音引擎要求参考音频在 3-10s 时间内，否则极可能出错
- 进入 `菜单 -> 工具 -> 高级选项 -> 语音识别参数`
- 最长语音持续秒数：6-10
- 最短语音持续毫秒：3000-4000
3. **翻译渠道**：使用 DeepSeek 或 OpenAI 等大模型，勾选「发送完整字幕」
4. **人声背景分离**：点击主界面「设置更多参数」，勾选「分离人声背景声」，大幅提升克隆音质
### 使用本地参考音频
有时您可能不希望克隆原始视频中的音色，而是使用某个本地音频里的音色。
**步骤**：
1. 准备一段 3-10 秒的 单声道 WAV 格式音频，确保：
- 清晰准确的单一人声
- 没有背景噪声
- 开头结尾没有多余静音
2. 将音频复制到软件目录下的 `f5-tts` 文件夹
3. 打开 `菜单 -> TTS 设置 -> 设置参考音频`，填写：
**文件名.wav#音频中的说话文本**，例如 `myaudio1.wav#你说四大皆空，却为何紧闭双眼`
4. 保存后，在主界面配音角色下拉框中选择 `myaudio1.wav`
> **注意**：GPT-SoVITS 的参考音频需要放在 GPT-SoVITS 软件的根目录下，而不是 `f5-tts` 文件夹内。
---
## 6. 使用已有的外部 SRT 字幕与音视频素材
# 使用已有的 SRT 字幕 和 人声背景声
> 如果你本地有配套的或自行准备好的 SRT 字幕，质量更高，不想使用软件自动生成的字幕；
>
> 或者有已经分离好了的人声和背景声，想让软件直接使用他们。
---
## 〇、了解视频翻译输出位置的默认规则
- 未勾选`文件夹`时默认输出位置: 所选视频同级的 `_video_out` 文件夹内，例如所选视频是`D:/videos/001.mp4`,则输出到`D:/videos/_video_out`内，每个视频生成一个结果文件夹，名字是`{视频名字(不含后缀)}-{视频后缀名}`，例如`D:/videos/_video_out/001-mp4`
- 若勾选`文件夹`时默认输出位置：所选文件夹同级的`_video_out/{该文件夹名}` 下，例如所选文件夹是 `D:/videos/ceshi`, 输出到`D:/videos/_video_out/ceshi` 文件夹内，每个视频生成一个结果文件夹，名字是`{视频名字(不含后缀)}-{视频后缀名}`,例如`D:/videos/_video_out/ceshi/001-mp4`
> **当点击了`输出到...`自定义输出位置后，将不再保存到默认位置，而是你指定的位置**
> **为简单起见，建议不要点击`输出到...`手动指定，而是使用默认位置，以下教程均假定你使用的是默认位置**
> 如果已选了输出到，想恢复为软件默认输出，则点击`输出到...`按钮，在弹出的文件选择框里单击`取消`或关闭按钮，则恢复默认
## 一、导入本地已有 SRT 字幕
### 前置准备
1. **规范文件名**：由于底层工具对中文、空格、特殊符号兼容性较差，建议将视频文件名改为简单的英文字母、数字、下划线组合（如 `myvideo.mp4`）
2. **开启系统扩展名显示**：
- Win10：打开文件夹 → 点击「查看」→ 勾选「文件扩展名」
- Win11：打开文件夹 → 点击「查看」→「显示」→ 勾选「文件扩展名」
### 1. 手动处理具体步骤
**如果只有很少几个视频，例如个位数个，可手动按照如下方法处理**
假设视频文件名为 `myvideo.mp4`，目标是从英文翻译至中文。
**步骤 1**：在视频文件所在的同级目录下，创建一个名为 `_video_out` 的文件夹。
**步骤 2**：进入 `_video_out` 文件夹，创建一个**视频同名且带格式后缀**的子文件夹：
```
_video_out/myvideo-mp4/
```
> ⚠️ v3.87 及以后版本必须带有后缀，格式为 `[文件名]-[视频格式]`，例如 `myvideo-mp4` 或 `video1-avi`。
**步骤 3**：将准备好的两种语言字幕文件复制到子文件夹内，并重命名为标准的语言代码：
```
_video_out/myvideo-mp4/en.srt ← 源语言字幕（英文）
_video_out/myvideo-mp4/zh-cn.srt ← 目标语言字幕（中文）
```
**步骤 4**：回到软件主界面，导入该视频并执行翻译。软件检测到 `_video_out` 内的对应字幕后，将跳过 ASR 和翻译阶段，直接进入配音与合成阶段。**一定不要勾选`清理已生成`，否则会清空已有的字幕**
### 2.自动处理：适合大批量，例如几十几百个视频(必须确保软件版本大于等 v4.05-0711)
> **必须确保视频名字和字幕名字完全相同(仅仅后缀不同)，并且位于同一文件夹内**
>
> 例如
> - D:/myvideos/123.mp4
> - D:/myvideos/123.srt
> - D:/myvideos/abc.mp4
> - D:/myvideos/abc.srt
点击`软件--菜单--工具/选项--批量创建文件夹结构`
1. 选择要处理的视频，按住 `ctrl` 键可多选，按住`ctrl+A`可全选
2. 选择 `字幕文本语言`：必须选择字幕文本真实所属语言，不可乱选，如果字幕是中文，就必选选择中文。
- 如果所选语言和视频发音语言【相同】：视频翻译时将把这个字幕视为发音语言字幕，跳过语音识别；
- 如果所选语言和视频发音语言【不同】：视频翻译时将把这个字幕视为翻译后的字幕，不再翻译该字幕，但仍会进行语音识别，创建发音语言字幕，若不需要，请将主界面发音语言设为和目标语言一样。
3. 任务完成后，即可去主界面选择这些视频，将自动使用这些字幕，但一定不要再点击【输出到...】按钮，否则无法找到这些字幕。也不要选中【清理已生成】，否则会删除里面的字幕文件
----
## 二、导入外部人声和背景声
由于软件内置的人声分离采用纯 CPU 计算，速度极慢。建议使用专业第三方工具（如 [UVR5-GUI](https://github.com/Anjok07/ultimatevocalremovergui/releases)）在 GPU 加速下进行分离：
**步骤 1**：使用第三方工具将音频分离为：
- 人声文件（Vocal）：无背景音的人声
- 伴奏文件（Instrumental）：无干声的伴奏
输出格式必须为 `wav`。
**步骤 2**：将文件重命名：
```
vocal.wav ← 人声
instrument.wav ← 伴奏
```
**步骤 3**：将这两个文件复制到 `_video_out/myvideo-mp4/` 文件夹内。
**步骤 4**：一定`不要勾选 清理已生成`，否则会清空已有的人声和背景声，并且必须勾选`分离人声背景声`和`重新嵌入背景` 。
---
## 7. 视频翻译的音画同步对齐引擎
由于不同语言在表达相同意思时句子的音节数和语法结构不同，配音后的时长必定会发生变化（如中文的"你好"，英文配音为"Hello there"或"How do you do"，耗时不同），这会导致字幕、声音、画面不同步。
### 7.1 软件内嵌的 5 大对齐调整策略
为了缓解这一问题，pyVideoTrans 底层 `SpeedRate` 对齐引擎支持以下策略：
1. **音频加速**：当配音时长超出原字幕对应时长时，自动将该句配音音频倍速播放。
2. **精简译文**：通过大模型或人工精简目标语言的字数，从源头上缩短配音时长。
3. **调整字幕间静音**：若原视频字幕段落之间存在静音间隙，通过压缩或移除这些间隙来"借用时间"，避免字幕重叠。
4. **移除配音前后静音**：剔除 TTS 引擎在句首和句尾自动生成的无声缓冲时间，从而缩短音频。
5. **视频降速播放（视频慢速）**：如果音频加速仍不足以对齐，则强行将该画面片段进行慢动作播放，延长视频时长以匹配声音。
### 7.2 对齐引擎（SpeedRate）核心逻辑
`videotrans/task/_rate.py` 内置了 `SpeedRate`（视频场景）和 `TtsSpeedRate`（纯字幕配音场景）两个引擎。`SpeedRate` 优先级处理策略如下：
* **启用音频加速 + 视频慢速**：两者协同工作，忽略单项最大倍率限制，声音与画面各承担一半的时间差异。
* **仅启用音频加速**：加速配音直至匹配原字幕时长，但最高速度不能超过设置的 `max_audio_speed_rate`。
* **仅启用视频慢速**：放慢视频画面直至匹配配音时长，但放慢倍数最高不超过设置的 `max_video_pts_rate`。
* **两者均不启用**：按原有字幕时间轴强行拼接音频片段，差异时间以静音填充，可能会造成声音阶段性重叠或断层。
### 7.3 音频加速实现细节
* **首选方案**：使用 Rubber Band 算法（`pyrubberband`），效果最平滑。
* **回退方案**：使用 FFmpeg `atempo` 滤镜链（`atempo` 单次范围 [0.5, 2.0]，超出时自动链式组合如 `atempo=2.0,atempo=2.0,atempo=X`）。
* **Rubber Band 安装提示**：
* Windows：下载 `rubberband-4.0.0-gpl-executable-windows.zip` 并将可执行文件放入 `ffmpeg/` 目录
* macOS：`brew install rubberband` 并 `uv add pyrubberband`
* Linux：`sudo apt install rubberband-cli libsndfile1-dev` 并 `uv add pyrubberband`
### 7.4 对齐引擎的局限性
* **PTS 精度限制**：FFmpeg 的 `setpts` 滤镜无法实现毫秒级精确的视频减速，输出视频可能与预期有微小偏差,随着视频时长的延长偏差会累积。
* **CRF/Preset 覆盖**：对齐步骤的 CRF 和编码预设可通过 `/crf.txt` 和 `/preset.txt` 文件覆盖全局设置（默认 CRF=20, preset=veryfast）。
* **最小片段时长**：低于 40ms 的音频片段会被丢弃（`MIN_CLIP_DURATION_MS = 40`）。
* **无效文件检测**：小于 1024 字节的文件被视为无效（可能只包含元数据）。
---
## 8. 最佳配置推荐
## 第一步：语音识别
**目标**：将视频中的语音转换为对应语言的字幕文件。
> 💡 **提示**：如果原始音视频有背景音或噪声，建议在主界面点击 `设置更多参数` 并选中 `分离人声背景声`，处理后排除背景声干扰，识别效果会更准确(若已选中分离背景声则无需再选中降噪)。
### 非中文视频
| 配置级别 | 渠道 | 模型 | 说明 |
|---------|------|------|------|
| 免费推荐 | faster-whisper(内置) | large-v3 | 速度与质量兼顾 |
| 免费备选 | openai-whisper(内置) | large-v3 | 准确度略高 |
| 免费备选 | whipser.cpp(Win内置) | large-v3 | 速度较快，win内置 |
| 收费推荐 | OpenAI 语音识别 API | — | 效果优秀 |
| 免费备选 | Nemotron-3.5-asr-0.6b(内置) | Nemotron-3.5-asr-streaming-0.6b | 主要欧洲系语言和日韩越 |
### 中文视频
| 配置级别 | 渠道 | 模型 | 说明 |
|---------|------|------|------|
| 免费推荐 | Qwen-ASR(内置) | — | 中文效果佳，也支持英文等其他几种语言|
| 免费备选 | 阿里FunASR(内置) | paraformer-zh | 中文效果佳 |
| 免费备选 | Firered中文(内置) | 小红书中文及方言 | 中文效果佳，也支持英文 |
| 免费备选 | Huggingface_ASR(内置) | zai-org/GLM-ASR-Nano-2512 | 智谱AI模型中文效果佳，也支持英文 |
| 免费备选 | Moss-Diarize(内置) | 90分钟内支持输出说话人 | 中英等多种语言 |
| 收费推荐 | 豆包语音识别大模型极速版 | — | 中文效果佳，也支持英文 |
| 收费推荐 | 小米mimo-v2.5-asr | — | 中文效果佳，也支持英文 |
| 收费备选 | 阿里百炼ASR | — | 中文优化，也支持英文 |
### 日语视频
| 配置级别 | 渠道 | 模型 | 说明 |
|---------|------|------|------|
| 免费推荐 | openai-whisper(内置) | large-v3 | 通用效果好 |
| 免费推荐 | Nemotron-3.5-asr-0.6b(内置) | 英伟达开源多语言模型 Nemotron-3.5-asr-streaming-0.6b | 主要欧洲系语言加日韩越 |
| 免费备选 | Huggingface_ASR | japanese-wav2vec2-large/Nemotron-3.5-asr-streaming-0.6b | 日语专用 |
| 收费推荐 | OpenAI 语音识别 API | — | 效果优秀 |
### 小语种视频
> 在 HuggingFace_ASR 里内置了几个针对小语种微调的模型，可视情况选择使用
| 配置级别 | 渠道 | 说明 |
|---------|------|------|
| 免费推荐 | openai-whisper(内置) large-v3 | 通用模型，支持数十种语言 |
| 免费推荐 | Dophin(内置) | 专门用于亚洲语言(批量语音转录界面可选择`自动检测`) |
| 免费推荐 | Omnilingual ASR(内置) | 1600多种语言(批量语音转录界面可选择`自动检测`) |
| 收费推荐 | Gemini 大模型识别 / OpenAI API | 小语种效果好 |
> **注意**：使用本地模型时，如果没有 N 卡或未启用 CUDA 加速，处理速度会很慢。显存不够大时可能崩溃。
> [点击查看语音识别各个渠道使用方法](/yuyinshibiequdao)
---
## 第二步：字幕翻译
**目标**：将第一步生成的字幕翻译为目标语言。
| 配置级别 | 渠道 | 说明 |
|---------|------|------|
| **首选** | DeepSeek / OpenAI ChatGPT / Gemini（最新模型） | AI 翻译质量最佳 |
| 免费 | Google 翻译 / Microsoft 翻译(可能已无法使用，微软已关闭接口) | 传统翻译，速度快 |
| 本地 | M2M100 | 完全离线翻译,模型位置[软件目录/models/m2m100_12b] |
| 本地 | Hy-MT2-1.8B | 腾讯开源翻译模型 |
**提升字幕翻译质量的关键设置**：
- 勾选「发送完整字幕
- 使用 AI 渠道时，将「AI翻译渠道每批字幕行数」设为 100 或更大，配合支持超长上下文的模型
- 在 高级选项-字幕翻译--AI翻译附带所有字幕做参考--选中，可在翻译字幕时附带所有原文作为上下文参考，能取得更佳质量（v4.12-0908版本起）
---
## 第三步：配音
**目标**：根据翻译后的字幕生成配音音频。
| 配置级别 | 渠道 | 说明 |
|---------|------|------|
| 免费推荐 | Edge-TTS/gTTS | 微软免费接口、google免费接口，效果自然，支持所有语种 |
| 本地推荐 | Qwen-TTS、F5-TTS、OmniVoice、Confucius、higgs-audio-v3| 内置，支持克隆 |
| 收费推荐 | 豆包语音合成2.0 / Qwen-TTS(bailian) / 小米 / Minimaxi / OpenAI-TTS | 高质量商业 API |
| 克隆语音 | OmniVoice / Confucius / Higgs-audio-v3 / Qwen-TTS / GPT-SOVITS / CosyVoice / F5-TTS / Index-TTS / ChatterBox / ZipVoice| 使用原视频音色 |
> [查看配音渠道详细信息和使用方法](/peiyinqudao)
---
## 第四步：字幕、配音、画面同步对齐
**目标**：将字幕、配音和画面进行同步处理。
| 配置 | 说明 |
|------|------|
| 选中「二次识别」 | 在配音完成后对配音文件再次语音识别，生成简短、时间轴精准的字幕 |
| 设置「配音语速」 | 中文翻译成英文时，设置 `+10` 或 `+15` 加快配音速度 |
| 选中「配音加速」 | 当配音比原视频长时，自动加速配音 |
| 同时选中「视频慢速」 | 配合音频加速，效果最佳 |
| 选中「分离人声背景声」 | 嵌入原始背景音 |
| 选中「降噪」 | 提升原音质量，提高识别精度 |
---
## 第五步：其他质量提升
### 基础设置
1. 选中「发送完整字幕」
2. 选中「菜单-工具-高级选项-AI翻译附带完整原字幕」
3. 将「AI翻译渠道每批次字幕行数」设为 100 或更大
4. 必须使用支持超长上下文的在线 AI 大模型
---
## 9. 菜单高级选项（Advanced Options）核心参数详解
通过主界面顶部 `菜单 -> 工具/选项 -> 高级选项` 进入，此处的配置会全局影响软件的行为与资源消耗。
#### 【通用设置/(Common)】
- **`软件界面语言/(Software interface language)`**: 设置软件界面语言，修改后需要重启软件
- **`单视频交互翻译暂停倒计时/(Countdown for single video translation pause)`**: 当单视频交互翻译时，暂停倒计时秒数(设为0将跳过编辑窗口)
- **`独立功能(如语音转录/文字配音/翻译字幕)输出目录/(Set output directory)`**: 用于设置 批量语音转录 / 批量为字幕配音 / 批量翻译srt字幕 等功能的输
出结果位置，非视频翻译结果保存位置，默认软件安装目录下output文件夹
- **`失败后重试次数/(Number of retries after failure)`**: 失败后重试次数(针对重试可能恢复的错误，在此设定重试次数)
- **`LLM纠错每批字幕行数/(LLM Correction errors How many subtitles are sent each time)`**: LLM大模型纠错时，每次发送多少条字幕，该值越大断句效果越
好，一次性发送全部字幕最佳，但受限于最大输出token和上下文(max_token)，过长输入可能导致超出AI限制而失败，默认20条字幕
- **`LLM纠错所用AI渠道/(AI provider for LLM Correction errors)`**: LLM纠错时使用的AI渠道
- **`禁用桌面通知/(Disable desktop notifications)`**: 任务完成或失败后不显示桌面通知
- **`分离背景声模型/(BGM separation model)`**: 选择分离背景声时所用模型
- **`人声背景分离线程数/(Threads nums for separation)`**: 人声背景声分离/降噪线程数，越大越快但占用资源越多
- **`批量翻译视频时每批数量/(Translating batches, quantity per batch)`**: 批量翻译视频时，在此设置每批次同时翻译几个，默认0即不限制
- **`主界面显示所有参数?/(Show all parameters?)`**: 为避免过多参数造成困扰，主界面默认隐藏大部分参数，如果选中这里将切换为默认显示所有参数
- **`CPU同时任务数[重启生效]/(Number of CPU tasks[restart])`**: 最大CPU同时任务数，越大越快但可能爆内存，最大不应超过cpu核数
(修改保存后重启生效)
- **`GPU同时任务数[重启生效]/(Number of GPU tasks[restart])`**: GPU任务同时执行数量，除非显存超大，否则请设为1
(修改保存后重启生效)
- **`强制指定重型任务运行设备/(Force the operation of heavy-duty equipment)`**: 强制指定重型任务运行设备，不要乱动，除非你知道自己在做什么
#### 【视频输出控制/(Video Output)】
- **`视频输出质量控制/(Video output quality control (CRF))`**: 视频转码时损失控制，0=无损但视频会超级大，51=质量差文件小
- **`输出视频压缩率/(Output video compression preset)`**: 主要调节编码速度和质量的平衡，有 ultrafast、superfast、veryfast、faster、fast、medium、s
low、slower、veryslow 选项，编码速度从快到慢、压缩率从低到高、视频尺寸从大到小。
- **`264/265编码/(H.264/H.265 encoding)`**: 采用 libx264 编码或 libx265 编码，264兼容性更好，265压缩比更大清晰度更高
- **`输出视频格式(mp4/mkv)/(Output video format (mp4/mkv))`**: 输出视频格式(mp4/mkv)
- **`可变帧率vfr/固定帧率cfr/(Variable frame rate (vfr)/fixed frame rate (cfr))`**: 有视频慢速处理时，可变帧率vrf效果更好，固定帧率cfr兼容性更佳
- **`强制软编码视频?/(Force software video encoding?)`**: 强制ffmpeg使用软编解码?（速度慢但兼容性好不易出错，默认优选硬件编码）
- **`视频合成cuda硬解码/(ffmpeg decode video use cuda)`**: 最后一步视频合成时，强制使用cuda解码视频，更快但易出错
- **`自定义ffmpeg命令参数/(Custom FFmpeg command arguments)`**: 自定义ffmpeg命令参数， 将添加在输出文件之前的位置,例如 -bf 7 -b_ref_mode middle
#### 【语音识别参数/(ASR Settings)】
- **`选择VAD/(Select VAD)`**: 选择要使用的VAD
- **`语音阈值/(VAD: Speech probability threshold)`**: 表示音频片段被认为是语音的最低概率。VAD 会为每个音频片段计算语音概率，超过此阈值的部分被视为
语音，反之视为静音或噪音。越小越灵敏但可能误将噪声视为语音
- **`非语音阈值/(no speech threshold)`**: 减小可降低幻觉但可能遗漏文字
- **`最长语音持续(秒)/(VAD:max speech duration(s))`**: 最长语音持续时长(秒),限制单个语音片段的最大长度。超过此时长时强制分割。填写数字，单位是秒
- **`最短语音持续(毫秒)/(VAD:min speech duration(ms))`**: 最短语音持续时长(毫秒)，如果某条字幕时长小于该ms，则尝试将该字幕合并进相邻字幕中，单位是
毫秒
- **`静音分割持续毫秒/(VAD:Min silence duration for split(ms))`**: 在语音结束时，需等待的静音时间达到此值后，才会分割出语音片段。填写数字，单位ms
也就是只在大于此值的静音片段处分割
- **`二次识别最长语音持续(秒)/(Recognition(2): max duration(s))`**: 二次识别最长语音持续时长(秒),限制单个语音片段的最大长度。超过此时长时强制分割
。填写数字，单位是秒
- **`二次识别最短语音持续(毫秒)/(Recognition(2): min duration(ms))`**: 二次识别最短语音持续时长(毫秒)，如果某条字幕时长小于该ms，则尝试将该字幕合
并进相邻字幕中，单位是毫秒
- **`二次识别所用模型/(The model used for secondary recognition)`**: 二次识别所用模型(固定使用faster-whisper渠道)
- **`说话人分离模型/(Model for speaker separation)`**: 用于说话人分离的模型，默认内置模型支持中英.
若选 pyannote 必须拥有 https://huggingface.co 上的token，
并且同意pyannote组织的授权协议
具体请访问URL查看教程:
https://pvt9.com/shuohuaren
- **`Huggingface的token/(Your token from huggingface.co)`**: 填写你在 huggingface.co 的token，否则无法使用 pyannote，具体查看教程
https://pvt9.com/shuohuaren
- **`计算数据类型/(Compute data type)`**: faster模式时计算数据类型，int8=消耗资源少，速度快，精度低，float32=消耗资源多，速度慢，精度高，float16适
合GPU加速。default默认自选
- **`识别准确度beam_size/(Recognition accuracy (beam_size))`**: 字幕识别时精度调整，1-5，1=消耗显存最低，5=消耗显存最多
- **`识别准确度best_of/(Recognition accuracy (best_of))`**: 字幕识别时精度调整，1-5，1=消耗显存最低，5=消耗显存最多
- **`启用上下文感知/(Enable context awareness)`**: 若开启将占用更多GPU，效果也更好，但也容易出现重复或幻觉
- **`重复惩罚/(repetition penalty)`**: 增大该值有利于减少重复
- **`文本压缩率/(compression ratio threshold)`**: 减小该值有利于减少重复
- **`采样温度/(temperature)`**: 采样温度
- **`热词/(hotwords)`**: 告诉模型哪些词可能出现，以英文逗号分隔多个
- **`faster-whisper模型/(faster-whisper models)`**: faster-whipser的模型列表，英文逗号分隔
- **`whisper.cpp模型/(whisper.cpp models)`**: whisper.cpp的模型名字列表，英文逗号分隔
- **`Gemini语音识别每批切片数/(Gemini speech recognition batch slice count)`**: 使用gemini识别语音时，每次发送音频切片数，越大效果越好，但失败率会
升高
- **`字幕繁体转简体/(Convert Traditional to Simplified Chinese subtitles)`**: 强制将识别出的繁体字幕转为简体
- **`删除字幕末尾标点?/(Remove punctuation at end subtitles?)`**: 删除字幕末尾标点?
- **`云API识别暂停秒/(Cloud API pauses after each recognition/Seconds)`**: 云API每次识别后暂停秒数，防止超过频率限制
#### 【字幕翻译调整/(Translation)】
- **`传统翻译渠道每批字幕行数/(Batch size (lines) for traditional translation)`**: 传统翻译渠道每次发送字幕行数
- **`AI翻译渠道每批字幕行数/(Batch size (lines) for AI translation)`**: AI翻译渠道每次发送字幕行数
- **`AI翻译附带所有字幕做参考/(AI translation includes all original subtitles for reference?)`**: 选中时，AI翻译渠道会附带全部原始字幕到提升词中，做背景参考，翻译质量最佳，但会大幅增加 token 消耗
【务必注意】
1. 必须使用支持超长上下文的先进模型(在线AI旗舰模型)
2. 可能反馈较慢，表现为迟迟未返回数据
- **`翻译后暂停秒/(Pause (s) after each translation request)`**: 每次翻译后暂停秒数,用于限制请求频率
- **`发送完整字幕/(Send full SRT format for AI translation)`**: 是否在使用AI翻译渠道时发送SRT格式字幕内容
- **`AI翻译模型温度值/(AI temperature for translation subtitles)`**: AI翻译模型温度值，默认0.1
#### 【字幕配音调整/(Dubbing)】
- **`并发配音线程数/(Concurrent dubbing threads)`**: 同时配音的线程数
- **`配音后暂停秒/(Pause (s) after each dubbing request)`**: 每次配音后暂停秒数,用于限制请求频率
- **`移除配音前后静音缓冲/(Remove the mute buffer each subtitle audio)`**: 移除每条字幕配音前后静音缓冲，利于音画同步，但可能结尾仓促
- **`保留每条字幕的配音文件/(Save dubbed audio for each subtitle line)`**: 保留每行字幕的配音结果
- **`文本规范化/(Text Text normalization)`**: 配音前对文本规范化处理
- **`ChatTTS音色值/(ChatTTS voice timbre value)`**: ChatTTS 音色值
- **`EdgeTTS配音渠道配音并发数/(The higher concurrent of EdgeTTS)`**: EdgeTTS渠道配音并发数，越大越快，但可能限流失败
- **`EdgeTTS配音渠道失败重试次数/(Retries after EdgeTTS failure)`**: EdgeTTS渠道失败后重试次数,有些失败无论多少次重试也无法恢复，太大只会延长耗时
#### 【字幕声音画面对齐/(Alignment)】
- **`音频加速最大倍数/(Maximum audio speed-up rate)`**: 最大音频加速倍数，默认100
- **`视频慢放最大倍数/(Maximum video slow-down rate)`**: 视频慢放最大倍数，默认10，不可大于10
- **`中日韩字幕单行字符数/(Number of characters per line for CJK)`**: 中日韩字幕单行字符数，多于将换行，仅针对视频翻译中的目标字幕或单独的语音转录
功能字幕
- **`其他语言字幕单行字符数/(Number of words per line for Other)`**: 其他语言字幕单行字符数，多于将换行，仅针对视频翻译中的目标字幕或单独的语音转
录功能字幕
#### 【Whisper模型提示词/(Whisper Prompt)】
...
---
## 10. 技术架构与核心数据类定义
### 10.1 九个处理阶段说明
整个生命周期内，同一阶段内部的所有子任务串行处理，阶段之间支持高度的并行流转：
| 阶段 | 对应核心方法 | 阶段职责描述 |
|:---|:---|:---|
| **① 预处理** | `prepare()` | 分离视频中的无声视频流和原始音频流；进行人声伴奏分离及音频降噪；初始化缓存与输出目录。 |
| **② 语音识别** | `recogn()` | 调用 ASR 引擎将音频转录为带精确时间轴的 `SrtItem` 列表。可选恢复标点、LLM 重新断句。 |
| **③ 说话人分离（批量翻译视频时跳过）**| `diariz()` | 调用分离模型（内置、阿里CAM++、pyannote），将识别出的字幕按说话人角色重新归类。 |
| **④ 字幕翻译** | `trans()` | 将源字幕通过指定渠道翻译为目标语言。支持输出单行、双语、及各种双语样式。 |
| **⑤ 语音合成** | `dubbing()` | 逐条生成配音音频切片。若启用 `clone`，将在此阶段动态裁剪原声作为参考音频进行克隆。 |
| **⑥ 音画对齐** | `align()` | 依靠 `SpeedRate` 引擎执行：配音加速、视频慢放、去除字幕静音、强行对齐等音画重构操作。 |
| **⑦ 二次识别** | `recogn2pass()` | 对合成的新配音再次进行 ASR（有配音且非双语硬字幕嵌入模式），生成字数精简、时间更贴合的字幕。 |
| **⑧ 最终合成** | `assembling()`| 利用 FFmpeg 命令行，将无声视频、配音、背景伴奏以及目标字幕压制/合并为最终 MP4/MKV。 |
| **⑨ 任务收尾** | `task_done()` | 将成品文件从缓存移动至指定输出目录，彻底清理临时切片与进程缓存，发送完成通知。 |
### 11.2 独立子进程池与 GlobalProcessManager
为防止本地 AI 推理模型（如 `faster-whisper`）在遇到极端视频帧或因 C++ 底层显存溢出发生硬崩溃（SegFault）直接连带导致整个 pyVideoTrans 客户端闪退，软件设计了独立子进程隔离池管理机制：
* **防内存泄漏自我重启**：每个子进程的 `maxtasksperchild` 属性**强制设置为 1**，即每个子进程在被派发执行完单次 AI 运算（如一段视频的 Whisper 识别）后，进程会被主控池安全回收并重新拉起新实例，从根本上杜绝了开源 AI 推理模型长期运行导致的内存与显卡显存泄漏。
---
#### 发音语言谨慎选择【自动检测】
> 明确指定发音语言，会让识别更准确
自 v4.12 起，在视频翻译界面 `发音语言` 下拉最底部增加了`自动检测`，用于无法预先知道的音视频翻译。
若选择了`自动检测`，必须注意：
- 确保`语音识别`仅使用`faster-whisper(内置)` 、`openai-whisper(内置)`、`Qwen-ASR(内置)`，否则可能出现无法预知错误，因为多数渠道需要明确指定语言
- 翻译渠道如`Google(免费)/微软(免费)`，如果待翻译文本中有多种语言文本混合，例如简繁混合，必须明确指定语言而非使用`自动检测`，否则不会翻译，而是直接返回原文
- 请勿嵌入双字幕，可能出现未知错误
---
## 本地离线识别
无需联网，首次使用时下载模型。
| 渠道 | 说明 | GPU 加速 | 推荐度 |
|------|------|---------|--------|
| [faster-whisper(内置)](/faster) | 速度快、质量高，支持所有内置语言 | ✅ | ⭐⭐⭐ **默认推荐** |
| [openai-whisper(内置)](/openaiwhisper) | 准确度高，速度略慢，支持所有内置语言 | ✅ | ⭐⭐⭐ |
| [Qwen-ASR(内置)](/qwenasrlocal) | 中文效果佳，支持多数内置语言 | 优先使用 | ⭐⭐⭐ |
| Nemotron-3.5-asr-0.6(内置) | [欧洲系语言及日韩越等40种](https://huggingface.co/nvidia/nemotron-3.5-asr-streaming-0.6b#supported-languages) | 优先使用 | ⭐⭐ |
| `Whisper.cpp(Win内置)` | 在Windows上已内置 whisper.cpp，可直接使用，MacOS和Linux上需自行单独部署| ✅ | ⭐⭐⭐|
| [FunASR(内置)](/funasr) | 中文效果佳，有多个模型可选 | ✅ | ⭐⭐⭐ |
| Firered中文(内置) | 仅支持中文及20中文方言 | X | ⭐⭐ |
| VibeVoice-ASR(内置) | 微软出品，多语言支持，极消耗显存(低于15G不建议) | ✅ | ⭐⭐⭐ |
| Dolphin(内置) | 支持40多亚洲语言及20中文方言 | X | ⭐⭐ |
| Omnilingual ASR(内置) | 支持所有内置语言等1600多种 | X | ⭐⭐ |
| parakeet日语(内置)**v4.12起已废弃，改用Nemotron-3.5-asr-0.6(内置)** | 仅支持日语 | X | ⭐⭐ |
| [Huggingface_ASR(内置)](/huggingface) | 可选多个语言模型 | 优先使用 | ⭐⭐ |
| Moss-Diarize(内置) | 50+语言，90分钟内可同时分离说话人，超出90分钟需配合说话人模型单独分离 | ✅ | ⭐⭐ |
| [Faster-Whisper-XXL.exe](/xxl) | faster-whisper的Windows封装版本,**需自定额外下载**并指定exe | ✅ | ⭐⭐ |
> 因国内网络环境问题，加之模型都比较巨大，自动下载有可能失败，如果失败，[请点击查看模型下载地址和手动下载方式](/aboutmodels)
> **优先使用**是指：无论是否选择了`启动CUDA加速`，都优先尝试使用GPU加速
### faster-whisper/openai-whisper渠道模型选择建议
| 模型 | 速度 | 准确度 | 显存需求 |
|------|------|--------|---------|
| tiny | 最快 | 低 | ~1GB |
| base | 快 | 中低 | ~1GB |
| small | 中 | 中 | ~2GB |
| medium | 慢 | 较高 | ~5GB |
| large-v3 | 最慢 | 最高 | ~8GB |
| large-v3-turbo | 较快 | 高 | ~6GB |
**推荐**：`large-v3-turbo`，速度与质量兼顾。
---
## 在线识别
| 渠道 | 说明 |
|------|------|
| [阿里百炼 Qwen3-ASR](/qwen-mt) | 需开通阿里百炼平台服务 |
| 小米 | mimo-v2.5-asr模型中文/中英混合效果佳 [需开通小米AI平台充值并获取API key](https://platform.xiaomimimo.com/console/api-keys) 填写到`菜单-翻译设置-小米AI`|
| [字节语音识别大模型极速版](/zijierecognmodel) | 中文效果极佳 |
| [Elevenlabs.io 语音识别](/elevenlabsrecogn) | 免费账号频率限制严格，几乎不可用 |
| [Deepgram.com](/deepgram) | 需注册 API Key |
| Gemini AI | 识别小语种能力强，需科学上网，固定使用 `gemini-3.5-transcribe`模型 |
| [302.AI](/302ai) | 访问 302.ai 申请 |
| [OpenAI 语音识别API](/openairecogn) | 效果优秀，需 SK 密钥 |
---
## 高级自定义
| 渠道 | 说明 |
|------|------|
| [Parakeet-tdt(本地API)](/parakeet) | 需自行单独部署|
| [WhisperX(本地API)](/whisperx) | 需自行单独部署 |
| [STT(本地API)](/stt) | 需自行单独部署 |
| [Whisper.NET](/whisper_net_setup) | 支持AMD显卡加速，需源码安装并按照文档说明下载相关dll |
| [自定义语音识别 API](/openairecogn) | 可编写自己的识别接口 |
---
## Huggingface_ASR(内置) 渠道可用模型
> 该渠道无论是否选中了`启用CUDA加速`，只要CUDA可用，就优先尝试使用
| 模型 | 支持语言 |
|------|---------|
| nvidia/parakeet-tdt-0.6b-v3 | en,bg,hr,cs,da,nl,et,fi,fr,de,el,hu,it,lv,lt,mt,pl,pt,ro,sk,sl,es,sv,ru,uk |
| nvidia/nemotron-3.5-asr-streaming-0.6b | en,es,fr,it,pt,nl,de,tr,ru,ar,hi,ja,ko,vi,uk,pl,sv,cs,nb,da,bg,fi,hr,sk,zh,hu,ro,et,el,lt,lv,mt,sl,he,th,nn |
| reazon-research/japanese-wav2vec2-large-rs35kh | 日语 |
| kotoba-tech/kotoba-whisper-v2.0 | 日语 |
| biodatlab/whisper-th-large-v3 | 泰语 |
| vinai/Phowhisper-large | 越南语 |
| anke01/whisper-small-uyghur | 维吾尔语 |
| openai/whisper-large-v3 | 所有语言 |
| zai-org/GLM-ASR-Nano-2512 | 智谱AI模型，中文粤语效果佳 |
|Audio8/ARK-ASR-0.6B/3B| 中文,英语,德语,日语,法语,韩语,西班牙,波兰,意大利,罗马尼亚,匈牙利,捷克,荷兰|
|ibm-granite/granite-speech-4.1-2b| 英语,法语,德语,西班牙语,葡萄牙语,日语|
|nguyenvulebinh/wav2vec2-base-vietnamese-250h|越南语|
|sakares/wav2vec2-large-xlsr-thai-demo|泰语|
|SiangLao/xlsr-53-lao-asr|老挝语|
|chuuhtetnaing/whisper-large-v3-myanmar|缅甸语|
|1morecupofhottea/whisper-turbo-khmer-v9|高棉语 柬埔寨|
|anke01/whisper-small-uyghur|维吾尔语|
|kingabzpro/whisper-large-v3-turbo-urdu|乌尔都语|
|vasista22/whisper-tamil-small|泰米尔|
|theainerd/Wav2Vec2-large-xlsr-hindi|印地语|
|cautroi/whisper-large-v3-id|印尼语|
|Khalsuu/filipino-wav2vec2-l-xls-r-300m-official|菲律宾|
|navai-uz/whisper-medium-uzbek|乌兹别克|
|jonatasgrosman/wav2vec2-large-xlsr-53-persian|波斯语|
|Ghost3454/translynx-pakistani-punjabi-whisper-small|旁遮普语|
|turkmedstt/whisper-large-v3-turkish-general|土耳其语|
|anton-l/wav2vec2-large-xlsr-53-mongolian|蒙古语|
|HNO333333/w2v-bert-2.0-Tibetan-Amdo|藏语|
---
#### STS 字幕翻译（24+ 个渠道，注册于 `videotrans/translator/__init__.py`）
翻译渠道的功能是把原始语言的字幕翻译成其他语言，比如把中文字幕变成英文字幕，或者反过来。它能调用各种翻译服务，将语音识别生成的字幕精准、快速地翻译成你想要的目标语言。
> 部分翻译服务需要你提供 API 地址、密钥（SK）等信息。你可以在软件顶部的菜单栏中找到「翻译设置」选项，轻松完成配置。
>
> [翻译结果可能出现空白字幕行或大堆文本，具体原因点击查看](/faq17)，解决方法：`菜单 → 工具 → 高级选项 → 字幕翻译 → 传统翻译渠道每批字幕行数/AI翻译每批字幕行 → 都设为 1`
---
## 免费翻译渠道
这类渠道通常免费，但可能存在网络限制或使用频率限制。
* **[Google 翻译](/googletranslate)**：翻译质量可靠。不过，在中国大陆地区使用需要"科学上网"。
* **[Microsoft 翻译](/microsoft)**：微软出品，无需特殊网络环境即可使用。但短时间内请求次数太多时可能会暂时不可用。
## 本地翻译模型
* **[M2M100 本地模型](/m2m100)**：本地模型翻译，第一次使用在线下载模型。下载地址 https://modelscope.cn/models/himyworld/videotrans/files
* **Hy-MT2-1.8B 本地模型**：腾讯的文字翻译模型，第一次使用在线下载模型。下载地址 https://huggingface.co/tencent/Hy-MT2-1.8B/tree/main
*只要CUDA可用，无论是否选中`启用CUDA加速`，都将优先尝试使用*
> 如果首次下载模型失败，可打开该地址，下载所有文件覆盖到`软件目录/models/models--tencent--Hy-MT2-1.8B`
>
> 默认使用 1.8B 小尺寸的模型，如果你想使用 7B/30B 更大的模型，请手动到该地址 https://huggingface.co/tencent/Hy-MT2-7B/tree/main 下载所有文件放到 `软件目录/models/models--tencent--Hy-MT2-1.8B` 文件夹内覆盖
---
## 需要申请 API Key 的专业翻译服务
这些是专业的机器翻译平台，通常需要注册账户、创建应用并获取密钥（API Key）才能使用。它们的服务更稳定，翻译质量也更有保障。
* **[百度翻译](/baidu)**：百度官方提供的翻译服务。你需要访问[百度翻译开放平台](https://fanyi-api.baidu.com/)，创建自己的应用，并获取 AppID 和密钥。请注意，该服务仅限中国大陆 IP 使用。
* **[腾讯翻译](/tencent)**：腾讯云旗下的机器翻译服务。你需要登录[腾讯云](https://cloud.tencent.com/product/tmt)，开通相关服务并创建访问密钥（SecretID 和 SecretKey）。同样，此服务也仅限中国大陆 IP 使用。
* **[阿里机器翻译](/alibaba-machine-translation)**：来自阿里云的专业翻译服务。你需要前往阿里云官网开通服务。
* **[DeepL 翻译](/deepl)**：以高质量和自然的翻译效果而闻名。你需要在其[官网](https://www.deepl.com)注册并使用国际信用卡开通服务。
---
## AI 大模型翻译渠道
利用前沿的人工智能模型进行翻译，翻译结果更智能、更贴近人类语言习惯。
* **[DeepSeek](/deepseek-ai)**：一家专注于大模型研发的公司。你需要前往其开放平台申请 API 密钥。
* **[字节火山大模型](/zijiehuoshan)**：由字节跳动火山引擎提供。你需要前往其官网开通服务并创建推理点。
* **[智谱 AI](/zhipu-ai)**：国内领先的 AI 公司。你需要访问[智谱 AI 开放平台](https://open.bigmodel.cn/)申请 API 密钥。
* **[阿里百炼 API](/qwen-mt)**：阿里云推出的大模型服务平台。你需要前往[阿里百炼平台](https://www.aliyun.com/product/bailian)申请 API 密钥。
* **[硅基流动 (SiliconFlow)](/siliconflow-ai)**：专注于 AI 技术服务的公司。你需要访问其官网申请 SK 密钥。
* **[302.AI 翻译](/302ai)**：访问 `302.ai` 网站申请 appkey 即可使用。
* **[OpenRouter.ai](/openrouter-ai)**：一个集成了多种 AI 模型的平台。你需要前往其官网申请 SK 密钥。
* **[OpenAI (ChatGPT)](/openai)**：大名鼎鼎的 ChatGPT，翻译效果出众。你可以使用 OpenAI 官方模型，也可以配置兼容的第三方或中转 API。
* **[Gemini 翻译](/gemini-recognition)**：Google 出品的强大 AI 模型。你需要前往 Google AI 平台申请 Gemini 的 API 密钥，国内使用需要科学上网。
* **[AzureGPT 翻译](/azure)**：微软 Azure 云平台提供的 AI 翻译服务，你需要开通 Azure 服务。
---
## 自行部署与定制
适合有一定技术能力的开发者，可以让你拥有更高的自由度和控制权。
* **[DeepLX 翻译](/deeplx)**：一个可以让你免费使用 DeepL 服务的项目，需要你自己在本地或服务器上进行部署。
* **[LibreTranslate 翻译](/libretranslate)**：一款开源的机器翻译软件，你需要自行部署才能使用。
* **[兼容 AI/本地模型翻译](/localllm)**：如果你在自己的电脑或服务器上部署了 AI 大模型（需兼容 OpenAI 的接口），可以在这里填写 API 地址直接调用。
* **[自定义翻译 API](/transapi)**：如果你具备编程能力，可以编写自己的翻译 API。只要按照指定的格式返回数据，就可以无缝集成到我们的软件中。
#### TTS 语音合成（34 个渠道，注册于 `videotrans/tts/__init__.py`）
配音（TTS）是视频翻译的第三步，将翻译后的字幕文本转换为语音音频。pyVideoTrans 支持 30+ 种配音渠道。
> 也可通过左侧面板`文字配音`单独使用配音功能，支持导入多个srt字幕文件或txt文件进行配音。
>
> 角色`clone`代表使用原始视频中的说话人音色进行配音，以实现语音克隆，该角色仅在主界面`视频翻译`功能中可用。
>
> 有`clone`角色渠道均支持自定义参考音频，即克隆你自己准备的一段3-10s的音频中的音色，使用该音色配音，具体方法见下方的`制作和使用参考音频`
---
## 开箱即用（免费）
无需复杂配置，非常适合新手。
| 渠道 | 说明 | 推荐度 |
|------|------|--------|
| [Edge-TTS(免费)](/edgetts) | 微软免费接口，声音自然，支持所有语种 | ⭐⭐⭐ **默认推荐** |
| gTTS(免费) | Google TTS，基础质量，国内需科学上网 | ⭐⭐ |
> ⚠️ Edge-TTS 短时间内大量使用可能触发限流，建议在高级选项中将并发数设为 1，暂停秒数设为 5-10。
---
## 内置（免费）
首次使用时自动下载模型。
> GPU 加速列中`优先使用`是指：只要CUDA可用，无论是否选中了`启用CUDA加速`，都优先尝试使用
>
| 渠道 | 说明 | GPU 加速 |支持克隆(`clone`角色)| 推荐度 |
|------|------|---------|--------|--------|
| [Qwen3-TTS(内置)](/qwen-tts) | 支持中文、英文、日文、韩文、德文、法文、俄文、葡萄牙文、西班牙文和意大利文 | 优先使用 |✅ | ⭐⭐⭐ 推荐 |
| [F5-TTS(内置)](/f5tts) | 中英日法德俄意、西班牙、印地、阿拉伯语 | ✅ | ✅ |⭐⭐⭐ |
| [OmniVoice-TTS](/ominivoice) | 支持600种语言(v4.05起内置) | 优先使用 | ✅ | ⭐⭐⭐ 推荐 |
| Confucius-TTS(内置)*v4.06起* | 中文、英文、日语、韩语、德语、法语、西班牙语、印尼语、意大利语、泰语、葡萄牙语、俄语、马来语、越南语 | ✅| ✅ | ⭐⭐⭐ |
| MOSS-TTS-Nano(内置) | 中文、英文、德文、西班牙文、法文、日文、意大利文、匈牙利文、韩文、俄文、波斯文、阿拉伯文、波兰文、葡萄牙文、捷克文、瑞典文、希腊文、土耳其文 | ❌ | ✅ |⭐⭐ |
| ZipVoice(内置) | 中英语言 | ✅ | ✅ |⭐⭐⭐ 推荐 |
| [Piper(内置)](/vitspiper) | 轻量级，支持20种语言 | ❌ | ❌ |⭐⭐ |
| ChatterBox(内置) | 阿拉伯语、德语、希腊语、英语、西班牙语、芬兰语、法语、希伯来语、印地语、意大利语、日语、韩语、马来语、荷兰语、挪威语、波兰语、葡萄牙语、俄语、瑞典语、斯瓦希里语、土耳其语、中文 | ✅ |✅ | ⭐⭐⭐ 推荐 |
| Supertonic3(内置) | 英语、韩语、日语、阿拉伯语、捷克语、德语、希腊语、西班牙语、法语、印地语、匈牙利语、印尼语、意大利语、荷兰语、波兰语、葡萄牙语、罗马尼亚语、俄语、瑞典语、土耳其语、乌克兰语、越南语 | ❌ | ❌ | ⭐⭐ |
| [VITS(内置)](/vitspiper) | 中英配音 | ❌ | ❌ | ⭐⭐ |
| Higgs-audio-v3(内置) | 所有内置语言，纯CPU运行需20G内存,GPU加速需显存大于10G | 优先使用 | ✅ | ⭐⭐ |
> ChatterBox 第一次使用除了模型外，还需要从 github.com 下载2个文件到 `models`文件夹内，如果下载失败，请手动从该地址下载 [https://github.com/explosion/spacy-pkuseg/releases/download/v0.0.26/spacy_ontonotes.zip](https://github.com/explosion/spacy-pkuseg/releases/download/v0.0.26/spacy_ontonotes.zip),下载后解压，会得到2个文件，分别是`features.msgpack`和`weights.npz`，将他们复制到`软件目录/models/pkuser_home` 内，如果不存在该文件夹，请新建
**因国内网络环境问题，加之模型都比较巨大，自动下载有可能失败，如果失败，[请点击查看模型下载地址和手动下载方式](/aboutmodels)**
---
## 本地自行部署（高阶）
| 渠道 | 说明 | 支持克隆(`clone`角色) | 推荐度 |
|------|------|---------|--------|
| [GPT-SoVITS](/gptsovits) | 支持中英日韩粤 | ✅ | ⭐⭐⭐ 推荐 |
| [Index-TTS](/gradiowin) | 中英 | ✅ | ⭐⭐⭐ 推荐 |
| [VoxCPM-TTS](/gradiowin) | 阿拉伯语、缅甸语、中文、丹麦语、荷兰语、英语、芬兰语、法语、德语、希腊语、希伯来语、印地语、印尼语、意大利语、日语、高棉语、韩语、老挝语、马来语、挪威语、波兰语、葡萄牙语、俄语、西班牙语、斯瓦希里语、瑞典语、他加禄语、泰语、土耳其语、越南语 | ✅ | ⭐⭐⭐ |
| [CosyVoice](/cosyvoice) | 中文、英语、日语、韩语、德语、西班牙语、法语、意大利语、俄语 | ✅ | ⭐⭐ |
| [ChatTTS](/chattts) | 支持中英 | — | ⭐⭐ |
| [Fish-TTS](/fishtts) | 支持内置所有语言 | — | ⭐ |
| [Kokoro-TTS](/kokorotts) | 中英韩意葡德法印地 | — | ⭐ |
| [Spark-TTS](/gradiowin) | 中英 | ✅ | ⭐⭐ |
| [clone-voice](/clone-voice) | 已不维护 | ✅ | ⭐ |
| [FireRed3-TTS](/gradiowin) | Arabic · Cantonese · Chinese · Czech · Dutch · English · Finnish · French · German · Greek · Hindi · Indonesian · Italian · Japanese · Korean · Polish · Portuguese · Romanian · Russian · Spanish · Thai · Turkish · Ukrainian · Vietnamese | ✅ | ⭐⭐ |
---
## 13. CLI 命令行模式详解
## 环境要求
| 项目 | 要求 |
|------|------|
| Python | 3.10 |
| 包管理 | [uv](https://docs.astral.sh/uv/) |
| FFmpeg | 必须安装并配置环境变量（Windows 打包版已内置） |
| GPU 加速（可选） | NVIDIA 显卡 + CUDA 12.8 + cuDNN 9.11 |
### 启动方式
```bash
# 源码部署
uv run cli.py [参数...]
# Windows 打包版 不支持命令行模式，必须源码部署使用
```
> **注意**：Windows 打包版不可使用命令行模式，必须源码部署后使用。
---
## 基本用法
```bash
uv run cli.py --task <任务类型> --name "<文件路径>" [其他参数]
```
**四种任务类型：**
| 任务 | 说明 | 流水线 |
|------|------|--------|
| `stt` | 语音转录 — 将音频/视频中的人声转为 SRT 字幕 | 预处理 → 语音识别 → 说话人分离 → 输出字幕 |
| `tts` | 文字配音 — 将 SRT 字幕或文本转为语音音频 | 预处理 → 配音 → 音画对齐 → 输出音频 |
| `sts` | 字幕翻译 — 将 SRT 字幕翻译为目标语言 | 预处理 → 翻译 → 输出字幕 |
| `vtv` | 视频翻译 — 全流程：识别 → 翻译 → 配音 → 合成视频 | 预处理 → 识别 → 说话人分离 → 翻译 → 配音 → 对齐 → 二次识别 → 合成视频 |
---
## 全局选项
| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--task {stt,tts,sts,vtv}` | **必选** — 任务类型 | — |
| `--name FILE` | **必选** — 输入文件的绝对路径 | — |
| `--output-dir DIR` | 输出目录 | `<软件目录>/output/<文件名>/` |
| `--list {providers,languages,models}` | 查询可用渠道/语言/模型列表 | — |
| `--log-level {DEBUG,INFO,WARNING,ERROR}` | 日志级别 | `WARNING` |
| `-v, --verbose` | 详细输出（等同 `--log-level INFO`） | 否 |
| `-q, --quiet` | 静默模式，仅输出错误 | 否 |
| `--version` | 显示版本号 | — |
| `-h, --help` | 显示帮助信息 | — |
---
## 任务类型总览
### 各任务必选参数
| 任务 | `--name` | `--voice_role` | `--source_language_code` | `--target_language_code` |
|------|:---:|:---:|:---:|:---:|
| `stt` | ✅ | — | — | — |
| `tts` | ✅ | ✅ | — | — |
| `sts` | ✅ | — | 可选（默认 auto） | ✅ |
| `vtv` | ✅ | 可选（默认 No） | ✅ | ✅ |
### 各任务参数范围
| 参数 | stt | tts | sts | vtv |
|------|:---:|:---:|:---:|:---:|
| `--recogn_type` | ✅ | — | — | ✅ |
| `--detect_language` | ✅ | — | — | ✅ |
| `--model_name` | ✅ | — | — | ✅ |
| `--cuda` | ✅ | — | — | ✅ |
| `--remove_noise` | ✅ | — | — | ✅ |
| `--enable_diariz` | ✅ | — | — | ✅ |
| `--nums_diariz` | ✅ | — | — | ✅ |
| `--rephrase` | ✅ | — | — | ✅ |
| `--fix_punc` | ✅ | — | — | ✅ |
| `--tts_type` | — | ✅ | — | ✅ |
| `--voice_role` | — | ✅ | — | ✅ |
| `--voice_rate` | — | ✅ | — | ✅ |
| `--volume` | — | ✅ | — | ✅ |
| `--pitch` | — | ✅ | — | ✅ |
| `--voice_autorate` | — | ✅ | — | ✅ |
| `--align_sub_audio` | — | ✅ | — | ✅ |
| `--translate_type` | — | — | ✅ | ✅ |
| `--source_language_code` | — | — | ✅ | ✅ |
| `--target_language_code` | — | — | ✅ | ✅ |
| `--video_autorate` | — | — | — | ✅ |
| `--is_separate` | — | — | — | ✅ |
| `--recogn2pass` | — | — | — | ✅ |
| `--subtitle_type` | — | — | — | ✅ |
| `--clear_cache` | — | — | — | ✅ |
---
## STT — 语音转录
将音频或视频中的人声转录为带时间轴的 SRT 字幕文件。
### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--recogn_type` | int | `0` | 语音识别渠道编号（0=faster-whisper, 1=openai-whisper, ...） |
| `--detect_language` | str | `auto` | 音频发音语言（auto=自动检测, zh-cn, en, ja, ...） |
| `--model_name` | str | `tiny` | 模型名称（仅 faster-whisper/openai-whisper 有效） |
| `--cuda` | flag | 否 | 启用 CUDA GPU 加速 |
| `--remove_noise` | flag | 否 | 启用降噪 |
| `--enable_diariz` | flag | 否 | 启用说话人识别 |
| `--nums_diariz` | int | `-1` | 说话人数量（-1=自动检测） |
| `--rephrase` | int | `0` | 重新断句（0=默认, 1=LLM 断句） |
| `--fix_punc` | flag | 否 | 恢复标点符号 |
---
## TTS — 文字配音
将 SRT 字幕文件或纯文本文件转换为语音音频。
### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--tts_type` | int | `0` | 配音渠道编号（0=Edge-TTS, ...） |
| `--voice_role` | str | **必选** | 音色名称 |
| `--voice_rate` | str | `+0%` | 语速（如 `+20%` 加速, `-10%` 减速） |
| `--volume` | str | `+0%` | 音量（如 `+50%` 增大, `-30%` 减小） |
| `--pitch` | str | `+0Hz` | 音调（如 `+10Hz` 变尖锐, `-5Hz` 变低沉） |
| `--voice_autorate` | flag | 否 | 自动加速音频以对齐字幕时间轴 |
| `--align_sub_audio` | flag | 否 | 强制修改字幕时间轴以对齐音频 |
| `--target_language_code` | str | `None` | 目标语言代码 |
### 常用 Edge-TTS 音色
| 音色名称 | 性别 | 语言 | 说明 |
|----------|------|------|------|
| `zh-CN-YunyangNeural` | 男 | 中文 | 云扬 — 新闻播报风格 |
| `zh-CN-XiaoxiaoNeural` | 女 | 中文 | 晓晓 — 自然对话 |
| `zh-CN-YunxiNeural` | 男 | 中文 | 云希 — 年轻活泼 |
| `en-US-GuyNeural` | 男 | 英文 | Guy — 自然男声 |
| `en-US-JennyNeural` | 女 | 英文 | Jenny — 自然女声 |
| `en-US-AriaNeural` | 女 | 英文 | Aria — 专业女声 |
| `en-US-EmmaNeural` | 女 | 英文 | Emma — 温暖女声 |
| `en-US-BrianNeural` | 男 | 英文 | Brian — 沉稳男声 |
> 完整音色列表请运行 `uv run cli.py --list providers` 或在软件 GUI 的 TTS 设置中查看。
---
## STS — 字幕翻译
将 SRT 字幕文件从一种语言翻译为另一种语言。
### 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--translate_type` | int | `0` | 翻译渠道编号（0=Google, ...） |
| `--source_language_code` | str | `auto` | 源语言代码（auto=自动检测） |
| `--target_language_code` | str | **必选** | 目标语言代码 |
---
## VTV — 视频翻译
全流程视频翻译：语音识别 → 字幕翻译 → 配音 → 音画合成。这是最常用也是最复杂的任务类型。
### 参数说明
VTV 模式包含 STT + TTS + STS 的所有参数，加上以下额外参数：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--source_language_code` | str | **必选** | 源语言代码（不可为 auto） |
| `--target_language_code` | str | **必选** | 目标语言代码 |
| `--voice_role` | str | `No` | 配音角色（`No`=不配音） |
| `--video_autorate` | flag | 否 | 自动慢速视频以对齐配音 |
| `--is_separate` | flag | 否 | 分离人声背景声 |
| `--recogn2pass` | flag | 否 | 二次语音识别（生成更精准字幕） |
| `--subtitle_type` | int | `1` | 字幕类型（0=无, 1=硬字幕, 2=软字幕, 3=硬字幕双语, 4=软字幕双语） |
| `--clear_cache` | flag | 是 | 完成后清理缓存 |
| `--no-clear-cache` | flag | — | 不清理缓存 |
---
## 完整示例
以下示例均假设：
- 中文原始视频文件为 `60.mp4`
- 中文字幕文件为 `zw.srt`
- 翻译目标语言为英文
- 配音使用 Edge-TTS 的 `en-US-GuyNeural` 音色
- 其他非必须参数保持默认
### 场景 1：仅语音转录（中文字幕生成）
```bash
uv run cli.py --task stt --name "60.mp4" --detect_language zh-cn --cuda
```
**说明**：将 `60.mp4` 中的中文语音转录为 `zh-cn.srt` 字幕文件，输出到 `output/60-mp4/`。
### 场景 2：仅字幕翻译（中文字幕 → 英文字幕）
```bash
uv run cli.py --task sts --name "zw.srt" --source_language_code zh-cn --target_language_code en
```
**说明**：将 `zw.srt` 翻译为 `en.srt`，输出到 `output/zw-srt/`。
### 场景 3：仅文字配音（为中文字幕生成英文配音）
```bash
uv run cli.py --task tts --name "zw.srt" --voice_role "en-US-GuyNeural" --target_language_code en
```
**说明**：为 `zw.srt` 中的文本生成英文配音 WAV 文件，输出到 `output/zw-srt/`。
### 场景 4：完整视频翻译（中文 → 英文，带配音）
```bash
uv run cli.py --task vtv --name "60.mp4" --source_language_code zh-cn --target_language_code en --voice_role "en-US-GuyNeural" --cuda
```
**说明**：全流程处理：
1. 识别 `60.mp4` 中的中文语音 → 生成中文字幕
2. 将中文字幕翻译为英文字幕
3. 使用 Edge-TTS Guy 男声生成英文配音
4. 将英文字幕和配音合成到视频中
输出：`output/60-mp4/60.mp4`（翻译后的视频）
---
## 13.2 WebUI界面使用说明
# pyVideoTrans WebUI 使用指南
## ⚠️ 重要提示
> **WebUI 版本仅实现了部分功能**，主要用于以下场景：
> - 云服务器部署（远程访问翻译服务）
> - 局域网内部署（服务器与使用机分离）
> - Docker 容器化部署
>
> **如需完整功能**，请使用桌面客户端（`sp.exe`）或源码运行（`sp.py`）。
> 桌面版支持更多 API 渠道配置、实时交互编辑、批量处理等高级功能。
---
## 一、部署方式
### 1.1 源码部署（推荐）
```bash
git clone https://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans
uv sync --extra webui
```
启动服务：
```bash
uv run webui.py # 默认 0.0.0.0:7860
uv run webui.py --port 8080 # 指定端口
uv run webui.py --host 127.0.0.1 # 仅本机访问
uv run webui.py --share # 创建 Gradio 公网链接
```
访问：`http://127.0.0.1:7860` 或 `http://<服务器IP>:7860`
### 1.2 Docker 部署
```bash
# 构建镜像
git clone https://github.com/jianchang512/pyvideotrans.git
cd pyvideotrans
docker build -t pyvideotrans-webui .
# 运行
docker run -d -p 7860:7860 --name pyvideotrans pyvideotrans-webui
# 持久化配置和输出
docker run -d -p 7860:7860 \
-v ./data/output:/app/output \
-v ./data/config:/app/videotrans \
--name pyvideotrans pyvideotrans-webui
# GPU 加速
docker run -d -p 7860:7860 --gpus all \
-v ./data/output:/app/output \
-v ./data/config:/app/videotrans \
--name pyvideotrans pyvideotrans-webui
```
### 1.3 Google Colab
1. 打开 https://colab.research.google.com/drive/1kPTeAMz3LnWRnGmabcz4AWW42hiehmfm?usp=sharing
2. 登录 Google 账号 → 点击 **全部运行**
3. 等待 `*.gradio.live` 链接出现，点击使用
> ⚠️ Colab 免费版有 4-6 小时使用时长限制。
---
## 14. 手动下载 各个渠道使用的模型
为减小软件体积，不内置任何模型，将在第一次使用时自动在线下载，主要从国外模型仓库`huggingface.co`、国内镜像站`hf-mirror.com`和 阿里魔塔`modelscope.cn`下载
本页面列出所有用到的模型下载地址、下载后本地存放位置，若自动下载总是失败，可先删掉已下载的模型文件，然后尝试手动下载。
> 模型体积普遍较大、国外模型仓库国内无法直接访问，需科学上网，无科学上网时软件内部会自动切换国内镜像站
>
> 即便已科学上网，但若是科学工具网络不够稳定仍可能下载失败；
>
> 而国内镜像站有下载频率限制，下载速度也不够快、不够稳定。
>
> 由于以上种种原因，下载失败非常常见，很多其他错误也多由模型下载失败后间接引发的。
> 下载失败后，有可能缺失模型，报错类似`Error no file named pytorch_model.bin, model.safetensors, tf_model.h5, model.ckpt.index or flax_model.msgpack`，也可能模型存在，但不完整，例如只下载了一部分，进入模型目录看起来一切都存在，但实际可能不完整， 建议删掉，然后重新下载
**软件目录是指`sp.exe`或`sp.py`所在的文件夹**
- **国外模型仓库地址**：https://huggingface.co
- **部分阿里模型和onnx模型将从阿里魔塔下载**： https://modelscope.cn
::: details 下载注意事项
一般每个模型都有多个文件组成，而不同模型可能存在相同名字的文件，例如大多都存在`model.safetensors`，如果你下载目录下已存在同名文件，浏览器可能为自动为你重命名，例如你下载的是`model.safetensors`,可能被自动命名为`model(2).safetensors`，你必须重新改回原名，然后放到要求的存放位置，软件才能识别到。
在 huggingface.co 网站，点击下载图标，即可下载该模型文件
:::
## 语音识别渠道所用模型
### Qwen-ASR(内置)
**0.6B模型：**
- 下载地址：https://huggingface.co/Qwen/Qwen3-ASR-0.6B/tree/main
- 存放位置：`软件目录/models/models--Qwen--Qwen3-ASR-0.6B`
**1.7B模型：**
- 下载地址：https://huggingface.co/Qwen/Qwen3-ASR-1.7B/tree/main
- 存放位置：`软件目录/models/models--Qwen--Qwen3-ASR-1.7B`
### Firered中文(内置)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/fireredasr2aed.zip
- 存放位置：`软件目录/models/复制压缩包内的 fireredasr 文件夹到此`
### Dolphin(内置)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/dolphin.zip
- 存放位置：`软件目录/models/复制压缩包内的 dolphin 文件夹到此`
### Omnilingual亚洲语言(内置)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/omnilingual.zip
- 存放位置：`软件目录/models/复制压缩包内的 omnilingual 文件夹到此`
### parakeet日语(内置)(v4.12后已移除该渠道，请改用 nemotron-3.5-asr-0.6b)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/parakeet-ja.zip
- 存放位置：`软件目录/models/复制压缩包内的 parakeet 文件夹到此`
### Moss-Diarize(内置)
- 下载地址：https://huggingface.co/OpenMOSS-Team/MOSS-Transcribe-Diarize/tree/main
- 存放位置：`软件目录/models/models--OpenMOSS-Team--MOSS-Transcribe-Diarize`
### faster-whisper(内置)
| 模型名称 | 本地存放位置 | 下载地址 |
|----------|-----------|---------------------|
| tiny | `软件目录/modles/models--Systran--faster-whisper-tiny` | https://huggingface.co/Systran/faster-whisper-tiny/tree/main |
| base | `软件目录/modles/models--Systran--faster-whisper-base` | https://huggingface.co/Systran/faster-whisper-base/tree/main |
| small | `软件目录/modles/models--Systran--faster-whisper-small` | https://huggingface.co/Systran/faster-whisper-small/tree/main |
| medium | `软件目录/modles/models--Systran--faster-whisper-medium` | https://huggingface.co/Systran/faster-whisper-medium/tree/main |
| large-v1 | `软件目录/modles/models--Systran--faster-whisper-large-v1` | https://huggingface.co/Systran/faster-whisper-large-v1/tree/main |
| large-v2 | `软件目录/modles/models--Systran--faster-whisper-large-v2` | https://huggingface.co/Systran/faster-whisper-large-v2/tree/main |
| large-v3 | `软件目录/modles/models--Systran--faster-whisper-large-v3` | https://huggingface.co/Systran/faster-whisper-large-v3/tree/main |
| large-v3-turbo | `软件目录/modles/models--mobiuslabsgmbh--faster-whisper-large-v3-turbo` | https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/tree/main |
|----------|-----------|---------------------|
| tiny.en | `软件目录/modles/models--Systran--faster-whisper-tiny.en` | https://huggingface.co/Systran/faster-whisper-tiny.en/tree/main |
| base.en | `软件目录/modles/models--Systran--faster-whisper-base.en` | https://huggingface.co/Systran/faster-whisper-base.en/tree/main |
| small.en | `软件目录/modles/models--Systran--faster-whisper-small.en` | https://huggingface.co/Systran/faster-whisper-small.en/tree/main |
| medium.en | `软件目录/modles/models--Systran--faster-whisper-medium.en` | https://huggingface.co/Systran/faster-whisper-medium.en/tree/main |
|----------|-----------|---------------------|
| distil-large-v2 | `软件目录/modles/models--Systran--faster-distil-whisper-large-v2` | https://huggingface.co/Systran/faster-distil-whisper-large-v2/tree/main |
| distil-large-v3 | `软件目录/modles/models--Systran--faster-distil-whisper-large-v3` | https://huggingface.co/Systran/faster-distil-whisper-large-v3/tree/main |
| distil-large-v3.5 | `软件目录/modles/models--distil-whisper--distil-large-v3.5-ct2` | https://huggingface.co/distil-whisper/distil-large-v3.5-ct2/tree/main |
| distil-small.en | `软件目录/modles/models--Systran--faster-distil-whisper-small.en` | https://huggingface.co/Systran/faster-distil-whisper-small.en/tree/main |
| distil-medium.en | `软件目录/modles/models--Systran--faster-distil-whisper-medium.en` | https://huggingface.co/Systran/faster-distil-whisper-medium.en/tree/main |
### openai-whisper(内置)
> 下载后的.pt模型文件直接放在 `软件目录/models` 文件夹内即可
- **tiny.en** https://openaipublic.azureedge.net/main/whisper/models/d3dd57d32accea0b295c96e26691aa14d8822fac7d9d27d5dc00b4ca2826dd03/tiny.en.pt
- **tiny** https://openaipublic.azureedge.net/main/whisper/models/65147644a518d12f04e32d6f3b26facc3f8dd46e5390956a9424a650c0ce22b9/tiny.pt
- **base.en** https://openaipublic.azureedge.net/main/whisper/models/25a8566e1d0c1e2231d1c762132cd20e0f96a85d16145c3a00adf5d1ac670ead/base.en.pt
- **base** https://openaipublic.azureedge.net/main/whisper/models/ed3a0b6b1c0edf879ad9b11b1af5a0e6ab5db9205f891f668f8b0e6c6326e34e/base.pt
- **small.en** https://openaipublic.azureedge.net/main/whisper/models/f953ad0fd29cacd07d5a9eda5624af0f6bcf2258be67c92b79389873d91e0872/small.en.pt
- **small** https://openaipublic.azureedge.net/main/whisper/models/9ecf779972d90ba49c06d968637d720dd632c55bbf19d441fb42bf17a411e794/small.pt
- **medium.en** https://openaipublic.azureedge.net/main/whisper/models/d7440d1dc186f76616474e0ff0b3b6b879abc9d1a4926b7adfa41db2d497ab4f/medium.en.pt
- **medium** https://openaipublic.azureedge.net/main/whisper/models/345ae4da62f9b3d59415adc60127b97c714f32e89e936602e85993674d08dcb1/medium.pt
- **large-v1** https://openaipublic.azureedge.net/main/whisper/models/e4b87e7e0bf463eb8e6956e646f1e277e901512310def2c24bf0e11bd3c28e9a/large-v1.pt
- **large-v2** https://openaipublic.azureedge.net/main/whisper/models/81f7c96c852ee8fc832187b0132e569d6c3065a3252ed18e56effd0b6a73e524/large-v2.pt
- **large-v3** https://openaipublic.azureedge.net/main/whisper/models/e5b1a55b89c1367dacf97e3e19bfd829a01529dbfdeefa8caeb59b3f1b81dadb/large-v3.pt
- **large** https://openaipublic.azureedge.net/main/whisper/models/e5b1a55b89c1367dacf97e3e19bfd829a01529dbfdeefa8caeb59b3f1b81dadb/large-v3.pt
- **large-v3-turbo** https://openaipublic.azureedge.net/main/whisper/models/aff26ae408abcba5fbf8813c21e62b0941638c5f6eebfb145be0c9839262a19a/large-v3-turbo.pt
- **turbo** https://openaipublic.azureedge.net/main/whisper/models/aff26ae408abcba5fbf8813c21e62b0941638c5f6eebfb145be0c9839262a19a/large-v3-turbo.pt
### HuggingFace_ASR(内置)
显示的模型名称为
- nvidia/parakeet-tdt-0.6b-v3 | en,bg,hr,cs,da,nl,et,fi,fr,de,el,hu,it,lv,lt,mt,pl,pt,ro,sk,sl,es,sv,ru,uk
- nvidia/nemotron-3.5-asr-streaming-0.6b | [欧洲系语言及日韩越等40种](https://huggingface.co/nvidia/nemotron-3.5-asr-streaming-0.6b#supported-languages)
- `Audio8/ARK-ASR-0.6B` 支持中英等10多种语言识别
- `Audio8/ARK-ASR-3B` 支持中英等10多种语言识别
- `zai-org/GLM-ASR-Nano-2512` 支持中英识别
- `ibm-granite/granite-speech-4.1-2b` 支持法英德西班牙
- `reazon-research/japanese-wav2vec2-large-rs35kh` 日语
- `kotoba-tech/kotoba-whisper-v2.0` 日语
- `vinai/Phowhisper-large` 越南语
- `nguyenvulebinh/wav2vec2-base-vietnamese-250h` 越南语
- `biodatlab/whisper-th-large-v3` 泰语
- `sakares/wav2vec2-large-xlsr-thai-demo` 泰语
- `SiangLao/xlsr-53-lao-asr` 老挝语
- `chuuhtetnaing/whisper-large-v3-myanmar` 缅甸语
- `1morecupofhottea/whisper-turbo-khmer-v9` 柬埔寨高棉语
- `anke01/whisper-small-uyghur` 维吾尔语
- `billingsmoore/tibetan-asr-nict-tib1-whisper-small` 藏语
- `kingabzpro/whisper-large-v3-urdu` 乌尔都语
- `vasista22/whisper-tamil-small` 泰米尔语
- `theainerd/Wav2Vec2-large-xlsr-hindi` 印地语
- `cautroi/whisper-large-v3-id` 印尼语
- `Khalsuu/filipino-wav2vec2-l-xls-r-300m-official` 菲律宾
- `navai-uz/whisper-medium-uzbek` 乌兹别克语
- `MohammadKhosravi/whisper-large-v3-Persian` 波斯语
- `Ghost3454/translynx-pakistani-punjabi-whisper-small` 巴基斯坦旁遮普语
- `turkmedstt/whisper-large-v3-turkish-general` 土耳其语
- `anton-l/wav2vec2-large-xlsr-53-mongolian` 蒙古语
- `openai/whisper-large-v3` 所有内置语言
* 下载地址：https://huggingface.co/此处使用显示的模型名称替代/tree/main
* 存放位置：`软件目录/models/models--此处使用显示的名称名称替代，并将斜杠改为2个中横线`
例如显示名称是 `Audio8/ARK-ASR-0.6B`
那么下载地址就是`https://huggingface.co/Audio8/ARK-ASR-0.6B/tree/main`,
存放位置就是 `软件目录/models/models--Audio8--ARK-ASR-0.6B`
看到规律了吗？下载地址就是直接使用模型显示名称替换，存放位置也是替换，并将显示名称中的`/` 斜线改为`--`
### whisper.cpp
- windows预编译包下载地址：下载后里面的`whisper-cli`文件夹复制到`软件目录内`
* https://huggingface.co/mortimerme/repocollect/resolve/main/whisper-cpp-win32.zip?download=true
* https://modelscope.cn/models/himyworld/videotrans/resolve/master/whisper-cpp-win32.zip
- 模型下载地址：
* 下载源(墙外)：[https://huggingface.co/ggerganov/whisper.cpp/tree/main](https://huggingface.co/ggerganov/whisper.cpp/tree/main)
* 镜像下载源：[https://hf-mirror.com/ggerganov/whisper.cpp/tree/main](https://hf-mirror.com/ggerganov/whisper.cpp/tree/main)
> 单文件模型，下载后将 `.bin` 文件放入 `软件目录/models` 文件夹内。
----
----
## 翻译渠道(字幕翻译)所用模型
### Hy-MT2-1.8B(内置)
- 下载地址： https://huggingface.co/tencent/Hy-MT2-1.8B/tree/main
- 存放位置：`软件目录/models/models--tencent--Hy-MT2-1.8B`
### M2M100(内置)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/m2m100_12b_model.zip
- 存放位置：`软件目录/models/复制压缩包内的 m2m100_12b 文件夹到此`
----
----
## 配音渠道所用模型
### Piper(内置)
- 下载地址：https://huggingface.co/rhasspy/piper-voices/tree/main
- 存放位置：`软件目录/models/piper`
### VITS(内置)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/vits-tts.zip
- 存放位置：`软件目录/models/复制压缩包内的 vits 文件夹到此`
### ZipVoice(内置)
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/resolve/master/zipvoice-tts.zip
- 存放位置：`软件目录/models/复制压缩包内的 zipvoice 文件夹到此`
### OmniVoice(内置)
- 下载地址：https://huggingface.co/k2-fsa/OmniVoice/tree/main
- 存放位置：`软件目录/models/models--k2-fsa--OmniVoice`
### MOSS-TTS-Nano(内置)
- 下载地址：https://huggingface.co/OpenMOSS-Team/MOSS-TTS-Nano-100M/tree/main
- 存放位置：`软件目录/models/MOSS-TTS-Nano-100M`
- 下载地址：https://huggingface.co/OpenMOSS-Team/MOSS-Audio-Tokenizer-Nano-ONNX/tree/main
- 存放位置：`软件目录/models/MOSS-Audio-Tokenizer-Nano-ONNX`
### ChatterBox(内置)
- 下载地址：https://huggingface.co/ResembleAI/chatterbox/tree/main
- 存放位置：`软件目录/models/models--ResembleAI--chatterbox`
### Supertonic(内置)
- 下载地址：https://huggingface.co/Supertone/supertonic-3/tree/main
- 存放位置：`软件目录/models/models--Supertone--supertonic-3`
### Higgs-audio-v3(内置)
- 下载地址：https://huggingface.co/multimodalart/higgs-audio-v3-tts-4b-transformers/tree/main
- 存放位置：`软件目录/models/models--multimodalart--higgs-audio-v3-tts-4b-transformers`
### Qwen3-TTS(内置)
- 下载地址：https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-Base/tree/main
- 存放位置：`软件目录/models/models--Qwen--Qwen3-TTS-12Hz-0.6B-Base`
- 下载地址：https://huggingface.co/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice/tree/main
- 存放位置：`软件目录/models/models--Qwen--Qwen3-TTS-12Hz-0.6B-CustomVoice`
### Confucius-TTS(内置)
- 下载地址：https://huggingface.co/netease-youdao/Confucius4-TTS/tree/main
- 存放位置：`软件目录/models/models--netease-youdao--Confucius4-TTS`
- 下载地址：https://huggingface.co/facebook/w2v-bert-2.0/tree/main
- 存放位置：`软件目录/models/models--models--facebook--w2v-bert-2.0`
- 下载地址：https://huggingface.co/nvidia/bigvgan_v2_22khz_80band_256x/tree/main
- 存放位置：`软件目录/models/models--nvidia--bigvgan_v2_22khz_80band_256x`
- 下载地址：https://huggingface.co/funasr/campplus/tree/main
- 存放位置：`软件目录/models/models--funasr--campplus`
### F5-TTS(内置)
- 官方中英模型(1.35G)：https://huggingface.co/SWivid/F5-TTS/tree/main/F5TTS_v1_Base
> 存放位置: `软件目录/models/models--SWivid--F5-TTS/F5TTS_v1_Base`
- 日语模型(5.6G)：https://huggingface.co/Jmica/F5TTS/tree/main/JA_21999120
> 存放位置: `软件目录/models/models--Jmica--F5TTS/JA_21999120`
- 法语模型(5.4G)：https://huggingface.co/RASPIAUDIO/F5-French-MixedSpeakers-reduced/tree/main
> 存放位置: `软件目录/models/models--RASPIAUDIO--F5-French-MixedSpeakers-reduced`
- 德语模型(1.35G)：https://huggingface.co/hvoss-techfak/F5-TTS-German/tree/main
> 存放位置: `软件目录/models/models--hvoss-techfak--F5-TTS-German`
- 俄语模型(3.4G)：https://huggingface.co/hotstone228/F5-TTS-Russian/tree/main
> 存放位置: `软件目录/models/models--hotstone228--F5-TTS-Russian`
- 意大利语模型(1.35G)：https://huggingface.co/alien79/F5-TTS-italian/tree/main
> 存放位置: `软件目录/models/models--alien79--F5-TTS-italian`
- 西班牙语模型(5.4G)：https://huggingface.co/jpgallegoar/F5-Spanish/tree/main
> 存放位置: `软件目录/models/models--jpgallegoar--F5-Spanish`
- 印地语模型(2.5G)：https://huggingface.co/SPRINGLab/F5-Hindi-24KHz/tree/main
> 存放位置: `软件目录/models/models--SPRINGLab/F5-Hindi-24KHz`
- 阿拉伯语模型(2.6G)：https://huggingface.co/silma-ai/silma-tts/tree/main
> 存放位置: `软件目录/models/models--silma-ai--silma-tts`
- 土耳其语模型(5.6G)：https://huggingface.co/multilingual-tts/F5-TTS-OpenBible-Turkish/tree/main
> 存放位置: `软件目录/models/models--multilingual-tts--F5-TTS-OpenBible-Turkish`
- 越南语模型(5.6G)：https://huggingface.co/multilingual-tts/F5-TTS-OpenBible-Vietnamese/tree/main
> 存放位置: `软件目录/models/models--multilingual-tts--F5-TTS-OpenBible-Vietnamese`
----
----
## 说话人分离模型
### 内置模型:
- 下载地址：https://modelscope.cn/models/himyworld/videotrans/tree/master/onnx
在该地址页下载`3dspeaker_speech_eres2net_large_sv_zh-cn_3dspeaker_16k.onnx` 、`nemo_en_titanet_small.onnx`、`seg_model.onnx` 这3个文件
- 存放位置：`软件目录/models/onnx/将下载的3个文件放到此处`
### pyannote
- 下载地址：https://huggingface.co/pyannote/speaker-diarization-3.1
- 存放位置: `软件目录/models/models--pyannote--speaker-diarization-3.1`
### Ali camp++:
- 下载地址： https://modelscope.cn/models/iic/speech_campplus_speaker-diarization_common
- 存放位置：`软件目录/models/speech_campplus_speaker-diarization_common`
## 分离人声背景模型、降噪模型、标点恢复模型
下载地址：https://modelscope.cn/models/himyworld/videotrans/tree/master/onnx
存放位置：下载该页面所有 .onnx 文件后存放到 `软件目录/models/onnx/` 文件夹内
## 实时语音识别模型
- 下载地址: https://modelscope.cn/models/himyworld/videotrans/resolve/master/realtimestt.zip
- 存放位置: 下载后解压回看到一个 onnx 文件夹，将其内所有文件复制到 `软件目录/models/onnx/`
---
## 15. 常见问题排查与故障恢复 (FAQ)
### Q: Google翻译渠道经常返回 429 Client Error？
原因可能有二：
1. 请求过于频繁，导致Google报错，降低频率或高级选项中增加请求间隔
2. 可能你使用的代理(VPN) IP 不干净，被 Google标记为流量异常，请切换更干净的IP或更换不同VPN节点等
### Q: clone 音色报错找不到？
配音角色`clone`只可在视频翻译功能中作为配音角色使用，因为需要从原始视频中截取对应时间区间的音频，作为克隆音色所需的参考音频。 在单独的`语音合成`功能中是无法使用的。
### Q: 更新到 v4.09 Higgs-audio-v3 渠道报错`Subprocess Error: 'NoneType' object has no attribute 'isatty'`
答：windows预打包版可能报这个错误，请现在重新下载补丁包覆盖即可
### Q: Qwen3-TTS 遇到报错 `CUDA error: device-side assert triggered`
这是启用了CUDA加速时遇到数据超出范围导致的，首先请确保 1.显存充足，2.参考音频时长在3-10s，3.若是`clone`音色，请确保最短语音持续时长大于等于3000ms。
如果排除以上问题后，仍报此错，请升级到 `v4.05-0709`版本
### Q: 阿里百炼报错`url error, please check url！`
答：可能原因： 模型名称所选任务不匹配：例如语音识别应选`qwen-asr`开头的模型，却选了其他的，或字幕翻译模型选了`qwen-asr`开头的，此外qwen的多模态模型不允许作为字幕翻译模型，这是阿里百炼的限制，手动填写的模型请确保填写纯文本模型。
### Q: 微软翻译无法使用，报错`404 Client Error: Not Found for url: https://edge.microsoft.com/translate/auth`
答：微软翻译是使用的微软免费在线API，当前微软已更改了翻译api，请更新到 v4.09 版本，若已是v4.09，请再次下载补丁包覆盖，或改用 DeepSeek,效果更好，价格很低，去[https://platform.deepseek.com/] 登录充值(可自定义充值1元)，获取 api key，然后填写到软件菜单--翻译设置--DeepSeek的密钥中，在翻译渠道下拉里选`Deepseek`即可，deepseek-v4-pro和deepseek-v4-flash均支持思考模式，取消选中设置面板中的`Thinking`复选框，即可取消思考模式，思考模式下需要较大的max token，否则会被截断
或者使用`M2M100(内置)`本地翻译，第一次使用将在线下载模型,位置[软件目录/models/m2m100_12b]。
(Google翻译国内需代理VPN才可用，当选择Google翻译并且失败时，会自动使用微软翻译重试)
### Q: 新版不好用，越更新越不好用。新版有解决不了的内部错误或bug
答：可以继续使用旧版，或重新下载旧版本使用，下载地址 https://pyvideotrans.com/downpackage
### Q: 都哪些渠道支持 GPU/CUDA 加速
答：语音识别转录渠道 faster-whisper / openai-whisper/Qwen-ASR/Whisper.cpp/FunASR/Huggingface_ASR/
配音渠道：Qwen3-TTS / F5-TTS /OmniVoice-TTS /Confucius-TTS/ChatterBox/Moss-Diarize/FireRed3
字幕翻译渠道：M2M100
### Q: v4.08报错`The srt subtitles were not read. The file may be empty or the format does not conform to the SRT specification`或最后一步合并音频+视频+字幕时找不到字幕
答：未选配音角色时，可能会遇到目标语言字幕找不到或为空的错误，要修复该报错，请升级到最新版本，软件左上角版本号仍是`v4.08`,源码部署的请重新下载源码覆盖
### Q: 升级 4.05/4.06版本后报错`Backend should be defined in the BACKENDS_MAPPING. Offending backend: tensorflow_text`
答：这可能是 transformers 版本升级覆盖导致的旧代码遗留问题，请尝试重新下载此刻的 补丁包再次覆盖试试
### Q: 升级软件如何保存配置文件？
答：配置文件在`软件目录/videotrans`文件夹内的几个json格式文件中，重点是这2个：`params.json/cfg.json`。完整包和补丁包是不含有这些文件的，第一次使用时自动生成，后续会根据你的设置更新，因此可以直接覆盖，会保留你的配置文件，当然你也可以复制这几个json文件到别处做备份
### Q: 能否同时启动多个 sp.exe 实例？
可以，但不建议，因多个实例共享同个`tmp`临时文件夹，并且任意一个实例关闭时，都会尝试清空该临时文件夹，可能导致其他在运行的实例报错。
如果确实需要，建议复制软件到其他文件夹内，然后再启动，例如一个在`D:/aivideo`下， 再复制一份到`D:/aivideo2`下，然后分别启动对应文件夹下的`sp.exe`，这样他们之间就互不影响
### Q: 经常提示模型下载失败或 Unable open model.bin ?
模型体积普遍较大(1G-5G)无法内置，需在第一次使用该模型时在线下载，除了部分阿里模型位于国内阿里魔塔`modelscope.cn`网站，其他均位于国外网站`huggingface.co`，而此站国内已屏蔽，无法直接访问，需科学上网(VPN/代理)，无科学上网时软件内部会自动切换至国内镜像站`hf-mirror.com`
即便已科学上网，但若是（VPN/代理）不够稳定可靠，长时间持续下载大文件仍可能失败；
而国内镜像站下载较慢、有频率限制(429)，仍有较大概率下载失败。
以上种种原因导致模型下载频频失败，很多其他错误(如Unable open/no such file等)也多由模型下载失败后间接引发。
### 15.1 启动与客户端基础运行故障
#### Q: 提示 dll 文件丢失或未找到 sp.exe 客户端闪退
检查是否下载的 260MB 的补丁包，第一次使用必须下载 2.7GB 的完整包。
#### Q: 本地部署的模型或小模型翻译结果中出现提示词或``等xml标签？
本地部署的小模型（如 7B 级参数），其指令跟随能力较弱，容易输出无关文本，请根据使用的渠道，自行精简提示词，如果你使用的是 `兼容AI/本地模型`，对应提示词在`软件目录/videotrans/prompts/srt/localllm.txt`和`软件目录/videotrans/prompts/text/localllm.txt`中，前者是选中`发送完整字幕`时使用的，后者是未选中时使用的，打开txt，精简后修改，本地小模型可能难以理解和遵守复杂提示词，可让AI帮你精简，注意`{}`包裹的是变量，不要修改不要删除，软件会自动替换变量为真实数据
#### Q: 配音后时间轴、时间也被读了出来？
批量为srt字幕配音可接受2种形式的输入，一是没有时间轴的纯文本，二是符合 SRT字幕格式的SRT内容。前者纯文本会连续读出，不进行时间语速处理，二者若同时选中`配音加速/自动加速`会按照时间轴处理配音，达到对齐效果。但注意，如果你输入/导入的配音内容有时间轴，但不符合SRT字幕格式，时间轴也将会被读出。
#### Q: 双击 `sp.exe` 后，软件无法打开，任务管理器没有反应，或者长时间黑屏？
1. **加载正常延迟**：基于 PySide6 构建的客户端在首次初始化时需搜索并加载大量本地依赖库，根据硬件性能，启动需等待 **5 秒至 2 分钟**，切勿连续重复双击。
2. **杀毒软件拦截阻断**：本软件利用 PyInstaller 进行离线绿色打包，未购买昂贵的商业数字签名，易遭腾讯管家、360、火绒或 Windows Defender 误报隔离阻断。请关闭杀毒软件或将软件根目录整体加入**信任白名单**。
3. **解压路径异常**：检查软件是否被放置在含有**中文、空格、表情或特殊符号**的盘符路径中（例如 `D:\视频 软件\pyVideoTrans` 易引发加载失败），移至浅层全英文数字目录（如 `D:\pyVideoTrans`）即可。
4. **禁止在压缩包内直接双击**：必须先利用解压软件将其完整释压到硬盘目录下，方可双击 `sp.exe`。
#### Q: 运行或启动时提示缺少 `python310.dll` 报错？
此问题代表您下载的仅仅是体积约为 260MB 的**更新升级补丁包**，而非全量主包。升级包内没有附带 Python 核心运行时。
* *解决办法*：先去官网下载 `2.6GB+` 的 **完整绿色主程序压缩包**，全量解压后，再下载升级补丁覆盖进去。
#### Q: 软件支持 Windows 7 系统吗？
**完全不支持**。软件依赖的高版本 PyTorch、OnnxRuntime 以及 PySide6 等核心框架均已停止兼容 Windows 7。请使用 Windows 10 或 Windows 11。
#### Q: 处理完一两个长视频任务后，突然发现电脑 C 盘或软件所在盘硬盘空间被彻底占满？
这是由于开启了"视频慢速"或"分离人声背景声"等高强度重构功能产生的大量临时中间缓存碎片。
* *解决办法*：通常客户端在安全关闭时会自动触发缓存回收。若遭遇中途报错中断导致临时文件未清理，可手动进入软件根目录下的 **`tmp/` 文件夹**，安全清空里面的所有临时切片。
#### Q: 如何快速清空我搞乱的所有 Key、配音和全局配置，让软件完全恢复刚下载的原始状态？
无需重新下载软件，只需进入软件根目录下的 `videotrans/` 文件夹，彻底删除以下四个持久化 JSON 配置文件：
* `params.json`（存放用户输入的 API 密钥和偏好设置）
* `cfg.json`（存放高级选项及系统设置）
* `codec.json`（视频硬解码缓存）
* `ass.json`（硬字幕样式缓存）
* *删除后直接双击 sp.exe 即可无痛重建全套出厂配置。*
#### Q: cfg.json 文件损坏导致软件设置全部丢失怎么办？
如果 `cfg.json` 文件内容被意外损坏（如手动编辑出错、意外断电等），软件会在启动时检测到 `json.JSONDecodeError`，并**自动用默认值重写该文件**。这意味着所有用户自定义设置（包括模型列表、音频参数等）将全部丢失。日志文件中会记录此错误。建议定期备份 `videotrans/` 目录下的 JSON 配置文件。
#### Q: 如何清除翻译缓存？
翻译缓存存储在 `tmp/translate_cache/` 目录下，按 MD5 键值缓存。如果发现翻译结果异常（例如使用了错误的缓存），可手动删除该目录下的缓存文件。缓存没有过期时间，相同输入会一直使用缓存。
### 15.2 GPU 加速与 CUDA / 显存报错
#### Q: 已经安装了 CUDA 工具箱，但为什么在执行时控制台仍提示未启用 GPU 加速？
1. **显卡硬件不兼容**：GPU 加速仅支持 NVIDIA 英伟达显卡（N卡）。AMD 或 Intel 的集成显卡、独立显卡均无法开启 CUDA 加速。
2. **驱动版本过于老化**：CUDA 12.8 及以上版本对显卡驱动有底线要求，请前往英伟达官网将您的显卡驱动版本更新至最新版。
3. **cuDNN 缺失**：CUDA 的深度神经网络库 cuDNN 9.x 必须安装，并将其对应的 `bin` 和 `lib` 目录完整追加配置进系统的 `Path` 环境变量。
#### Q: 在执行本地 ASR 或 TTS 时控制台疯狂报错：`Unable to allocate`、`CUDA out of memory`？
此问题代表您的显卡物理显存不足，无法承载当前运算模型。
* *解决办法（依次调优）*：
1. **降低 AI 模型尺寸**：将 ASR 从大型的 `large-v3` 模型降格更换为中型的 `medium`、`small` 或基础 `base` 模型（`large-v3` 基础运行需要不低于 8GB 的闲置显存）。
2. **更改计算数据类型**：进入 `高级选项 -> 语音识别参数`，将 `计算数据类型` 强制由 `float32` 改为 `float16`（显卡最适合）或 `int8`（最省空间）。
3. **减小搜索深度**：将 `beam_size` 和 `best_of` 从默认的 `5` 调低设为 `1`。
4. **关闭上下文感知**：将高级选项中的 `启用上下文感知` 设为 `False`。
5. **防止多卡首选卡显存过小**：若系统有集成独显与独立显卡，软件默认使用索引为 0 的显卡。若此显卡极差则会爆显存。请升级软件版本至 v3.98-317 以上，其支持自适应检测并强制调用当前可用显存最大的高性能显卡。
#### Q: BrokenProcessPool 错误是怎么回事？
当本地 AI 推理模型（如 faster-whisper）在处理过程中因 CUDA 显存溢出或底层 C++ 崩溃时，子进程会发生硬崩溃（SegFault）。软件会捕获此错误并显示 `BrokenProcessPool`，错误信息中包含模型名称和 GPU 索引。此时需要：1. 降低模型尺寸或切换为 CPU 模式；2. 关闭 GPU 同时任务数设为 1；3. 重启软件以重建进程池。
#### Q: STT 超时（SttTimeoutError）是什么原因？
faster-whisper 在某些情况下可能在生成字幕后子进程挂起（静默崩溃）。软件会在检测到字幕文件已生成但超过 20 秒仍未返回结果时抛出 `SttTimeoutError`。此时字幕文件仍然可用，但需要重启软件以恢复进程池。常见原因：CUDA 兼容性问题、显存不足、模型损坏。
#### Q: 在执行翻译合成时，任务管理器里显示 GPU 使用率非常低甚至接近 0%，这正常吗？
**完全正常**。因为流水线在 ASR 阶段（第一阶段）会集中占用 GPU 进行语音解码神经网络计算，而后续的文字翻译、TTS 云接口请求、音画速度匹配主要耗费网络和 CPU 核心。仅有在最后的视频压制时可能产生短暂的显卡硬件编解码占用，因此显卡负载呈现波峰波谷变化是符合预期的。
### 15.3 翻译、配音与特定渠道报错
#### Q: index-tts 渠道启动配音时爆出：`Value: 'Same as the voice reference' is not in the list of choices` 类似报错？
此为 `index-tts` 开源库内部的多语言界面字符翻译不一致引发的校验 Bug。
* *解决办法*：打开您本地部署的 index-tts 项目根目录下的 `webui.py` 文件，全局搜索字符串 `i18n("与音色参考音频相同")`，将其直接替换为英文：`Same as the voice reference`，保存后重启服务即可。
#### Q: 批量使用字幕配音时，即便导入了 SRT 或文本，仍不断弹窗警告 `Import SRT or Fill Text` 提示？
此为历史旧版本 Bug，请前往 pyVideoTrans 官网或 GitHub Release 页面，单独下载最新的 [sp.exe 主执行程序补丁](https://github.com/jianchang512/stt/releases/download/0.0/sp.exe)，直接覆盖替换主目录下同名文件即可解决。
#### Q: 在启动 Azure-TTS 渠道时，控制台提示：`Could not find module Microsoft.CognitiveServices.Speech.core.dll` 报错？
1. 如果您当前使用的是精简版补丁包，请重新下载并解压官方完整包。
2. 若已是完整包，说明您的 Windows 操作系统底层缺少必要的微软 C++ 运行库组件，导致底层 C 库加载失败。请下载并安装 [微软官方VC++全量运行时集合包](https://aka.ms/vs/17/release/vc_redist.x64.exe)，安装后重启电脑。
#### Q: 使用 Edge-TTS 渠道时，频繁发生 403 封禁报错、配音中断或大段生成静音无声片段？
因为 Edge-TTS 属于微软免费公开的并发接口，一旦在短时间内发起高频突发请求，您的外部公网 IP 就会被微软防火墙临时限流拦截。
* *解决办法*：进入 `高级选项 -> 字幕配音调整`，将 **`EdgeTTS配音渠道配音并发数`（同时配音线程数）设为 1**，将 **`配音后暂停秒` 设置为 5 至 10 秒**，以低频率温和调用，即可彻底避免被封限流。
* *EdgeTTS 代理问题*：EdgeTTS 在使用代理时可能遇到连接问题。如果遇到 "Please turn off the clear proxy and try again" 错误，可在软件根目录创建 `edgetts-noproxy.txt` 空文件来强制 EdgeTTS 绕过代理。EdgeTTS 在检测到代理错误时也会自动禁用代理并重试。
#### Q: 为什么在新版本的发音语言选择列表中，没有了原本的"自动检测（Auto）"选项？
为了防范多任务流水线的致命崩溃。
* 如果使用 ASR 自动检测，某些 ASR 模型遇到背景声时可能会返回杂乱的语言代码，或者直接不返回代码。然而，后续的字幕翻译大模型、TTS 配音克隆渠道对原语种和目标语种代码有严苛的入参要求。中途一旦获取不到明确的语种参数，整个流水线便会硬报错中断。
* *解决办法*：在"翻译视频或音频"主功能中，**必须明确指定发音语言**。如果仅仅是想快速转录音频转字幕，请单独使用左侧面板中的"语音转录"面板，该面板保留了"自动检测"逻辑。
#### Q: 调用大模型（如 DeepSeek、GPT）翻译后，生成的 SRT 内出现了大段空白行，或是直接把 System Prompt 提示词当成翻译塞进了字幕里？
1. **AI 大模型智能不足**：如果调用了参数规模极小的本地 LLM（如 7B 级小模型），极易发生"指令失控"问题。建议更换为 DeepSeek-V3 官方或 GPT-4o 等旗舰大模型。
2. **大模型合并了字幕**：在默认状态下，翻译大模型可能会觉得将前后两个短句拼接翻译更连贯，于是自作聪明合并了段落并返回。这会导致 pyVideoTrans 在按照行号对齐翻译时发生指针严重移位，导致后续所有字幕对应关系全部错乱。
3. *解决办法*：在高级选项中，**取消勾选"发送完整字幕"**，强制采用纯文本逐行提交翻译模式，并在高级选项中将翻译并发数 `trans_thread` 限制为 `1`。
#### Q: 翻译结果为空或全部为空白行怎么办？
翻译渠道返回了空结果。可能原因：
- 使用的 AI 模型不够智能，未按照提示词要求返回规定的格式
- AI模型重新组织合并了相邻的字幕：在原始视频中，说话人的一句长话经常被语音识别系统切成多段较短的字幕。翻译时，AI 会根据目标语言的语法习惯重新组织合并这些句子，合并到字幕后，2行字幕就变成了1行字幕加1个空白行。保留空行是为了**保护时间轴对齐；翻译后的字幕条数、时间节点与原始视频严格对应。如果手动删除空行，可能导致：双语字幕的原文与译文错位； 后续配音的时间轴混乱；无法进行精确的字幕微调。如果确实不需要空行，可以在翻译完成后手动删除。
#### Q: API 地址填写 0.0.0.0 报错怎么办？
软件会自动检测并提示 "API 地址不可是 0.0.0.0，请修改为 127.0.0.1"。请将所有本地服务的 API 地址中的 `0.0.0.0` 替换为 `127.0.0.1`。
#### Q: GPT-SoVITS 报错 `{"detail":"Not Found"}` 是什么原因？
通常有三种原因：
1. 启动了 `api.py` 但在软件中勾选了 `api_v2?`（或反之）——启动的 API 版本与勾选不一致。
2. 填写了 GPT-SoVITS 的 WebUI 地址（7860端口），而非 API 地址（9880端口）。
3. GPT-SoVITS 服务未启动。
#### Q: 如何输出无损视频？
视频处理中只要涉及重新编码，就必然损失画质，默认生成的视频是有损的，质量可通过 `高级选项--视频输出--视频输出质量、控制输出视频压缩率`进行适当调节。
**当符合以下条件时，将自动进行无损输出**：
- 原始输入视频编码是 `mp4/h.264/yuv420p`（若不符合，则自动重新编码）
- 高级选项中`264/265编码`选择的是`264`（若选265将重新编码）
- 未启用`视频慢速`（若启用则变速处理必然重新编码损失画质）
- 未嵌入`硬字幕`或`硬字幕(双)`（硬字幕需重新编码）
符合以上条件，将不进行任何视频重编码操作，因此可以无损输出。但注意可能出现的问题，若配音后时长大于视频原时长，配音超出部分将强制截断，丢失末尾一些声音，要避免，请选中 音频加速 或 增大语速。
### 15.4 音视频与 FFmpeg 报错
#### Q: 为什么最终翻译合成出来的视频，文件体积超级大，甚至是原视频的数倍？
1. **视频慢速导致定格帧膨胀**：如果勾选了"视频慢速"功能，FFmpeg 会将视频切片并大幅度降低播放速率。由于降低重编码编码损失，画面被强行重构拉伸，体积会指数级暴增。若非绝对必要，建议关闭"视频自动慢速"，仅通过"音频加速"来适应时长。
2. **码率/质量控制不当**：进入 `高级选项 -> 视频输出控制`，将 `视频输出质量控制`（CRF）从默认的 23 适当调大到 **25~30** 之间。数值越大体积越小，但画面会产生细微噪点。
3. **更换 H.265 编码**：在高级选项同个面板中，将视频编码从 264 更改为 **265**（HEVC），可在相同清晰度下直接精简 30%~50% 的物理体积。
#### Q: 执行任务时客户端弹窗报错，提示信息中包含 `ffprobe exec error` 或 `ffmpeg` 相关异常？
这通常是因为**总文件路径过长**或**文件名中夹杂特殊异常符号**。
1. Windows 命令行（CMD）有 260 个字符的物理路径最大长度限制。如果原视频本身从 YouTube 下载，标题极长且存放在很深的子目录中，命令拼接后便会超出长度限制而崩溃。请将视频移动至浅层盘符根目录（如 `D:/`），并重命名为极简的字母数字。
2. 视频文件名中如果夹杂 `?`、`*`、表情符号、不规则符号等，在传递给 FFmpeg 终端执行时极易产生解析崩塌。请彻底过滤删减文件名中的所有特殊符号。
#### Q: 软件导入视频后，提示检测到视频"不含音轨"或转录结果返回为空？
1. **视频本身无声音轨**：从一些特殊网站在线下载的视频，画面与声音流是物理分离下载的。若在合并时出错会导致视频中没有 Audio 轨道，可尝试用播放器本地播放确认是否有声音。
2. **音量过低或环境背景噪音过大**：人声完全被噪音淹没，ASR 引擎由于 VAD 切割过滤，可能判定该段音频无人类语音输入。
3. **视频编码格式不支持**：某些特殊编码格式（如 AV1）可能导致 FFmpeg 无法正确提取音频流。可尝试先用其他工具将视频转换为标准的 H.264/MP4 格式再导入。
#### Q: 硬件编码器（NVENC/QSV/AMF等）报错怎么办？
软件支持多种硬件编码器：NVENC（NVIDIA）、VideoToolbox（Mac）、QSV（Intel）、AMF（AMD）、VAAPI（Linux）。如果硬件编码失败，软件会**自动回退到软件编码**（libx264/libx265）。如果回退后仍报错，可进入高级选项勾选 `强制软编码视频？` 直接使用软件编码。
### 15.5 其他常见问题
#### Q: 为什么在 webui 网页里克隆出来的效果很好，但在软件里`clone`配音角色时出来的效果很差？
1. 在 webui 里你需要自己提供参考音频，可以提供时长合适、背景清晰、发音准确的参考音频，但 `clone` 模式下会根据字幕时长从原始视频里动态裁切，裁切后的音频片段作为参考音频，这个片段可能时长不合适、有背景噪声、或开头结尾强行中断一句话、或中间有停顿反复等，也就是参考音频质量不可控
#### Q: 是否提供上下文下载，用于提供给AI进行问答训练，例如 llms.txt等？
1. 有整理好的上下文内容llms.txt，访问该网址另存为txt，将内容提供给你的AI即可，[llms.txt](/llms.txt)
#### Q: 遇到此类报错`max_workders must be greater then 0`
1. 这是内部bug，请更新到 {$version} 或更新版本
#### Q: 代理设置即代理填写相关问题
* **代理填写**：在主界面 *对齐控制(Alignment)* 行右侧，有个网络代理文本框，可在此填写 `http`代理，类似`http://127.0.0.1:10808`，需确保已运行代理服务，并且端口正确，不可随意乱填
* **国内访问国内 API 不需要代理**：百度翻译、腾讯翻译、阿里翻译、DeepSeek、智谱AI、字节火山等国内 API 默认不走代理。软件内置了免代理域名列表（`no_proxy`），自动绕过代理。
* **本地服务不需要代理**：GPT-SoVITS（127.0.0.1:9880）、ChatTTS（127.0.0.1:9966）、F5-TTS（127.0.0.1:7860）等本地服务自动绕过代理。
* **代理格式**：正确格式为 `http://127.0.0.1:端口号` 或 `socks5://127.0.0.1:端口号`。
* **关闭代理**：如果不需要代理，请将代理文本框清空并保存。填写了无效代理地址会导致所有网络请求失败。
#### Q: 翻译缓存导致结果异常怎么办？
翻译结果会被缓存到 `tmp/translate_cache/` 目录下，使用 MD5 键值索引。缓存没有过期时间。如果修改了提示词或翻译渠道后发现结果没有变化，可能是缓存导致的。解决方法：删除 `tmp/translate_cache/` 目录下的缓存文件，或勾选主界面的 `清理已生成` 选项。
#### Q: 软件启动后界面语言显示异常怎么办？
修改界面语言后需要**重启软件**才能生效。语言翻译文件位于 `videotrans/language/` 目录下（zh.json、en.json 等）。
#### Q: 任务失败后如何查看详细错误日志？
* 日志文件位于 `logs/` 目录下，按日期命名（如 `20250622.log`）。
* 控制台日志级别为 WARNING，文件日志级别为 DEBUG，文件日志包含更详细的信息。
* 在 GUI 中可点击 "查看错误报告" 按钮查看详细堆栈信息。
#### Q: 你们的盈利模式是什么样的？
答：这是个人开发者基于兴趣创建的开源项目，无盈利目标和商业模式。为尽量延长项目生命周期，有以下几种收益方式用于支付`文档服务器费用/问答站点AI大模型调用费用/开发时在线渠道的API调用费`等。
- 文档站的少量 Google 广告
- 用户通过 `微信/支付宝二维码/Ko-fi` 的无偿打赏
- 技术群用户的月度捐赠
- GitHub 上用户的打赏
#### Q: 为何那么多纯CPU的操作， 例如背景声分离、降噪、某些内置渠道？
答：为降低软件复杂度以及软件体积，同时减小维护工作量，这些渠道若是要支持GPU加速，软件将不得不专门打包为CPU版和GPU版，加上不同GPU类型、型号，将大大增加维护难度和工作量，作为免费软件，精力有限
#### Q: 为什么使用中经常出现很多错误，以至于还存在专门的报错网站和问答网站？
视频翻译是个复杂过程，涉及 语音转录、字幕翻译、语音合成，而每个阶段都集成了多种本地AI模型、在线API服务等，本地模型涉及到在线下载(网络问题、代理问题)，本地模型通常体积较大，运行又涉及到GPU加速、OOM等，AI模型本身又涉及到模型自身智能程度。在线API涉及密钥正确性、权限、余额、网络连接(vpn/区域限制)，同时不同模型对语言支持、参考音频要求各不相同。再加上原始输入视频大小、质量、分辨率、路径名称，同时涉及到 Windows、MacOS、Linux、显卡类型、CUDA版本等，显然可能涉及到的问问方方面面。
---
## 16. 错误类型与错误消息对照表
软件内部定义了完整的异常体系，帮助定位问题根源。以下是用户可能遇到的主要错误类型及其含义：
### 16.1 异常类层级
```
VideoTransError (基类)
├── TranslateSrtError (视频翻译任务失败)
├── DubbingSrtError (TTS/配音失败)
├── SpeechToTextError (ASR/语音识别失败)
├── LLMSegmentError (LLM重新断句失败)
├── FFmpegError (FFmpeg操作失败)
├── DownloadModelsError (模型下载失败)
├── SttTimeoutError (STT子进程超时)
├── StopTask (任务立即终止，不可恢复)
└── StopRetry (停止重试，不可重试)
```
### 16.4 自定义API渠道怎么报错？
答：该定义是给有编程能力或有自己的中转API服务的用户提供，需要按照软件要求的数据格式返回数据，才可以的，直接拿第三方现成的接口填入，大概率是不能用的。如果第三方兼容 OpenAI API 格式，请填写相关信息到 `OpenAI渠道/OpenAI兼容渠道/OpenAI ChatGPT渠道`中
### 17.0 pynini 安装失败(Failed to build pynini==2.1.6)？
在 MacOSX 上需要预先执行 `brew install openfst`，然后再执行`uv sync`安装。
如果一直失败，可考虑打开 `pyproject.toml` 大约256行附近，删除这两行内容`"pynini",`和`"WeTextProcessing",`，然后再重新执行`uv sync`
### 17.0 安装 chatterbox-tts 失败？
需要确保可以连接 github.com 网站，否则会失败， 请确保科学上网，启用系统代理，确保命令行可以连接 https://github.com
---
## 18. 官方参考文档链接
[Windows版下载](https://pyvideotrans.com/downpackage)
[MacOS/Linux安装](https://pyvideotrans.com/deply)
[使用文档](https://pyvideotrans.com/getstart)
[快速上手](https://pyvideotrans.com/firstuse)
[单视频模式](https://pyvideotrans.com/danshipin)
[语音识别所有渠道](https://pyvideotrans.com/yuyinshibiequdao)
[字幕翻译所有渠道](https://pyvideotrans.com/fanyiqudao)
[文字配音所有渠道](https://pyvideotrans.com/peiyinqudao)
[语音克隆](https://pyvideotrans.com/multi-role-dubbing)
[导入本地字幕或人声](https://pyvideotrans.com/localsrt)
[短视频优化](https://pyvideotrans.com/duanshipin)
[最佳配置推荐](https://pyvideotrans.com/bester)
[手动下载模型](https://pyvideotrans.com/aboutmodels)
[常见问题FAQ](https://pyvideotrans.com/faq)
[全部语音识别渠道说明](https://pyvideotrans.com/yuyinshibiequdao)
[faster-whisper(本地内置)](https://pyvideotrans.com/faster)
[openai-whisper(本地内置)](https://pyvideotrans.com/openaiwhisper)
[Qwen-ASR(本地内置)](https://pyvideotrans.com/qwenasrlocal)
[阿里FunASR(本地内置)](https://pyvideotrans.com/funasr)
[字节语音识别大模型极速版](https://pyvideotrans.com/zijierecognmodel)
[Whisper.cpp语音识别](https://pyvideotrans.com/whisper-cli)
[阿里百炼Qwen3-ASR语音识别](https://pyvideotrans.com/qwen-mt)
[OpenAI语音识别API](https://pyvideotrans.com/openairecogn)
[Elevenlabs.io语音识别](https://pyvideotrans.com/elevenlabsrecogn)
[Parakeet-tdt语音识别](https://pyvideotrans.com/parakeet)
[Deepgram.com语音识别](https://pyvideotrans.com/deepgram)
[faster-whisper-xxl.exe语音识别](https://pyvideotrans.com/xxl)
[Whisperx-api语音识别](https://pyvideotrans.com/whisperx-api)
[智谱AI GLM-ASR语音识别](https://pyvideotrans.com/zhipu-ai)
[STT语音识别API](https://pyvideotrans.com/stt)
[自定义语音识别API](https://pyvideotrans.com/recognapi)
[Whisper.NET(AMD显卡加速)](https://pyvideotrans.com/whisper_net_setup)
[说话人识别](https://pyvideotrans.com/shuohuaren)
[全部字幕翻译渠道说明](https://pyvideotrans.com/fanyiqudao)
[Microsoft翻译(免费)](https://pyvideotrans.com/microsoft)
[Google翻译(免费)](https://pyvideotrans.com/googletranslate)
[M2M100翻译(本地内置)](https://pyvideotrans.com/m2m100)
[DeepSeek](https://pyvideotrans.com/deepseek-ai)
[百度翻译](https://pyvideotrans.com/baidu)
[腾讯翻译](https://pyvideotrans.com/tencent)
[阿里巴巴机器翻译](https://pyvideotrans.com/alibaba-machine-translation)
[DeepL翻译](https://pyvideotrans.com/deepl)
[DeepLX翻译](https://pyvideotrans.com/deeplx)
[字节火山大模型翻译](https://pyvideotrans.com/zijiehuoshan)
[302.AI翻译](https://pyvideotrans.com/302ai)
[ChatGPT翻译](https://pyvideotrans.com/openai)
[Gemini翻译](https://pyvideotrans.com/gemini-recognition)
[LibreTranslate翻译(本地API)](https://pyvideotrans.com/libretranslate)
[AzureGPT翻译](https://pyvideotrans.com/azure)
[智谱AI](https://pyvideotrans.com/zhipu-ai)
[Minimaxi AI](https://pyvideotrans.com/minimaxi)
[阿里百炼API](https://pyvideotrans.com/qwen-mt)
[硅基流动](https://pyvideotrans.com/siliconflow-ai)
[OpenRouter.ai](https://pyvideotrans.com/openrouter-ai)
[自定义翻译api](https://pyvideotrans.com/transapi)
[本地大模型/国产AI接入](https://pyvideotrans.com/localllm)
[全部配音渠道说明](https://pyvideotrans.com/peiyinqudao)
[Edge-TTS(免费)](https://pyvideotrans.com/edgetts)
[Qwen3-TTS(本地内置)](https://pyvideotrans.com/qwen-tts)
[VITS/Piper-TTS(本地内置)](https://pyvideotrans.com/vitspiper)
[OmniVoice-TTS(本地API)](https://pyvideotrans.com/omnivoice)
[GPT-SoVITS(本地API)](https://pyvideotrans.com/gptsovits)
[IndexTTS/VoxCPM/FireRedTTS3](https://pyvideotrans.com/gradiowin)
[CosyVoice3](https://pyvideotrans.com/cosyvoice)
[ChatterBox(本地内置)](https://pyvideotrans.com/chatterbox)
[Minimaxi配音](https://pyvideotrans.com/minimaxi)
[字节语音合成模型2.0](https://pyvideotrans.com/doubao2tts)
[302.AI接入配音](https://pyvideotrans.com/302ai)
[ChatTTS](https://pyvideotrans.com/chattts)
[FishTTS](https://pyvideotrans.com/fishtts)
[Gemini-TTS](https://pyvideotrans.com/gemini-tts)
[Kokoro-TTS](https://pyvideotrans.com/kokorotts)
[Azure TTS](https://pyvideotrans.com/azuretts)
[OpenAi-TTS](https://pyvideotrans.com/openaitts)
[Elevenlabs.io](https://pyvideotrans.com/elevenlabstts)
[x.ai TTS](https://pyvideotrans.com/xaitts)
[xiaomi TTS](https://pyvideotrans.com/mitts)
[智谱AI GLM-TTS](https://pyvideotrans.com/zhipu-ai)
[自定义TTS-API](https://pyvideotrans.com/ttsapi)
[新增目标语言](https://pyvideotrans.com/newlanguage)
[高级选项](https://pyvideotrans.com/adv)
[修改提示词](https://pyvideotrans.com/prompt)
[字幕语音画面对齐](https://pyvideotrans.com/subtitle-sound-alignment)
[优化断句效果](https://pyvideotrans.com/youhua)
[调节VAD精确控制语音识别](https://pyvideotrans.com/vad)
[优化本地大模型接入](https://pyvideotrans.com/llmbetter)
[提高AI渠道翻译字幕的质量](https://pyvideotrans.com/aitranslate)
[说话人识别](https://pyvideotrans.com/shuohuaren)
[为什么翻译后会出现“空白字幕行”？](https://pyvideotrans.com/faq17)
[使用参考音频后合成声音后乱糟糟](https://pyvideotrans.com/aittserror)
[Windos上配置CUDA和cuDNN](https://pyvideotrans.com/gpu)
[源码部署FunASR报错 paraformer-zh is not registered](https://pyvideotrans.com/blog/paraformer-zh-is-not-registered)
[CLI命令行](https://pyvideotrans.com/cli)
[WebUI界面](https://pyvideotrans.com/webui)
[语音转录功能](https://pyvideotrans.com/speech2text)
[文字配音功能](https://pyvideotrans.com/text2speech)
[翻译字幕功能](https://pyvideotrans.com/translate-srt)
[提取视频硬字幕为SRT](https://pyvideotrans.com/ocrsp)
[Youtube视频下载](https://pyvideotrans.com/youtubedownload)
[模型下载地址](https://pyvideotrans.com/aboutmodels)
[软件技术架构](https://pyvideotrans.com/yuanli)
[音画字幕对齐原理](https://pyvideotrans.com/blog/Synchronize)
[博客列表](https://pyvideotrans.com/bloglist)
[技术支持](https://pyvideotrans.com/support)
[小额捐赠](https://pyvideotrans.com/about)
[软件许可协议](https://pyvideotrans.com/law)
[文档使用协议](https://pyvideotrans.com/xieyi)
[隐私政策](https://pyvideotrans.com/yinsizhengce)
[联系我们](https://pyvideotrans.com/lianxi)
[关于我们](https://pyvideotrans.com/guanyu)
[为什么网站有广告？](https://pyvideotrans.com/whyad)
## 18.1 单视频交互模式
当一次仅选择一个视频进行翻译时，软件会进入交互模式，在每个处理阶段完成后弹出编辑窗口，允许你进行人工校对和微调，以确保最终效果。
> 如果一次选择多个视频，将同时交叉执行，中间不会暂停。
>
> 如果不想弹出编辑窗口，可点击`菜单 → 工具 → 高级选项 → 单视频交互模式暂停时间`，将其改为 0。
---
## 阶段一：语音识别完成后 — 字幕修改窗口
- 如果**不修改**，可直接点击底部按钮**不保存只继续**
- 如果**修改**，请首先点击右上角**倒计时**按钮，关闭倒计时，否则倒计时为0后将自动关闭并进入下一步。
- 带有`铅笔图标`的列，双击可进行编辑，例如`开始时间`和`结束时间`列，代表开始时间秒数和结束时间秒数，可进行手动调整
- 点击三角形播放按钮，播放字幕对应的视频片段
- 进阶操作：如果你想通过第三方工具修改字幕，可以点击**打开字幕文件夹**按钮，找到 `原始语言代码.srt` 文件（例如中文发音就是 `zh-cn.srt`），用外部编辑器修改后保存，然后在软件界面中点击**不保存只继续**按钮，后续将使用你修改过的文件。
---
## 阶段二：字幕翻译完成后 — 配音分配窗口
同样在修改前，需要先点击右上角**倒计时**按钮关闭倒计时，否则减为0后会自动关闭并继续下一步
- 带有`铅笔图标`的列，双击可进行编辑，例如`开始时间`和`结束时间`列，代表开始时间秒数和结束时间秒数，可进行手动调整
- 可以单独为每行字幕指定一个配音角色
- 可以为每个说话人指定一个配音角色，实现多角色配音
- 点击播放按钮，播放字幕对应的视频片段
- 进阶操作：同上，可以通过「打开字幕文件夹」找到翻译后的 SRT 文件（例如 `en.srt`），用外部编辑器修改后保存，再点击「不保存只继续」。
---
## 阶段三：配音完成后 — 校对配音/重新配音面板
同样在修改前，需要先点击右上角**倒计时**按钮关闭倒计时，否则减为0后会自动关闭并继续下一步
- 带有`铅笔图标`的列，双击可进行编辑，例如`开始时间`和`结束时间`列，代表开始时间秒数和结束时间秒数，可进行手动调整
- 点击播放按钮，预览字幕对应的视频画面和当前字幕配音，但注意：此时配音和视频均未做变速处理，因此二者大概率不会同步，可以根据预览效果调整字幕文本数量，右键重新配音
- 可以根据预览效果重新选择是否启用`配音加速`和`视频慢速`
**每一行代表一句字幕，有6列组成：从左到右依次为：**
1. **行号** 例如`[1]`：第行句字幕
2. **播放按钮**：点击播放该行字幕对应的视频画面和配音
3. **开始时间** ：双击单元格可直接手动修改（单元格上`ctrl+左右方向键`可调整时间）
* 右键单元格--`开始时间减小0.1s`：让这句话早一点开始（每次提前 0.1 秒）
* 右键单元格--`开始时间增大0.1s`：让这句话晚一点开始（每次推后 0.1 秒）
* **注意：开始时间不能早于上一句话的结束时间**
4. **结束时间** ：双击单元格可直接手动修改（单元格上`ctrl+左右方向键`可调整时间）
* 右键单元格-- `结束时间减小0.1s`：让这句话早一点结束（每次缩短 0.1 秒）
* 右键单元格-- `结束时间增大0.1s`：让这句话晚一点结束（每次延长 0.1 秒）
* **注意：结束时间不能晚于下一句话的开始时间**
5. **配音时长**：单元格上右键显示`试听`和`重新配音`按钮
* **x.xxs \<超出\> x.xxs**：配音太长，字幕时间放不下。程序会自动加速播放配音。如不希望配音变快，请**延长结束时间**或**删减字幕文字**后重配。
* **x.xxs \<缩短\> x.xxs**：配音比字幕时间短，这是正常的，会有短暂静音。
6. **字幕：双击可编辑**：右键显示`试听`和`重新配音`按钮，双击可直接编辑字幕文本
* **重新配音**：修改文字后**必须**点击此按钮，程序会根据新文字重新生成语音。
* **试听配音**：播放当前这句字幕的语音，检查读音或语调。
---
## 阶段四：二次识别后弹出字幕编辑界面
如果选中了二次识别、并且有配音、并且未嵌入双字幕，那么会弹出该界面，可在此修改错别字，然后点击保存并继续。
- 带有`铅笔图标`的列，双击可进行编辑，例如`开始时间`和`结束时间`列，代表开始时间秒数和结束时间秒数，可进行手动调整
## 注意事项
* **保存并继续下一步**：确认无误，保存字幕修改并继续执行。
* **终止本次任务**：放弃当前操作，关闭窗口。
> 💡 **小贴士**：
> * 如果列表很长，滑动或点击时请耐心等待，程序已优化过，通常反应很快。
> * 如果某行文字被清空，或者配音时长显示为 0s，该条配音将不会被合成。
## 19. 新增目标语言和发音语言
> 在 v4.11 版本之后，优化了新增语言办法,以下针对 v4.11及以上 版本
pyVideoTrans 默认已内置支持 30 多种常用目标语言。如果你需要翻译或配音到其他小众语种，可以按照以下步骤手动添加。
---
### ⚠️ 新增前必读提示
在开始添加前，请先确认：**你打算使用的翻译渠道和配音渠道，是否支持该语种？**
- 很多配音渠道（如F5-TTS）仅支持常见语种，不支持小语种；
- 部分翻译渠道（如 DeepL）支持的语言种类也相对有限。
- 部分语音识别渠道 （如Qwen-ASR）支持的语言也有限
> **注意**：如果渠道本身不支持该语言，即便在软件中添加成功，实际运行时依然会报错。
---
### 第一步：查询并获取目标语言的渠道代码
不同的翻译和识别服务对同一门语言的“代号（代码）”要求各不相同。例如【简体中文】：
- Google翻译渠道为 `zh-CN`
- DeepL 翻译渠道为 `ZH-HANS`
- Faster-whisper识别渠道为`zh`
- 软字幕规范识别为 `zho`
请按需前往对应渠道查询你的目标语言代码：
1. **Google 翻译**：[点击查询支持的语言代码](https://docs.cloud.google.com/translate/docs/languages) （例如中文是 `zh-CN`）
2. **腾讯翻译**：[点击查询支持的语言代码](https://cloud.tencent.com/document/product/551/118482) （例如中文是 `zh`）
3. **百度翻译**：[点击查询支持的语言代码](https://fanyi-api.baidu.com/product/113) （例如中文是 `zh`）
4. **DeepL / DeepLX**：[点击查询支持的语言代码](https://developers.deepl.com/docs/getting-started/supported-languages) （例如中文是 `ZH-HANS`）
5. **微软翻译 (Microsoft)**：[打开网页](https://www.bing.com/translator?mkt=zh-CN) （例如中文是 `zh-Hans`，一般与 Google 一致，也可按 F12 调试查看）
6. **阿里机器翻译**：[点击查询支持的语言代码](https://help.aliyun.com/zh/machine-translation/developer-reference/machine-translation-language-code-list) （例如中文是 `zh`）
7. **阿里百炼API**：[点击查询支持的语言代码](https://help.aliyun.com/zh/model-studio/machine-translation#14735a54e0rwb) （例如中文是 `Chinese`）
8. **M2M100**：[点击查询支持的语言代码](https://github.com/ymoslem/DesktopTranslator/blob/main/utils/m2m_languages.json) （例如中文是 `zh`，提取下划线 `__xx__` 中的 2~3 位字母）
9. **AI 翻译渠道（ChatGPT / Claude 等）**：直接填写该语言的**英文全称**（例如中文填写 `Simplified Chinese`）。
10. **LibreTranslate 渠道**：[点击查询支持的语言代码](https://docs.libretranslate.com/guides/supported_languages/) （括号内的 2~3 位代码）
11. **字幕嵌入代码（必填项）**：当生成内嵌软字幕时，必须使用 **ISO 3 位字母**代码。在下方列表中找到对应语言 `Set2` 列的 3 位字母（若区分 `T`/`B`，请使用 `T` 列，例如中文填写 `zho`）：
---
### 第二步：组装代码片段
按照以下格式模板，把你查到的真实代码替换进去：
> 💡 **小贴士**：
> 1. 如果某些翻译渠道你不使用，可以直接填 `No`(区分大小写)；
> 2. 第 2 行的 **`字幕嵌入代码`必须真实填写**，否则将无法正常嵌入软字幕。
```json
"google翻译对应的语言代码小写形式": [
"Google翻译对应的语言代码",
"字幕嵌入对应的3位语言代码",
"百度翻译对应的语言代码",
"DeepL对应的语言代码",
"腾讯翻译对应的语言代码",
"Libre渠道对应的语言代码",
"微软翻译对应的语言代码",
"AI对应填写语言的英文名称",
"阿里机器翻译对应的语言代码",
"阿里百炼API对应的语言代码",
"M2M100对应的语言代码"
]
```
**【参考范例】** 简体中文组装后的完整格式如下：
```json
"zh-cn": [
"zh-cn",
"zho",
"zh",
"ZH-HANS",
"zh",
"zh",
"zh-Hans",
"Simplified Chinese",
"zh",
"Chinese",
"zh"
]
```
---
### 第三步：写入配置文件 `languages.json`
1. 打开软件根目录下`videotrans`文件夹内的 `languages.json` 文件（推荐使用记事本或 VSCode 打开）。
2. 将你刚才组装好的代码，粘贴到大括号 `{ }` 内部。
3. **关键细节**：每组语言之间必须用**英文半角逗号 `,`** 隔开，最后一组后面不要加逗号。
**【粘贴位置示例】：**
```json
{
"ar-st": [
"es",
"spa",
"spa",
"ES-419",
"es",
"es",
"es",
"Spanish",
"es",
"Spanish",
"es"
],
"zh-cn": [
"zh-cn",
"zho",
"zh",
"ZH-HANS",
"zh",
"zh",
"zh-Hans",
"Simplified Chinese",
"zh",
"Chinese",
"zh"
]
}
```
4. 保存文件并**重启软件**，在目标语言下拉列表中就能看到新增的语言代码了。
---
### 第四步（可选）：自定义界面的显示名称
添加完成后，软件下拉框默认显示的是语言代码（如 `zh-cn`）。如果你希望显示为更友好的中文名称（如“简体中文”），请按以下步骤设置：
1. 打开文件：`软件目录/videotrans/language/zh.json`；
2. 翻到文件最底部，在最后一个 `}` 之前查看前一行末尾是否有英文逗号 `,`；
3. 如果没有，先在前一行末尾补上英文逗号 `,`，然后换行添加：
```json
"google对应的语言代码小写形式": "你想在软件中显示的中文名称"
```
*例如：`"zh-cn": "简体中文"`*
4. 保存文件并重启软件生效。
如果你的软件是英文界面，需要修改 `软件目录/videotrans/language/en.json`，方法一样
---
### ❓ 常见报错排查
如果修改后**软件启动报错或未报错但添加的语言未生效**，99% 是由于 `JSON` 格式错误造成的，这几个文件都是json文件，需要严格合法的语法，请重点检查：
1. **中英文符号**：所有标点符号（`"`、`,`、`:`、`{}`、`[]`）必须为**英文半角符号**，切勿输入中文逗号或中文引号。
2. **多余或遗漏逗号**：检查两段语言代码之间是否遗漏了逗号 `,`，或者在最后一项后面多写了逗号。
20. 自定义TTS API 渠道新增webui接入
- 方法一: 必须写代码,基于 application/x-www-form-urlencoded 的 POST 请求接口,具体方法查看 [https://pyvideotrans.com/ttsapi]
- 方法二：通过 Gradio WebUI 自定义接入任意声音克隆 TTS
很多优秀的开源 TTS（如 Index-TTS、F5-TTS、CosyVoice 等）都提供了基于 **Gradio** 的 WebUI 界面。`pyVideoTrans(v4.11)` 起已支持**通用 Gradio API 接入通道**。
---
### ⚠️ 接入前必读（核心前提）
1. **界面必须是 Gradio 开发的**（页面底部会有 `Use via API` 或`通过API使用`字样）。
2. 该模型在 WebUI 中 **必须支持声音克隆（参考音频克隆）** 功能。
---
### 接入实操步骤（以 Index-TTS 2.5 为例）
> **演示前提**：假设你已经成功启动了 Index-TTS 2.5 的 WebUI 网页（其他 TTS 的操作逻辑完全相同）。
---
### 第一步：打开 WebUI 页面底部的 API 文档
1. 浏览器打开 TTS 的 WebUI 界面，滚动页面到**最底部**。
2. 找到并点击右下角的小字 **`Use via API`**（或 `通过API使用`）。
> 💡 **提示**：如果页面底部完全找不到 `API` 字样，说明该 WebUI 启动时禁用了 API。如果自己不会改，可以将该 WebUI 的启动源码（通常是 `app.py` 或 `webui.py`）发给 AI，让 AI 帮你开启 API 功能。
---
### 第二步：找到“语音克隆”接口与核心参数
点击后会进入 API 说明页面。页面中可能会列出多个接口，我们需要找到**负责生成克隆音频**的那个接口（英文界面可借助浏览器右键翻译）。
**API接口可能非常多，在Index-TTS2.5中只有下面这个才是语音克隆接口**
*`=`号左侧是参数名，右侧是参数值*
在这个接口下，我们需要找出软件对接所需的**关键参数**。通常第一个参数和标注了 **`Required`（必填）** 的参数是必须配置的：
下拉查看参数说明列表：
#### 📝 参数类型与规则通俗讲解：
* **`api_name`（接口名称，必填）**：即告诉软件调用哪个功能端点。拉到该功能说明的最下方即可看到，例如 Index-TTS 2.5 是 `/gen_single`，也就是 `API name` 后对应的这个值。
* **配音文本参数（必填）**：通常叫 `text` 或 `tts_text`等。index-tts 2.5中是`text`
* **参考音频参数（必填）**：通常叫 `prompt`、`ref_audio`、`prompt_audio`、`prompt_wav` 等, index-tts2.5中叫`prompt`。
* **参考音频文本（选填/视模型而定）**：通常叫 `prompt_text` 或 `ref_text`。Index-TTS 2.5 不需要，但大部分模型都是需要的。
* **语言/枚举类参数（注意 `Literal` 标记）**：如果参数后面写着 `Literal[...]`，表示**单选参数**，它的值必须**完全等于**方括号里列出的其中一个选项（区分大小写）。
* 比如 `lang_choice: Literal['ZH', 'EN', 'JA', 'AR', 'ES']`，代表只能填 `ZH`、`EN`、`JA`、`AR`、`ES` 指定语言代码。
* 比如 `emo_control_method: Literal['Same as the voice reference', ...]`，我们选用第一项 `Same as the voice reference`（代表语气跟随参考音频）。
---
### 第三步：创建并编写 `gradio_api.txt` 配置文件
接下来，我们需要把上面找到的参数告诉 pyVideoTrans。
1. 进入 pyvideotrans 软件根目录（即 `sp.exe`或`sp.py` 所在的文件夹）。
2. 在该目录下**新建一个文本文档**，命名为 **`gradio_api.txt`**。
3. 打开该文件，按 **`参数名=参数值`** 的格式逐行填写（一行一个），类似下图。
#### ⚠️ 重点：动态替换占位符（固定格式）
因为字幕翻译配音时，**配音文本**和**参考音频**是每句/每个人物动态变化的，因此这些项的值要填写为软件专用的“代号”：
| 参数作用 | 右侧固定填写的值（代号） | 说明 |
| :--- | :--- | :--- |
| **配音目标文本** | `tts_text` | 软件会自动替换为每行字幕文字 |
| **参考音频文件** | `tts_audio` | 软件会自动替换为所选角色的克隆音频路径 |
| **参考音频对应的文字** | `tts_audio_text` | 某些模型需要，自动替换为参考音频的台词 。如果模型不需要，则不要填写该行参数|
以 **Index-TTS 2.5** 为例，我们在 `gradio_api.txt` 中填入以下内容(Index-TTS 2.5可在 配音渠道index-tts里直接使用，无需创建该文件，这里仅做示例 )：
```ini
emo_control_method=Same as the voice reference
prompt=tts_audio
text=tts_text
lang_choice=ZH
emo_ref_path=tts_audio
api_name=/gen_single
```
填写完成后，**保存并关闭**文件。
---
### 第四步：在软件中填入 WebUI 地址
1. 打开 `pyvideotrans` 软件。
2. 点击顶部菜单栏：**设置** -> **TTS设置** -> **自定义TTS API**。
3. 在地址栏中填入你的 WebUI 运行地址（例如 `http://127.0.0.1:7860/`），点击保存。
---
### 第五步：开始配音与角色选择
配置完成后，在软件主界面的配音渠道中选择自定义接口：
1. 在主界面**角色列表**中选择你的参考音频（或选择 `clone` 音色），软件在合成时就会自动调用你配置好的 Gradio TTS 接口进行声音克隆。
2. 如需添加更多克隆音色，可点击软件顶部菜单：**设置** -> **TTS设置** -> **设置参考音频** 进行添加和管理。
----
### 以下是几个示例，其他方式类似，具体请参考文档 https://pyvideotrans.com/ttsapi
*如下几个示例中 index-tts 可直接在配音渠道Index-TTS中使用，无需单独对接；其他几个已内置。若无特殊需要，不必单独对接，仅用于举例供对接其他WebUI时参考*
> 均根据官方自带 webui.py 创建，如果ui有变更，将失效
>
> 若有问题请附带官方demo地址或api端点参数截图评论
### index-tts 2.5 gradio_api.txt填写如下(Index-TTS 2.5可在 配音渠道index-tts里直接使用，无需创建该文件，这里仅做示例 )
```
emo_control_method=Same as the voice reference
prompt=tts_audio
text=tts_text
lang_choice=ZH
emo_ref_path=tts_audio
api_name=/gen_single
```
### F5-TTS gradio_api.txt填写如下(F5-TTS 可在 配音渠道 f5-tts里直接使用，无需创建该文件，这里仅做示例 )
```
gen_text_input=tts_text
ref_audio_input=tts_audio
ref_text_input=tts_audio_text
remove_silence=false
randomize_seed=false
seed_input=0
api_name=/basic_tts
```
### omnivoice gradio_api.txt填写如下(omnivoice-TTS 可在 配音渠道 omnivoice-tts里直接使用，无需创建该文件，这里仅做示例 )
```
text=tts_text
lang=Auto
ref_aud=tts_audio
ref_text=tts_audio_text
instruct=
du=0
api_name=/_clone_fn
```
### qwen3-tts gradio_api.txt填写如下(qwen3-TTS 可在 配音渠道 qwen-tts 里直接使用，无需创建该文件，这里仅做示例 )
```
ref_audio=tts_audio
ref_text=tts_audio_text
target_text=tts_text
language=Auto
use_xvector_only=false
model_size=1.7B
api_name=/generate_voice_clone
```
## pyproject.toml 文件内容
````
[project]
name = "pyVideoTrans"
version = "4.12"
requires-python = ">=3.10, <3.11"
dependencies = [
"absl-py==2.0.0",
"accelerate==1.12.0",
"addict==2.4.0",
"aenum==3.1.15",
"aiofiles==24.1.0",
"aiohappyeyeballs==2.6.1",
"aiohttp==3.12.13",
"aiosignal==1.3.2",
"alibabacloud-alimt20181012==1.1.0",
"alibabacloud-credentials==0.3.6",
"alibabacloud-endpoint-util==0.0.3",
"alibabacloud-gateway-spi==0.0.2",
"alibabacloud-openapi-util==0.2.2",
"alibabacloud-openplatform20191219==2.0.0",
"alibabacloud-oss-sdk==0.1.0",
"alibabacloud-oss-util==0.0.6",
"alibabacloud-tea==0.4.0",
"alibabacloud-tea-fileform==0.0.5",
"alibabacloud-tea-openapi==0.3.12",
"alibabacloud-tea-util==0.3.13",
"alibabacloud-tea-xml==0.0.2",
"aliyun-python-sdk-core==2.16.0",
"aliyun-python-sdk-kms==2.16.5",
"altgraph==0.17.4",
"annotated-types==0.6.0",
"antlr4-python3-runtime==4.9.3",
"anyio==4.9.0",
"asttokens==2.4.1",
"astunparse==1.6.3",
"async-timeout==5.0.1",
"attrs==25.3.0",
"audioread==3.0.1",
"av==16.0.1",
"azure-cognitiveservices-speech",
"blinker==1.8.2",
"cachetools==5.3.2",
"certifi==2025.10.5",
"cffi==1.17.1",
"chardet==3.0.4",
"charset-normalizer==3.4.4",
"click==8.1.7",
"colorama==0.4.6",
"coloredlogs==15.0.1",
"contourpy==1.1.1",
"crcmod==1.7",
"cryptography==45.0.4",
"ctranslate2==4.8",
"cycler==0.12.1",
"dashscope",
"dataclasses-json==0.6.7",
"datasets==3.0.0",
"decorator==5.2.1",
"deepgram-captions==1.2.0",
"deepgram-sdk==4.1.0",
"deepl==1.18.0",
"deprecation==2.1.0",
"diffusers==0.33.1",
"dill==0.3.8",
"distro==1.8.0",
"editdistance==0.8.1",
"exceptiongroup==1.2.2",
"executing==2.0.1",
"ffmpeg-python==0.2.0",
"filelock==3.13.1",
"flatbuffers==25.9.23",
"fonttools==4.43.1",
"frozenlist==1.7.0",
"fsspec==2024.6.1",
"future==0.18.3",
"gast==0.4.0",
"googleapis-common-protos",
"grpcio==1.60.0",
"grpcio-status==1.60.0",
"h11==0.14.0",
"h2==3.2.0",
"h5py==3.10.0",
"hdbscan==0.8.40",
"hf-xet",
"hpack==3.0.0",
"hstspreload==2023.1.1",
"httpcore==1.0.6",
"httplib2==0.22.0",
"httpx[socks]==0.28.1",
"huggingface",
"humanfriendly==10.0",
"hydra-core==1.3.2",
"hyperframe==5.2.0",
"idna==3.11",
"imageio==2.31.4",
"imageio-ffmpeg==0.4.9",
"importlib-metadata==8.7.0",
"inflate64==1.0.0",
"ipython==8.23.0",
"iso639-lang==2.2.3",
"itsdangerous==2.2.0",
"jaconv==0.4.0",
"jamo==0.4.1",
"jedi==0.19.1",
"jieba==0.42.1",
"jinja2==3.1.6",
"jiter==0.11.1",
"jmespath==0.10.0",
"joblib==1.5.1",
"kaldiio==2.18.1",
"keras==2.9.0",
"keras-preprocessing==1.1.2",
"kiwisolver==1.4.5",
"lazy-loader==0.4",
"libclang==16.0.6",
"librosa==0.11.0",
"llvmlite==0.44.0",
"markdown==3.5",
"markdown-it-py==4.0.0",
"markupsafe==2.1.3",
"marshmallow==3.23.0",
"matplotlib-inline==0.1.6",
"mdurl==0.1.2",
"more-itertools==10.1.0",
"mpmath==1.3.0",
"msgpack==1.1.1",
"mypy-extensions==1.0.0",
"networkx==3.2",
"norbert==0.2.1",
"numba==0.61.2",
"numpy==1.26.0",
"oauthlib==3.2.2",
"omegaconf==2.3.0",
"opt-einsum==3.3.0",
"ordered-set==4.1.0",
"oss2==2.19.1",
"packaging==25.0",
"pandas==2.3.0",
"parso==0.8.3",
"pefile==2023.2.7",
"peft==0.15.2",
"pip==25.1.1",
"platformdirs==4.3.8",
"plyer==2.1.0",
"pooch==1.8.2",
"proglog==0.1.10",
"prompt-toolkit==3.0.43",
"propcache==0.3.2",
"proto-plus==1.23.0",
"protobuf==4.21.6",
"psutil==6.0.0",
"pure-eval==0.2.2",
"py7zr==0.22.0",
"pyarrow==20.0.0",
"pyasn1==0.5.0",
"pyasn1-modules==0.3.0",
"pybcj==1.0.2",
"pycparser==2.22",
"pycryptodome==3.23.0",
"pycryptodomex==3.21.0",
"pydantic==2.12.5",
"pydantic-core==2.41.5",
"pydub==0.25.1",
"pygments==2.17.2",
"pyinstaller==6.16.0",
"pyinstaller-hooks-contrib==2025.8",
"pynndescent==0.5.13",
"pyparsing==3.1.1",
"pyppmd==1.1.0",
"pyside6==6.9.2",
"pyside6-addons==6.9.2",
"pyside6-essentials==6.9.2",
"pysoundfile==0.9.0.post1",
"python-dateutil==2.9.0.post0",
"pytorch-wpe==0.0.1",
"pytz==2025.2",
"pyyaml==6.0.3",
"pyzstd==0.16.1",
"qdarkstyle==3.2.3",
"regex",
"requests[socks]==2.32.5",
"requests-oauthlib==1.3.1",
"resampy==0.4.2",
"rfc3986==1.5.0",
"rich==14.2.0",
"rsa==4.9",
"safetensors==0.8.0",
"scikit-learn==1.7.0",
"scipy==1.15.3",
"sentencepiece==0.2.0",
"setuptools==80.9.0",
"shellingham==1.5.4",
"shiboken6==6.9.2",
"simplejson==3.19.3",
"six==1.17.0",
"snakeviz==2.2.2",
"sniffio==1.3.1",
"sortedcontainers==2.4.0",
"soundfile==0.13.1",
"soxr==0.5.0.post1",
"speechrecognition==3.10.0",
"srt==3.5.2",
"stack-data==0.6.3",
"sympy==1.14.0",
"tabulate==0.9.0",
"tenacity==9.1.2",
"tencentcloud-sdk-python==3.0.1223",
"tencentcloud-sdk-python-common==3.0.1032",
"tencentcloud-sdk-python-tmt==3.0.1032",
"tensorboardx==2.6.4",
"tiktoken==0.8.0",
"torch==2.7.1",
"torch-complex==0.4.4",
"torchaudio==2.7.1",
"tqdm==4.67.1",
"typer==0.19.2",
"typing-extensions==4.15.0",
"typing-inspect==0.9.0",
"tzdata==2025.2",
"urllib3==2.5.0",
"websocket-client==1.8.0",
"websockets==13.1",
"wheel==0.45.1",
"wrapt==1.15.0",
"xxhash==3.5.0",
"yarl==1.20.1",
"zhconv==1.4.3",
"sherpa-onnx>=1.13.0",
"sherpa-onnx-core>=1.13.0",
"sounddevice>=0.5.3",
"openai-whisper>=20250625",
"multidict>=6.7",
"pytsmod>=0.3.8",
"pyrubberband>=0.4.0",
"piper-tts>=1.3.0",
"pillow>=12.0.0",
"gradio-client>=2.0.1",
"ten-vad>=1.0.6.8",
"pyannote-audio",
"modelscope==1.34.0",
"funasr==1.3.1",
"edge-tts",
"onnxruntime",
"openai",
"litellm>=1.85.0,<2.0",
"faster-whisper",
"google-genai",
"elevenlabs",
"camb-sdk",
"brotli>=1.2.0",
"gtts>=2.5.4",
"importlib-resources",
"g2pw>=0.1.1",
"unicode-rbnf>=2.4.0",
"sentence-stream>=1.3.0",
"google-cloud-storage>=3.12.0",
"pynini",
"WeTextProcessing",
"transformers4576==4.57.6.4",
"omnivoice",
"qwen-asr-pvt",
"qwen-tts-pvt",
"f5-tts",
"gradio>=6.8.0",
"inflect>=7.5.0",
"chatterbox-tts>=0.1.7",
"transformers>=5.13.1",
"huggingface-hub>=1.10.0",
"pythonnet",
"bitsandbytes>=0.49.2",
]
[project.optional-dependencies]
webui = [
"gradio"
]
[dependency-groups]
dev = [
"pytest",
]
lint = [
"ruff",
]
# 忽略版本冲突错误
[tool.uv]
override-dependencies = [
"torch==2.7.1",
"transformers==5.13.1",
"torchaudio==2.7.1",
"diffusers==0.33.1",
"safetensors==0.8.0",
"f5-tts==1.1.20",
"huggingface-hub==1.10.0",
"chatterbox-tts==0.1.7",
"google-cloud-storage==3.12.0",
"torchcodec ; sys_platform == 'never'",
"pythonnet ; sys_platform == 'win32'",
]
index-strategy = "unsafe-best-match"
[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
[tool.uv.sources]
torch = [
{ index = "pytorch-cu128", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
{ index = "pytorch-cpu", marker = "sys_platform == 'darwin'" }, # darwin 为 macOS
]
torchaudio = [
{ index = "pytorch-cu128", marker = "sys_platform == 'win32' or sys_platform == 'linux'" },
{ index = "pytorch-cpu", marker = "sys_platform == 'darwin'" },
]
# 仅针对 Windows (win32) 平台指定从 URL 下载 wheel 文件
# https://github.com/OpenMOSS/MOSS-TTS-Nano/issues/6
# https://github.com/billwuhao/pynini-windows-wheels/releases/download/v2.1.6.post1/pynini-2.1.6.post1-cp310-cp310-win_amd64.whl
pynini = [
{ url = "https://github.com/billwuhao/pynini-windows-wheels/releases/download/v2.1.6.post1/pynini-2.1.6.post1-cp310-cp310-win_amd64.whl", marker = "sys_platform == 'win32'" }
]
chatterbox-tts = { url = "https://github.com/resemble-ai/chatterbox/archive/refs/heads/master.tar.gz" }
````
## 语音识别渠道索引与排序
```
FASTER_WHISPER = 0
OPENAI_WHISPER = 1
QWENASR = 2
FUNASR_CN = 3
NEMOTRON_ASR=4
FIREREDASR=5
DOLPHIN=6
Omnilingual=7
HUGGINGFACE_ASR = 8
MOSS_DIARIZE=9
VIBEVOICE_ASR = 10
Whisper_CPP = 11
OPENAI_API = 12
QWEN3ASR = 13
XIAOMIASR = 14
ZIJIE_RECOGN_MODEL = 15
ZHIPU_API = 16
GEMINI_SPEECH = 17
Faster_Whisper_XXL = 18
WHISPERX_API = 19
PARAKEET = 20
AI_302 = 21
ElevenLabs = 22
GOOGLE_SPEECH = 23
Deepgram = 24
CAMB_ASR = 25
STT_API = 26
WHISPER_NET = 27
CUSTOM_API = 28
```
## 字幕翻译渠道索引与排序
```
GOOGLE_INDEX = 0
MICROSOFT_INDEX = 1
M2M100_INDEX = 2
HYMT2_INDEX = 3
CHATGPT_INDEX = 4
DEEPSEEK_INDEX = 5
GEMINI_INDEX = 6
ZHIPUAI_INDEX = 7
AZUREGPT_INDEX = 8
LOCALLLM_INDEX = 9
OPENROUTER_INDEX = 10
SILICONFLOW_INDEX = 11
AI302_INDEX = 12
QWENMT_INDEX = 13
ZIJIE_INDEX = 14
XIAOMI_INDEX = 15
MINIMAX_INDEX = 16
CAMB_INDEX = 17
DEEPL_INDEX = 18
DEEPLX_INDEX = 19
BAIDU_INDEX = 20
ALI_INDEX = 21
LIBRE_INDEX = 22
TENCENT_INDEX = 23
TRANSAPI_INDEX = 24
LITELLM_INDEX = 25
```
## 文字配音渠道索引与排序
```
# 推荐
EDGE_TTS = 0
# 本地内置
QWEN3LOCAL_TTS = 1
F5_TTS = 2
OMNIVOICE_TTS = 3
CONFUCIUS_TTS = 4
MOSS_TTS = 5
ZIPVOICE_TTS = 6
PIPER_TTS = 7
CHATTERBOX_TTS = 8
Supertonic_TTS = 9
VITSCNEN_TTS = 10
HIGGS_AUDIO_TTS = 11
# 本地 API
INDEX_TTS = 12
GPTSOVITS_TTS = 13
COSYVOICE_TTS = 14
VOXCPM_TTS = 15
FIRERED3_TTS = 16
# 云 API
DOUBAO2_TTS = 17
QWEN_TTS = 18
XIAOMI_TTS = 19
GLM_TTS = 20
MINIMAXI_TTS = 21
# 海外 API
OPENAI_TTS = 22
GEMINI_TTS = 23
ELEVENLABS_TTS = 24
XAI_TTS = 25
G_TTS = 26
# 本地 API
CHATTTS = 27
SPARK_TTS = 28
KOKORO_TTS = 29
FISHTTS = 30
#不推荐
CLONE_VOICE_TTS = 31
AZURE_TTS = 32
AI302_TTS = 33
CAMB_TTS = 34
TTS_API = 35
```
::: danger 防骗声明
- 本软件是一款基于 [GPL-V3 协议](https://www.gnu.org/licenses/gpl-3.0.html) 发布的开源软件。您可以从 [官方GitHub仓库](https://github.com/jianchang512/pyvideotrans) 或 [文档站](/downpackage) 下载和使用源代码或Windows预打包版。
- 【未授权商业销售行为】本开发者未授权任何实体或个人销售本软件（例如淘宝、闲鱼、拼多多等）。任何通过付费渠道获取本软件的行为均与开发者无关，开发者未授权也未从中受益，对此不承担任何责任，如果你是花钱购买并且想退款，请自行找卖家退钱或平台投诉，勿找开发者。
- 【无需登录或认证】下载预打包版或部署源码后就直接可用，无需登录或卡密验证，凡是需要此类操作才可使用的，都不是官方原版，请知悉。
- 【关于第三方API】第三方 API 需您自行提供账户和密钥（仅本地存储），相关费用你需自行在第三方平台充值或购买，与开发者无关，开发者仅在软件中提供API对接的技术规范。
[查看软件使用和许可协议了解更多...](/law)
:::