# 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 相关的代码生成、功能重构、问题解答时，您**必须**严格遵守以下架构设计与开发规范：

---

## AI Agent 与大模型阅读指引

### 1. 项目技术栈与核心定位
*   **核心技术栈**：Python 3.10+, PySide6 (Qt for Python), C++ 库。
*   **依赖管理**：采用 `uv` 包管理器。生成的代码或安装指令应优先使用 `uv run` 和 `uv sync`。
*   **架构设计**：基于 PySide6 的 `QThread` 与 Python 的 `queue.Queue` 构建的多线程、多队列异步流水线。
*   **进程隔离**：AI 模型（ASR 识别、本地 TTS 推理）一律在由 `GlobalProcessManager` 管理的独立子进程中执行，以防止 PyTorch/CTranslate2 的底层 C++ 崩溃导致主 GUI 闪退。

### 2. 代码生成与重构红线
当为 pyVideoTrans 生成代码、新增通道或重构功能时，您必须遵守以下规则：
*   **严格使用数据类（Dataclasses）**：所有配置和任务传递的数据结构必须继承或采用 `TaskCfgBase` 体系（例如 `TaskCfgVTT`、`SrtItem`、`SignMsg`）。
*   **禁止在 Worker 线程中直接操作 UI**：后台 Worker 线程（继承自 `BaseWorker`）**绝对不能**直接修改任何 Qt 主界面控件。必须通过调用 `BaseCon.signal(**kwargs)` 将状态发送至 `SignalHub` 单例，由其通过 Qt 的 `QueuedConnection` 安全分发给 UI 线程。
*   **动态懒加载规范**：所有新增的翻译、识别、配音渠道必须在 `videotrans/__init__.py` 中通过 `ChannelProvider` 进行注册，并在运行时通过 `get_class()` 动态加载。禁止在模块顶部导入耗时或依赖复杂的第三方库。
*   **跨平台路径安全**：使用 `os.PathLike` 或安全字符串进行路径操作。由于 Windows CMD 命令行有物理路径长度限制，请优先使用 `os.path.normpath` 规范路径，避免硬编码斜杠。

### 3. 核心概念与源码模块映射 (Semantic Mapping)
为了在向量检索（RAG）时获得更高的匹配精度，请牢记以下映射关系：
*   `ASR` / `STT` / `语音识别` ──> 对应 `videotrans/recognition` 目录（`BaseRecogn` 子类）
*   `STS` / `Translation` / `字幕翻译` ──> 对应 `videotrans/translator` 目录（`BaseTrans` 子类）
*   `TTS` / `Dubbing` / `语音配音` ──> 对应 `videotrans/tts` 目录（`BaseTTS` 子类）
*   `Alignment` / `Sync` / `音画对齐` ──> 对应 `videotrans/task/_rate.py`（`SpeedRate` 类）
*   `Core Pipeline` / `主流水线` ──> 对应 `videotrans/task/trans_create.py`（`TransCreate` 类）

### 4. 外部参考链接引用
*   若用户询问某个具体渠道的配置细节（例如如何配置特定 API 或本地部署），请检索 **官方参考文档链接**，并直接向用户提供对应的官方文档 URL。


---


# pyVideoTrans 核心知识库（第一部分）

## 1. 项目概况与身份定义

### 1.1 软件基础定义
*   **软件名称**：pyVideoTrans
*   **最新版本**：`{$version}`
*   **核心定位**：一款开源、免费、跨平台的视频翻译与配音工具。
*   **核心功能**：
    1.  **自动化视频翻译**：将视频/音频从一种语言自动翻译为另一种语言，全流程包含语音识别（ASR）、字幕翻译、语音合成（TTS/配音）及音画同步。
    2.  **语音转录（ASR）**：批量将音频或视频文件中的人声转录为带时间轴的 SRT 字幕或纯文本 TXT。
    3.  **语音合成（TTS）**：批量将文本或 SRT 字幕文件转换为自然流畅的语音音频。
    4.  **工具集**：内置人声与背景声分离、视频硬字幕提取（GVS）、字幕合并、音视频格式转换、视频裁剪等实用工具。
*   **适用平台**：
    *   **Windows**：提供预打包绿色版（`.exe`），开箱即用（支持 Win10/Win11，不支持 Win7）。
    *   **macOS / Linux**：支持通过源码部署（基于 Python 3.10+ 和 `uv` 包管理器）。

### 1.2 左侧功能面板模块划分
*   **翻译视频和音频**：智能识别转录音视频中的说话声，生成源语言字幕文件，再翻译为目标语言字幕文件，接着进行配音，最后将新的音频与字幕合成到原视频中。
*   **批量语音转字幕**：批量将视频或音频文件中的人类说话声，转录为带时间轴的 SRT 字幕文件。
*   **批量为字幕配音**：利用多种 TTS 渠道，为文本或 SRT 字幕文件生成配音音频。
*   **批量翻译 srt 字幕**：支持批量翻译 SRT 字幕文件，保留原有时间码和格式，并提供多种双语字幕样式。
*   **音视频字幕合并**：将指定的音频、视频、字幕三者合并为一个视频文件。

---

## 2. 安装与环境配置

### 2.1 Windows 用户（预打包版）
*   **下载说明**：官方提供 `.7z` 压缩包。
    *   **完整版压缩包**（约 2.6GB）：包含完整运行依赖及 `ffmpeg.exe` / `ffprobe.exe`。
    *   **补丁包**（约 260MB）：仅包含更新文件，需覆盖到完整版目录下使用。
*   **解压与运行要求**：
    *   必须解压到**非系统盘**（如 D 盘或 E 盘）。
    *   解压路径**强烈建议不包含中文、空格或特殊符号**（推荐形如 `D:\pyVideoTrans`）。
    *   **禁止**在 `C:\Program Files` 或 `C:\Windows` 等需要管理员或特殊权限的目录中解压。
    *   **禁止**直接在压缩包内双击 `sp.exe` 运行，必须先解压。
*   **启动方式**：进入解压后的主文件夹，双击 `sp.exe`。首次启动由于需要加载较多模块，请耐心等待 5 秒至 2 分钟。

### 2.2 macOS / Linux / Windows 用户（源码部署）
*   **前置依赖**：
    *   **FFmpeg**：系统必须安装并正确配置环境变量（macOS: `brew install ffmpeg`，Linux: `apt install ffmpeg`）。
    *   **Python**：建议使用 Python 3.10 版本。
    *   **uv**：推荐使用 `uv` 进行快速便捷的包管理。
*   **部署步骤**：
    1.  克隆仓库：
        ```bash
        git clone https://github.com/jianchang512/pyvideotrans
        cd pyvideotrans
        ```
    2.  同步并安装基础依赖：
        ```bash
        uv sync
        ```
        *注：默认不安装 `qwen-tts`、`qwen-asr`、`moss-tts`、`chatterbox` 本地渠道。*
    3.  安装可选本地渠道依赖（根据需要选择）：
        *   **全部安装可选渠道**：
            ```bash
            uv sync --all-extras
            ```
        *   **单独安装特定渠道**：
            *   `qwen-tts` 渠道：`uv sync --extra qwentts`
            *   `qwen-asr` 渠道：`uv sync --extra qwenasr`
            *   `moss-tts` 渠道：`uv sync --extra mosstts`
            *   `chatterbox` 渠道：`uv sync --extra chatterbox`
    4.  可选依赖项目声明：
        ```toml
        [project.optional-dependencies]
        dotnet = [
            "pythonnet>=3.0.1",
        ]
        qwentts = [
            "qwen-tts",
        ]
        qwenasr = [
            "qwen-asr",
        ]
        mosstts = [
            "pynini",
            "importlib-resources",
            "WeTextProcessing",
        ]
        chatterbox = [
            "chatterbox-tts"
        ]
        ```
    5.  启动运行：
        ```bash
        uv run sp.py
        ```

### 2.3 GPU 加速配置（CUDA）
*   **必要性说明**：本地语音识别（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` 目录。

---

## 3. 目录结构说明

```text
├── sp.exe / sp.py              # 主程序入口文件
├── models/                     # 存放本地 AI 离线模型文件（Whisper, Faster-Whisper, VAD 等）
├── ffmpeg/                     # 存放 FFmpeg 核心二进制文件（Windows 打包版专用）
├── output/                     # 批量转录、配音、翻译 SRT 字幕等独立功能的默认输出保存目录
├── tmp/                        # 临时工作文件目录
│   ├── _temp/                  # 进程级临时目录（音视频分离、切片、缓存文件等）
│   └── translate_cache/        # 翻译 MD5 缓存目录
├── videotrans/                 # 软件核心源码目录
│   ├── configure/              # 配置模块、常量与任务基类
│   ├── task/                   # 核心多线程任务控制逻辑（包括音画对齐引擎 _rate.py）
│   ├── recognition/            # ASR 语音识别各渠道实现模块
│   ├── tts/                    # TTS 语音合成配音各渠道实现模块
│   ├── translator/             # 字幕翻译各渠道实现模块
│   └── prompts/                # 系统提示词目录
│       ├── srt/                # 开启“发送完整字幕”时的各 AI 渠道提示词模板
│       ├── text/               # 未开启“发送完整字幕”（按行翻译）时的提示词模板
│       ├── recharge/recharge-llm.txt  # LLM 重新断句使用的系统提示词
│       └── recogn/gemini_recogn.txt   # Gemini 语音识别使用的提示词
└── f5-tts/                     # F5-TTS等支持声音克隆渠道的本地参考音频存放目录
```

---

## 4. 核心功能工作流：视频翻译

视频翻译是本软件最核心的功能，默认启动界面即为“翻译视频或音频”。

### 4.1 基本原理
通过自动化流水线将视频中的语言重构：
```text
【提取原始音视频】 ──> 【语音转录 (ASR)】 ──> 【字幕翻译 (STS)】 ──> 【语音合成 (TTS)】 ──> 【音画对齐与合成】
```
*   **可处理范围**：任何包含清晰人类语音的音视频（无论视频本身是否有字幕）。
*   **无法处理范围**：仅有背景音乐/画面但无人声说话的视频。
*   *注意：本功能无法直接提取或抹除视频画面已经内嵌的硬字幕。如需提取硬字幕，请使用基于智谱 AI 的硬字幕提取工具 [本地离线提取视频硬字幕](https://pyvideotrans.com/ocrsp)。*

---

### 4.2 主界面功能及参数详解

#### 第 1 行：选择要翻译的视频
*   **`选择音频或视频`**：点击选择需要翻译的文件。支持按住 `Ctrl` 键多选。
    *   *支持的视频格式*：`mp4/mov/avi/mkv/webm/mpeg/ogg/mts/ts/wmv`
    *   *支持的音频格式*：`wav/mp3/m4a/flac/aac/wma`
*   **`文件夹`**：勾选此项可以一次性导入整个文件夹内的所有音视频进行批量处理。
*   **`清理已生成`**：若需要对同一个视频重新识别和翻译（不使用历史缓存），请勾选此项。
*   **`输出到..`**：默认将翻译后的文件保存到原视频目录下的 `_video_out` 文件夹。点击此按钮可自定义输出目录。
*   **`仅输出mp4`**：选中后，最终输出中只保留合并后的 MP4 视频，中途产生的临时音频、字幕文件都会被自动清理。
*   **`完成后关机`**：所有排队任务处理完毕后，自动关闭计算机，适合夜间大批量处理。

#### 第 2 行：语音识别渠道 (ASR)
用于将音视频中的人声精准转录为带时间轴的字幕。
*   **`faster-whisper(本地)`**：本地离线运行（首次运行会自动在线下载模型，国内无法下载可手动导入）。速度与准确度平衡较好。
    *   提供多种尺寸模型，最小为 `tiny`（速度极快但准确度低，不推荐），效果最好的是 `large-v3`（推荐）。
    *   以 `.en` 结尾和以 `distil-` 开头的模型仅适用于识别英语发音。
*   **`openai-whisper(本地)`**：类似于 faster-whisper，运行速度稍慢，但部分语境下准确度略高，同样推荐使用 `large-v3` 模型。
*   **`qwen-asr(本地)`**：阿里巴巴开源的本地识别模型，对中文识别和口语化支持极佳，首次运行同样需在线下载。
*   **`二次识别`**：在配音结束并选择“嵌入单字幕”时可用。它会针对合成后的新配音音频再次进行转录，生成更为精简贴合的字幕，确保字幕与配音绝对对齐。
*   **`默认断句` / `LLM重新断句`**：
    *   `LLM重新断句`：在 ASR 识别出文本后，将字幕文本发送给大模型（如 DeepSeek 或 OpenAI ChatGPT），让其修正错别字、理顺语气并重新切分长文本。
    *   *配置路径*：可在 `菜单 -> 工具 -> 高级选项 -> 通用 -> LLM断句模型` 中指定模型。提示词存放于 `软件目录/videotrans/prompts/recharge/recharge-llm.txt`。
    *   *注意*：使用克隆原音色（`clone`）配音时，不建议开启 LLM 重新断句。

#### 第 3 行：翻译渠道 (STS)
将转录得到的原始字幕翻译为目标语言字幕。
*   **免费传统翻译**：`Google翻译`（需本地代理环境）、`微软翻译`（无需代理）、`M2M100本地翻译`、`DeepLX`（需自行部署接口）。
*   **收费传统翻译**：`百度翻译`、`腾讯翻译`、`阿里机器翻译`、`DeepL`。
*   **AI 智能翻译**：`OpenAI ChatGPT`、`Gemini`、`DeepSeek`、`智谱AI`、`硅基流动`、`302.AI` 等（需自备 API Key，并在 `菜单 -> 翻译设置 -> 对应渠道面板` 中配置）。
*   **兼容AI/本地模型**：支持对接本地部署的 LLM（如 Ollama 接口），将 API 地址配置到 `菜单 -> 翻译设置 -> 本地大模型设置` 即可。
*   **发音语言**：视频内人物实际说话的原始语言，必须正确选择，不能过度依赖 Auto 检测。
*   **目标语言**：希望将音视频翻译并配音成的目标语言。
*   **翻译术语表**：在进行 AI 翻译时，可附带特定行业或专有名词的术语表。
*   **发送完整字幕**：在使用 AI 翻译渠道时，建议勾选。勾选后会携带行号和时间轴一并发送给 AI，使其能结合上下文进行翻译（使用 `prompts/srt` 提示词模板）；未勾选则按纯文本逐行翻译（使用 `prompts/text` 提示词模板）。

#### 第 4 行：配音渠道 (TTS)
将翻译好的目标语言字幕合成为语音音频。
*   **免费渠道**：`Edge-TTS`（微软免费接口，无需申请 Key，开箱即用，但高并发易被限流）。
*   **配音角色与试听**：选择目标语言和配音渠道后，可在下拉框选择不同的发音人，点击“试听配音”可以预览人声效果。
*   **克隆角色（`clone`）**：在角色下拉框中选中 `clone`，代表将使用原始视频中该说话人的原音色进行配音。

#### 第 5 行：同步对齐与字幕样式
处理因语言翻译后（如中文翻译为英文，英文音节多、时间长）导致的音画不同步问题。
*   **`音频加速`**：若配音时长长于原字幕区间，自动加速播放音频以强行匹配原时长，避免声音重叠。
*   **`视频慢速`**：若配音长于视频片段，放慢该片段的视频播放速度以匹配配音时长。*（注意：此功能较耗时，且会生成大量中间临时视频，因降低重编码质量损失，输出体积会显著增大）*。
*   **`不嵌入字幕`**：最终视频只替换配音，不显示任何字幕。
*   **`嵌入硬字幕`**：将字幕永久烧录进视频画面，无法关闭。
*   **`嵌入软字幕`**：将字幕作为独立轨道封装进 MP4 文件，播放器中可自由开启或关闭。
*   **`(双)`**：生成双语字幕，画面同时显示原始语言和目标语言。
*   **`网络代理`**：国内访问 Google、OpenAI、Gemini 等服务时，在此处填写代理端口，格式如 `http://127.0.0.1:7890`。不使用代理请务必留空。

#### 第 6 行：开始执行与 GPU 加速
*   **`CUDA加速`**：若您的电脑配备 NVIDIA 显卡且已配置 CUDA 环境，**请务必勾选此项**，可实现数倍至数十倍的识别与推理加速。
*   *多卡配置*：若有多张 NVIDIA 显卡，可在 `菜单 -> 工具 -> 高级选项 -> 通用设置 -> 多卡模式` 开启。
*   *串行处理控制*：批量翻译时默认并行，若想彻底完成一个视频再进行下一个，可在 `高级选项 -> 通用设置 -> 批量翻译视频时每批数量` 设为 `1`。

#### 第 7 行：进度控制与输出
*   任务执行时底部会显示实时进度条。
*   任务完成后，**点击底部进度条区域**可直接打开对应的输出文件夹，获取最终合并的视频及产生的 ASR/译文 SRT 文件。

---

### 4.3 设置更多参数（精细化控制面板）

点击主界面上的“**设置更多参数...**”可以展开以下精细化控制项：

*   **`识别说话人`**：识别并区分视频中不同的说话角色。右侧数字代表预期识别的说话人数量（设为 `0` 代表不限制，由模型自适应）。高级选项中可切换后端模型。
*   **`配音语速` / `音量+` / `音调+`**：
    *   语速：默认为 `0`。填写 `50` 代表加快 50%，`-50` 代表放慢 50%。
    *   音量：默认为 `0`。填写 `50` 代表增大 50%，`-50` 代表降低 50%。
    *   音调：默认为 `0`。填写 `20` 代表调高 20Hz 声音变尖锐，`-20` 代表调低 20Hz 声音变低沉。
*   **`语音阈值`**：表示音频片段被识别为语音的最低概率，默认 `0.5`。数值越小越灵敏，但容易将环境噪音误判为人声。
*   **`最短语音持续毫秒数`**：限制单个语音切片的最低时长。若使用声音克隆（`clone`），建议保持在 `>= 3000` 毫秒。
*   **`最长语音持续秒数`**：限制单个语音切片的最大长度，超时强制分割。默认 `6` 秒，建议不要大于 `30` 秒。
*   **`静音分割持续毫秒数`**：人声结束时，静音时长达到该设定值时进行切分，默认 `500` 毫秒。
*   **`传统翻译渠道每批字幕行数`**：非 AI 翻译时，单次发送给接口的字幕行数。
*   **`AI翻译渠道每批字幕行数`**：AI 翻译时，单次发送给大模型的字幕行数。
*   **`翻译后暂停秒` / `配音后暂停秒`**：每次调用接口后强制等待的秒数，用于防止触发 API 限流。
*   **`中日韩单行字符` / `其他语言单行字符`**：视频字幕换行限制。超出此字符数限制，字幕会自动换行显示。
*   **`修改硬字幕样式`**：点击弹出硬字幕样式编辑器，可自定义字体、颜色、大小、边框等。
*   **`分离人声背景声`**：使用模型将视频中的人声和背景伴奏/噪音彻底分离（纯 CPU 计算，速度较慢）。
*   **`嵌入背景`**：翻译配音完成后，将分离出来的背景音重新混音合成回最终视频中。
*   **`循环背景音`**：若分离出的背景音短于最终视频长度，勾选此项可循环播放背景音，不勾选则在结束后保持静音。
*   **`背景音量`**：重新嵌入时的背景音量比例，默认 `0.8`。
*   **`额外添加背景音频`**：支持在合成时额外混入一段本地音频（如背景 BGM）。
*   **`降噪`**：尝试清除音频中的环境噪音。若同时勾选了“分离人声背景声”，则仅对分离出的人声部分进行降噪。
*   **`恢复标点`**：语音识别完成后，尝试利用模型为字幕文本自动添加标点符号。

---


---

# pyVideoTrans 核心知识库（第二部分）

## 5. 原音色克隆（Voice Cloning）与多角色配音

**原音色克隆**是指：使用原始视频中说话人的音色生成目标语言的配音。例如将一段中文视频翻译为英文，生成的新英文配音听起来依然是原说话人的声音。

### 5.1 克隆的基本原理
1. 提取要配音的字幕数据，循环每一条字幕。
2. 根据该字幕的起始与结束时间，从原始视频中截取对应的音频片段，作为配音的**参考音频（Reference Audio）**。
3. 将该参考音频与翻译后的目标字幕文本一并发送给支持声音克隆的 TTS 引擎进行配音合成。

### 5.2 支持音色克隆的渠道与特点
*   **OmniVoice (本地API)**：推荐，支持克隆几乎所有本软件支持的语言。在短音频参考下稳定性较好。
*   **Qwen-TTS (本地内置)**：推荐，支持中、英、日、韩等 10 多种常见语言的克隆。
*   **GPT-SoVITS (本地API)**：推荐，中英日韩克隆效果出色。
*   **F5-TTS (本地API)**：推荐，支持中、英克隆。
*   **Index-TTS (本地API)**：推荐，支持中、英克隆。
*   **VoxCPM-TTS (本地API)**：支持 10 多种语言克隆。
*   **Chatterbox (本地内置)**：本地运行，支持 10 多种语言克隆。
*   **CosyVoice (本地API)**：支持中英日韩等 10 多种常见语言，音色表现自然。
*   **Spark-TTS (本地API) / Dia-TTS (本地API)**：仅支持英语克隆。
*   **clone-voice (本地API)**：支持 10 多种语言，因项目已停止维护，不推荐优先使用。

### 5.3 最佳克隆配置方案（防止报错或杂音）
声音克隆对字幕时长及参考音频质量有极高要求，建议在主界面和高级选项中进行如下配置：
1.  **禁止使用“LLM重新断句”**：重新划分时间轴会导致截取的参考音频与说话时间错位。
2.  **强制控制字幕时长在 3-10 秒之间**：
    *   参考音频短于 3 秒，克隆模型易报错或生成沙沙的杂音。
    *   参考音频长于 10 秒，某些克隆渠道会发生内存溢出或拒绝服务。
    *   *设置方法*：进入 `菜单 -> 工具 -> 高级选项 -> 语音识别参数`，将**`最长语音持续秒数`**限制在 `6` 至 `10`，**`最短语音持续毫秒`**限制在 `3000` 至 `4000`（即 3-4 秒），并勾选**`合并过短字幕到邻近`**以及**`合并过短字幕`**。
3.  **翻译渠道推荐**：使用 DeepSeek 或 OpenAI 等大模型渠道，并勾选“发送完整字幕”以保持语义。
4.  **人声背景分离**：点击主界面“设置更多参数”，勾选**`分离人声背景声`**。分离后的纯净人声不含背景噪声，能使克隆出的音质大幅提升。
5.  **ASR 渠道推荐**：中文推荐使用 `豆包语音大模型极速版` / `Qwen-ASR(本地)`；英文推荐 `faster-whisper(本地)` 加 `large-v3` 模型。

### 5.4 使用自定义参考音频（不克隆原视频，克隆指定声音）
如果不希望克隆视频原声，而是想用特定的本地声音（如您自己的声音或特定声优的声音）进行全视频配音：
1.  **录制/准备参考音频**：准备一段 `5-10s` 的 `wav` 格式音频。确保音频内是单一人声，无 background 伴奏、无明显噪音、且开头和结尾没有多余的静音。
2.  **放置音频文件**：将该音频重命名为简短名字（如 `myaudio1.wav`），复制到软件根目录下的 `f5-tts` 文件夹内。
    *   *特例*：**GPT-SoVITS** 渠道的参考音频必须存放在 **GPT-SoVITS 软件本身的根目录下**，而非 pyVideoTrans 的 `f5-tts` 文件夹。
3.  **注册参考音频**：打开软件顶部 `菜单 -> TTS设置 -> 设置参考音频`。在文本框内新起一行，按照格式 `文件名.wav#音频内说话的文字内容` 填入并保存。
    *   *示例*：`myaudio1.wav#你说四大皆空，却为何，紧闭双眼，若你睁开眼睛看看我，我不相信你，两眼空空。`
4.  **选择使用**：保存后，回到软件主界面。在“配音角色”下拉菜单中，便会出现并可选择 `myaudio1.wav`，即可将其作为全视频的音色克隆基准。
    *   *注意*：确保系统已开启文件扩展名显示，避免命名为 `myaudio1.wav.wav` 的错误。

---

## 6. 使用已有的外部 SRT 字幕与音视频素材

如何使用自己已经翻译、校对完毕的外部字幕及高音质伴奏人声，而不是让软件自动生成？

### 6.1 前置准备
*   **规范文件名**：由于底层开源工具对中日韩等非拉丁字符、空格、特殊符号兼容性较差，建议将原始视频名称修改为简单的英文字母、数字、下划线组合（例如 `myhomework.mp4`）。
*   **开启系统扩展名显示**：
    *   *Win10*：打开任意文件夹，点击顶部“查看”，勾选“文件扩展名”。
    *   *Win11*：打开任意文件夹，点击顶部“查看” -> “显示” -> 勾选“文件扩展名”。

### 6.2 导入已有 SRT 字幕的具体步骤
假设视频文件名为 `myhomework.mp4`，目标是从英文翻译至中文。
1.  在视频文件所在的同级目录下，创建一个名为 `_video_out` 的文件夹。
2.  进入 `_video_out` 文件夹，创建一个**视频同名且带格式后缀**的子文件夹，命名为 `myhomework-mp4`。
    *   *注意*：v3.87 以前版本不含格式后缀（即直接命名为 `myhomework`），**v3.87 及以后版本必须带有后缀**，格式为 `[文件名]-[视频格式]`（例如 `myhomework-mp4` 或 `video1-avi`），以防止同名但不同格式的视频缓存冲突。
3.  将您准备好的两种语言字幕文件复制到 `myhomework-mp4` 子文件夹内，并重命名为标准的语言代码：
    *   源语言字幕（英文）重命名为：`en.srt`
    *   目标语言字幕（中文）重命名为：`zh-cn.srt`
4.  回到软件主界面，导入该视频并执行翻译，软件在检测到 `_video_out` 内的对应字幕后，将跳过 ASR 和翻译阶段，直接进入配音与合成阶段。

### 6.3 导入外部已分离的人声和背景伴奏（免去软件内置的缓慢分离）
由于软件内置的 UVR-onnx 分离人声采用纯 CPU 计算，速度极慢。建议使用专业第三方工具（如 [UVR5-GUI](https://github.com/Anjok07/ultimatevocalremovergui/releases)）在 GPU 加速下进行人声与伴奏的分离：
1.  使用第三方工具将音频分离为无背景音的人声（Vocal）和无干声的伴奏（Instrumental）。输出格式必须为 `wav`。
2.  将分离出来的人声文件重命名为 `vocal.wav`，背景伴奏文件重命名为 `instrument.wav`。
3.  将这两个文件复制到上述的 `_video_out/myhomework-mp4/` 文件夹内。
4.  软件在处理该视频时将直接读取这两个文件，人声识别率会大幅提高，且省去了繁重的人声分离耗时。

---

## 7. 视频翻译的音画同步对齐引擎（SpeedRate）

由于不同语言在表达相同意思时句子的音节数和语法结构不同，配音后的时长必定会发生变化（如中文的“你好”，英文配音为“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`。
*   **两者均不启用**：按原有字幕时间轴强行拼接音频片段，差异时间以静音填充，可能会造成声音阶段性重叠或断层。

---

## 8. ASR 语音识别断句深度优化方案

语音识别（ASR）的断句质量直接决定了后续翻译的顺畅度以及配音的长短稳定性。

### 8.1 优化步骤与最佳参数配置
1.  **首选最适模型**：
    *   *中文视频*：首选 `字节语音大模型极速版`、本地的 `Qwen-ASR(本地)` 或 `阿里FunASR(本地)`（配 paraformer-zh）。
    *   *其他语言视频*：首选 `openai-whisper(本地)` / `faster-whisper(本地)` 并搭配 `large-v3` 尺寸模型，或使用付费的 `OpenAI在线识别API`。
    *   *日语视频*：推荐本地 `Huggingface_ASR` 渠道下部署的 `reazon-research/japanese-wav2vec2-large-rs35kh`。
2.  **精确调节 VAD 与断句参数**：
    进入 `菜单 -> 工具 -> 高级选项 -> 语音识别参数` 进行微调：
    *   **`最短持续时间/毫秒`**：设为 `1000`（限制单条字幕时长不低于 1 秒）。
    *   **`最长语音持续时间秒`**：设为 `3` 到 `5`（防止长篇大论不换行）。
    *   **`静音分割持续毫秒`**：设为 `140` 至 `600`。该数值越小，切分出的字幕碎片越多；数值越大，字幕越趋于长句。
    *   **`合并过短字幕到邻近`**：如果配音时没有使用 `clone` 克隆音色，建议**取消勾选**该项，使字幕更精简；若使用了 `clone` 角色，则**必须勾选**该项。
3.  **开启二次识别**：
    在主界面右上角勾选“二次识别”。在视频配音完成后，会针对新合成的配音文件进行二次 ASR，生成时间轴极精准且不超出屏幕限制的短字幕。
4.  **剔除背景音干扰**：
    在主界面勾选“降噪”或在更多参数中勾选“分离人声背景声”，将干净的人声干声送入 ASR 识别，可以完全避免背景 BGM 导致的断句混乱或幻听。
5.  **针对 faster-whisper 渠道的调整**：
    如果使用的是本地 faster-whisper 渠道，且没有声音克隆需求，可以尝试在高级选项中**取消勾选**`Whisper预分割音频?`，有时其原生断句效果会比预分割更优。

---

## 9. 菜单高级选项（Advanced Options）核心参数详解

通过主界面顶部 `菜单 -> 工具/选项 -> 高级选项` 进入，此处的配置会全局影响软件的行为与资源消耗。

### 9.1 【通用设置】
*   **`软件界面语言`**：修改界面显示语言，修改后需重启软件生效。
*   **`单视频交互翻译暂停倒计时`**：单视频交互模式下，各阶段弹出编辑框时的停留倒计时（秒）。设为 `0` 将直接跳过编辑弹窗，设为 `-1` 则无限期暂停等待人工点击。
*   **`独立功能输出目录`**：批量转录、批量配音、批量翻译字幕等独立功能面板处理完后的输出保存目录（默认软件安装下的 `output`）。
*   **`失败后重试次数`**：网络不稳定或 API 限流时，底层重试的上限次数。
*   **`LLM重新断句每批字幕行数`**：大模型断句时单词发送的字幕数量，默认 `20`。数值越大语义连贯性越好，但需注意大模型单次输出 token 限制。
*   **`LLM重新断句所用AI渠道`**：可选 `OpenAI-ChatGPT` 或 `DeepSeek` 渠道。
*   **`禁用桌面通知`**：勾选后，任务成功或失败时不再发送系统弹窗通知。
*   **`批量翻译视频时每批数量`**：同时处理的任务并发数，设为 `0` 代表无限制，设为 `1` 代表强制串行（完全做好一个再做下一个，推荐低显存用户）。
*   **`主界面显示所有参数?`**：勾选后，主界面默认展开所有原本被隐藏的“更多参数”。
*   **`CPU同时任务数[重启生效]`**：最大 CPU 任务并发数，过大易导致内存溢出。
*   **`GPU同时任务数[重启生效]`**：GPU 密集型任务（ASR、本地 TTS）的并发数。除非显存极高（>24G）或多卡，否则**建议设为 1**，防止显存崩溃。
*   **`多显卡模式[重启生效]`**：若系统有多张英伟达显卡，勾选此项可实现显卡间负载均衡。

### 9.2 【视频输出控制】
*   **`视频输出质量控制`**：压制视频时的 CRF 损失率。默认 `23`。设为 `0` 为无损（但最终视频文件体积会极大），设为 `51` 为质量极差、文件极小。推荐范围 `18-25`。
*   **`输出视频压缩率`**：对应 FFmpeg 的 preset 参数。可选：`ultrafast`, `superfast`, `veryfast`, `faster`, `fast`, `medium`, `slow`, `slower`, `veryslow`。压缩率越慢（slow），相同画质下文件体积越小，但重编码耗时越长。
*   **`264/265编码`**：采用 `libx264` 编码或 `libx265` 编码。`264` 兼容性最好，`265` 在相同画质下体积更小、清晰度更高。
*   **`可变帧率vfr/固定帧率cfr`**：在对视频进行慢速拉伸对齐时，可变帧率（VFR）表现通常更好。
*   **`强制软编码视频?`**：勾选后，强制 FFmpeg 使用 CPU 软解压和压制。速度慢，但在硬件兼容性出错时（如 N 卡驱动崩溃）是有效的备用手段。
*   **`视频合成cuda硬解码`**：合成阶段强制开启 CUDA 显卡解码加速，可大幅提升合并速度，但在低端卡上易出错。
*   **`自定义ffmpeg命令参数`**：高级用户专用。将自定义参数追加到 FFmpeg 输出命令前，例如：`-bf 7 -b_ref_mode middle`。

### 9.3 【语音识别参数】
*   **`选择VAD`**：选择静音切分所用的 VAD（语音活动检测）模型，如 `ten-vad`（默认，语义分段更佳）或 `silero`。
*   **`非语音阈值`**：减小此值能有效减少 ASR 模型在无声段落中产生的幻觉文字，但可能会造成轻微漏字。
*   **`合并过短字幕到邻近`**：勾选后，时长低于阈值的字幕会自动合并到前后相邻的时间轴。
*   **`Whisper预分割音频?`**：开启后，会先将音频利用 VAD 切割为句子片段，再发送给 Whisper 识别。在克隆（`clone`）原音色配音时**必须选中**。
*   **`说话人分离模型`**：可选 `built` 内置模型（支持中英）、`ali_CAM`（针对中文优化）、或 `pyannote`。若使用最佳的 `pyannote` 3.1 模型，**必须**在下方填入 HuggingFace 申请的 Token，且必须先同意 pyannote 的官方授权协议（教程：`https://pvt9.com/shuohuaren`）。
*   **`计算数据类型`**：本地 ASR 推理时的数据类型。
    *   `int8`：速度极快，显存/内存开销极低，但识别精度稍有下降。
    *   `float32`：精度高，但开销极大。
    *   `float16`：最适合支持 CUDA 加速的 GPU。
*   **`识别准确度beam_size` / `best_of`**：ASR 识别采样搜索深度。可选 `1-5`。设为 `1` 最省显存且速度快，设为 `5` 准确度最高但消耗资源最多。
*   **`启用上下文感知`**：开启后，ASR 识别会参考前后文语境以提高识别精度，但较容易导致“幻觉重复”。
*   **`Gemini语音识别每批切片数`**：使用 Gemini API 进行 ASR 时，单词发送的音频切片数。

### 9.4 【字幕翻译调整】
*   **`AI翻译一次性翻译所有字幕行`**：开启此项后，不再按批次切分，而是将整个 SRT 字幕一次性扔给 AI 翻译，翻译质量和语境连贯性最好。
    *   *警告*：
        1. 必须使用支持长上下文（Large Context Window）的高阶模型（如 DeepSeek-V3/V4 或 GPT-4o）。
        2. 必须将翻译渠道设置面板中的 `max token` 设得非常大，否则长篇幅输出会被强行截断导致报错。
        3. 返回响应可能较慢，请耐心等待。
*   **`AI翻译模型温度值`**：控制翻译的创造性。默认 `1.0`，翻译字幕建议维持在 `1.0` 或设为 `0.3-0.7` 提高严谨度。

### 9.5 【字幕配音调整】
*   **`并发配音线程数`**：同时生成配音的线程数。
*   **`移除配音前后静音缓冲`**：自动剔除配音文件句首句尾多余的静音缓冲，有助于音画同步，但某些语境下结尾会略显仓促。
*   **`保留每条字幕的配音文件`**：勾选后，任务完成后不会清理临时生成的单句音频切片，便于后续微调。
*   **`文本规范化`**：配音前自动对文本中的数字、特殊符号进行发音规范化处理（例如将 “100m” 规范化为 “一百米”）。
*   **`EdgeTTS配音渠道配音并发数`**：设置 Edge-TTS 的最大并发线程数。因微软防高频刷接口限制，建议设为 `1`，并将下方`配音后暂停秒`设为 `3-5` 秒，防止被微软封禁 IP 导致 403 报错或静音。
*   **`分离背景声模型`**：选择伴奏人声分离时的具体算法模型（如 UVR-onnx 各算法）。

### 9.6 【字幕声音画面对齐】
*   **`音频加速最大倍数`**：配音强制加速的最大上限倍数，默认 `100`（即无上限限制）。
*   **`视频慢放最大倍数`**：视频慢放的上限，默认 `10` 倍，不得大于 `10`，防止画面过于卡顿。

---

---

# pyVideoTrans 核心知识库（第三部分）

## 10. 技术架构与核心数据类定义

软件在架构上将音视频翻译与配音处理抽象为 **9 个独立阶段**（`Stage`），通过五大布尔控制标志位来灵活调度、拼装流水线。

### 10.1 九个处理阶段说明
整个生命周期内，同一阶段内部的所有子任务串行处理，阶段之间支持高度的并行流转：

| 阶段 | 对应核心方法 | 阶段职责描述 |
|:---|:---|:---|
| **① 预处理** | `prepare()` | 分离视频中的无声视频流和原始音频流；进行人声伴奏分离及音频降噪；初始化缓存与输出目录。 |
| **② 语音识别** | `recogn()` | 调用 ASR 引擎将音频转录为带精确时间轴的 `SrtItem` 列表。可选恢复标点、LLM 重新断句。 |
| **③ 说话人分离**| `diariz()` | 调用分离模型（内置、阿里CAM++、pyannote），将识别出的字幕按说话人角色重新归类。 |
| **④ 字幕翻译** | `trans()` | 将源字幕通过指定渠道翻译为目标语言。支持输出单行、双语、及各种双语样式。 |
| **⑤ 语音合成** | `dubbing()` | 逐条生成配音音频切片。若启用 `clone`，将在此阶段动态裁剪原声作为参考音频进行克隆。 |
| **⑥ 音画对齐** | `align()` | 依靠 `SpeedRate` 引擎执行：配音加速、视频慢放、去除字幕静音、强行对齐等音画重构操作。 |
| **⑦ 二次识别** | `recogn2pass()` | 对合成的新配音再次进行 ASR（非双语硬字幕嵌入模式），生成字数精简、时间更贴合的字幕。 |
| **⑧ 最终合成** | `assembling()`| 利用 FFmpeg 命令行，将无声视频、配音、背景伴奏以及目标字幕压制/合并为最终 MP4/MKV。 |
| **⑨ 任务收尾** | `task_done()` | 将成品文件从缓存移动至指定输出目录，彻底清理临时切片与进程缓存，发送完成通知。 |

### 10.2 流程控制标志位设计
位于 `videotrans/task/_base.py`。软件会根据用户在界面上的配置，在初始化 `TransCreate` 任务时动态计算这五个关键控制位：
*   **`should_recogn`**：是否需要执行语音识别。若用户手动导入了已准备好的源字幕，则此项设为 `False`。
*   **`should_trans`**：是否需要进行字幕翻译。若源语言与目标语言完全一致，此项设为 `False`。
*   **`should_dubbing`**：是否需要生成配音。若配音角色选择为“不配音”，此项设为 `False`。
*   **`should_hebing`**：是否需要执行最后的视频合成。仅在非“提取字幕（tiqu）”模式下起效。
*   **`should_separate`**：是否需要进行人声伴奏的分离。由用户是否勾选该参数决定。

---

### 10.3 核心数据类 Python 定义
软件在底层依托分层继承的 `@dataclass` 体系（定义于 `videotrans/task/taskcfg.py`）来确保类型安全与统一的接口交互：

```python
import os
from typing import Union, Optional, List, Dict
from dataclasses import dataclass, asdict

class InputFile:
    """输入文件元信息数据类"""
    name: Union[os.PathLike, str] = None
    dirname: Union[os.PathLike, str] = None
    basename: str = None
    noextname: str = None
    ext: str = None
    uuid: str = None
    target_dir: Optional[str] = None

    def __getitem__(self, key): return getattr(self, key)
    def __setitem__(self, key, value): setattr(self, key, value)
    def get(self, key, default=None): return getattr(self, key, default)

    def __or__(self, other):
        if isinstance(other, dict): return asdict(self) | other
        return NotImplemented

    def __ror__(self, other):
        if isinstance(other, dict): return other | asdict(self)
        return NotImplemented

@dataclass
class SignMsg:
    """进程/线程间状态传递信号消息体"""
    type: str = "logs"
    uuid: str = ""
    text: str = ""
    
    def __getitem__(self, key): return getattr(self, key)
    def __setitem__(self, key, value): setattr(self, key, value)
    def get(self, key, default=None): return getattr(self, key, default)
    def is_stop(self): return self.type in ['end', 'stop', 'succeed', 'error']
    def is_error(self): return self.type == 'error'

@dataclass
class SrtItem:
    """单条字幕核心数据类"""
    text: str = ""
    start_time: Union[int, float] = 0   # 毫秒或秒计时的开始时间
    end_time: Union[int, float] = 0     # 结束时间
    startraw: str = ''                  # ASR 产生的原始未格式化开始时间
    endraw: str = ''                    # 原始未格式化结束时间
    line: Optional[int] = 1             # 字幕行号序号
    time: Optional[str] = ""            # SRT 格式化时间戳字符串 "00:00:01,000 --> 00:00:03,000"
    spk: Optional[str] = ""             # 说话人唯一识别 ID
    filename: Optional[str] = ""        # 对应裁剪出的音频切片文件名

    def __getitem__(self, key): return getattr(self, key)
    def __setitem__(self, key, value): setattr(self, key, value)
    def get(self, key, default=None): return getattr(self, key, default)
    def items(self):
        _names = ("line", "time", "start_time", "end_time", "startraw", "endraw", "text", "spk", "filename")
        for k in _names: yield k, getattr(self, k)
    def __iter__(self):
        return iter(("line", "time", "start_time", "end_time", "startraw", "endraw", "text", "spk", "filename"))

@dataclass
class TaskCfgBase:
    """全任务配置基类"""
    uuid: str = None
    name: Union[os.PathLike, str] = None
    dirname: Union[os.PathLike, str] = None
    noextname: str = None
    basename: str = None
    ext: str = None
    target_dir: str = None
    cache_folder: str = None
    is_cuda: bool = False
    source_language: str = None
    source_language_code: str = None
    source_sub: Union[os.PathLike, str] = None
    source_wav: Union[os.PathLike, str] = None
    source_wav_output: Union[os.PathLike, str] = None
    target_language: str = None
    target_language_code: str = None
    target_sub: Union[os.PathLike, str] = None
    target_wav: Union[os.PathLike, str] = None
    target_wav_output: Union[os.PathLike, str] = None

@dataclass
class TaskCfgSTT(TaskCfgBase):
    """ASR 语音转字幕专属配置类"""
    detect_language: str = None
    recogn_type: int = None
    model_name: str = None
    shibie_audio: Union[os.PathLike, str] = None
    remove_noise: bool = False
    enable_diariz: bool = False
    nums_diariz: int = 0
    rephrase: int = 2
    fix_punc: bool = False

@dataclass
class TaskCfgTTS(TaskCfgBase):
    """TTS 语音合成配音专属配置类"""
    tts_type: int = None
    volume: str = "+0%"
    pitch: str = "+0Hz"
    voice_rate: str = "+0%"
    voice_role: str = None
    voice_autorate: bool = False
    video_autorate: bool = False
    remove_silent_mid: bool = False
    align_sub_audio: bool = True

@dataclass
class TaskCfgSTS(TaskCfgBase):
    """字幕翻译专属配置类"""
    translate_type: int = None

@dataclass
class TaskCfgVTT(TaskCfgSTT, TaskCfgTTS, TaskCfgSTS):
    """全功能视频翻译合并配置类"""
    subtitle_language: str = None
    app_mode: str = "biaozhun"
    subtitles: str = ""
    targetdir_mp4: Union[os.PathLike, str] = None
    novoice_mp4: Union[os.PathLike, str] = None
    is_separate: bool = False
    embed_bgm: bool = True
    instrument: Union[os.PathLike, str] = None
    vocal: Union[os.PathLike, str] = None
    clear_cache: bool = False
    background_music: Union[os.PathLike, str] = None
    subtitle_type: int = 0
    only_out_mp4: bool = False
    recogn2pass: bool = False
    output_srt: int = 0
    copysrt_rawvideo: bool = False
    loop_backaudio: int = 0
    backaudio_volume: float = 0.8
```

---

## 11. 多线程异步任务处理架构

pyVideoTrans 底层采用 **"生产者-消费者"** 模型，基于多队列协作，实现高效异步流水线。

```text
                     MultVideo (生产者)
                           │
                    app_cfg.prepare_queue
                           ▼
                   WorkerPrepare (×N)
                    ┌────────┼────────┐
                    │ should_recogn ?  │
                    ▼        ▼        ▼
           regcon_queue  trans_queue  dubb_queue / assemb_queue / taskdone_queue
                │
                ▼
          WorkerRegcon (×N)
                │
         diariz_queue
                │
                ▼
          WorkerDiariz (×N)
           ┌────┼────┐
           ▼    ▼    ▼
      trans_queue  dubb_queue  assemb_queue / taskdone_queue
           │
           ▼
     WorkerTrans (×1) ────► API 接口调用 (限制并发以防封禁限流)
      ┌────┼────┐
      ▼    ▼    ▼
 dubb_queue  assemb_queue  taskdone_queue
      │
      ▼
WorkerDubb (×1) ────► API 接口调用 (限制单线程以防封封 IP)
      │
 align_queue
      │
      ▼
WorkerAlign (×1)
 ┌────┼────┐
 ▼    ▼    ▼
regcon2_queue  assemb_queue  taskdone_queue
 │
 ▼
WorkerRegcon2Pass (×1)
 ┌────┼────┐
 ▼    ▼
assemb_queue  taskdone_queue
 │
 ▼
WorkerAssemb (×N)
 │
taskdone_queue
 │
 ▼
WorkerTaskDone (×1)
 │
【终止并输出最终 MP4】
```

### 11.1 Worker 线程实例分配与动态调节策略
在启动时，软件会自动计算分配各 Worker 的并发实例数量：
*   **`WorkerTrans`（字幕翻译）与 `WorkerDubb`（配音生成）**：实例数**强制锁死为 1**。因为翻译与配音往往会调用第三方在线云 API 接口，强制单线程能够最大程度规避因高频突发并发导致的目标服务提供商 IP 封禁与 403 频率限流限制。
*   **计算/显卡密集型 Worker**（`Prepare` 预处理、`Regcon` 语音识别、`Assemb` 合成压制）：实例数根据 GPU 与物理硬件资源动态弹性计算（范围为 `1~4`）。若系统拥有单个 GPU，实例默认设为 1；若开启了多卡，实例上限将自适应扩大。

### 11.2 独立子进程池与 GlobalProcessManager
为防止本地 AI 推理模型（如 `faster-whisper`）在遇到极端视频帧或因 C++ 底层显存溢出发生硬崩溃（SegFault）直接连带导致整个 pyVideoTrans 客户端闪退，软件设计了独立子进程隔离池管理机制：
*   **双进程池划分**：`GlobalProcessManager` 在底层维护了专门的 CPU 进程池（`_executor_cpu`）与 GPU 进程池（`_executor_gpu`）。
*   **自适应最大子进程数计算**：
    *   CPU 进程数基于系统空闲内存动态核算。获取物理剩余内存后，按**每 4GB 内存分配 1 个进程**进行划分（限制在 `2~8` 之间）。
    *   GPU 进程数默认等同于系统物理显卡数量。
*   **防内存泄漏自我重启**：每个子进程的 `maxtasksperchild` 属性**强制设置为 1**，即每个子进程在被派发执行完单次 AI 运算（如一段视频的 Whisper 识别）后，进程会被主控池安全回收并重新拉起新实例，从根本上杜绝了开源 AI 推理模型长期运行导致的内存与显卡显存泄漏。

### 11.3 SignalHub 跨线程信号中心
为了消除多线程模型直接修改 Qt 主窗口控件造成的客户端死锁崩溃，pyVideoTrans 设计了统一的单例信号分发中心 `SignalHub`：
*   所有后台 Worker 的状态、百分比进度、调试日志、出错警报一律不得直接修改 UI。
*   Worker 统一通过调用 `BaseCon.signal(**kwargs)` 将状态包装为 `SignMsg`。
*   `SignalHub` 通过 Qt 的异步队列连接（`QueuedConnection`）向主窗口 `MainWindow` 抛出 `new_message`。
*   主窗口的 `WinAction` 接收到消息体后，在安全的 UI 主线程上刷新进度条、弹窗或提示。

---

## 12. 懒加载动态通道加载机制

为避免软件在运行之初一次性加载上百个依赖库（如 PyTorch、OnnxRuntime、各云厂商 SDK 等）导致启动极其缓慢甚至因系统缺少特定 DLL 直接崩溃，软件所有第三方渠道一律使用 **动态懒加载** 技术。

各功能渠道在初始化时仅作为轻量级的元信息注册在列表中。只有当用户在主界面选择该渠道并点击“开始执行”时，pyVideoTrans 才会触发动态导入。

### 12.1 渠道矩阵与对应关系表

#### ASR 语音识别（22 个渠道，注册于 `videotrans/recognition/__init__.py`）
| ID | 渠道名称 | 运行机制 | API 密钥字段 | 设置窗口类名 |
|:---|:---|:---|:---|:---|
| **0** | faster-whisper(本地) | 本地离线 CTranslate2 推理 | 无 | `faster` |
| **1** | openai-whisper(本地) | 本地 PyTorch Whisper 推理 | 无 | `openaiwhisper` |
| **2** | Qwen-ASR(本地) | 本地阿里千问 ASR | 无 | `qwenasrlocal` |
| **3** | 阿里FunASR(本地) | 本地 FunASR / paraformer | 无 | `funasr` |
| **4** | Huggingface_ASR | 动态下载 HF 模型识别 | 无 | `huggingface` |
| **5** | OpenAI语音识别API | 云端 ASR API | `chatgpt_key` | `openairecogn` |
| **6** | Gemini大模型识别 | 谷歌 Gemini 多模态识别 | `gemini_key` | `gemini-recognition` |
| **7** | 阿里百炼 Qwen3-ASR | 阿里云百炼大模型 ASR | `qwen_key` | `qwen-mt` |
| **8** | 字节语音大模型极速版 | 字节火山大模型识别 | `doubao_key` | `doubao` |
| **9** | 智谱AI GLM-ASR | 智谱 GLM 语音识别 | `zhipu_key` | `zhipu-ai` |
| **10**| Deepgram.com | Deepgram 商业接口 | `deepgram_key`| `deepgram` |
| ... | ... | ... | ... | ... |

#### STS 字幕翻译（24 个渠道，注册于 `videotrans/translator/__init__.py`）
部分常见接口配置项：
*   **`0=Google(免费)`**、**`1=微软(免费)`**、**`2=M2M100(本地)`**。
*   **`3=OpenAI ChatGPT`**、**`4=DeepSeek`**、**`5=Gemini AI`**、**`6=智谱AI`**。
*   **`10=硅基流动`**、**`14=腾讯翻译`**、**`15=百度翻译`**、**`16=DeepL`** 等。
*   *MD5 缓存机制*：`BaseTrans` 会根据“文本+原语言+目标语言+模型+地址”做 MD5 哈希。在 `TEMP_ROOT/translate_cache/` 下查找同名缓存，命中即直接返回，免除重复计费。

#### TTS 语音合成（33 个渠道，注册于 `videotrans/tts/__init__.py`）
配音渠道划分：
*   **本地内置开箱可用**：`Qwen3-TTS(本地)`、`MOSS-TTS-Nano`、`Piper`、`VITS`、`Supertonic`、`ChatterBox`。
*   **云端在线服务**：`Edge-TTS`（免费）、`豆包语音合成2.0`、`GLM-TTS`、`Elevenlabs.io`、`Azure-TTS`、`OpenAI-TTS` 等。
*   **本地部署开源生态**：`GPT-SoVITS(本地API)`、`CosyVoice(本地API)`、`F5-TTS(本地API)`、`ChatTTS`、`Fish-TTS`。

---

## 13. 系统内置提示词

大模型处理环节均通过定义精细的提示词模板进行强力约束。您可根据需要自行调整。

### 13.1 LLM 重新断句系统提示词（位于 `prompts/recharge/recharge-llm.txt`）
```text
**Role:**
You are an expert Multi-Language ASR Post-Editor. Your goal is to **losslessly repair, correct, and re-segment subtitles** from the given SRT.

---

# GOLDEN RULE — ABSOLUTE REQUIREMENTS
1. **Do NOT delete any meaningful information.**
2. **Removing meaningless fillers ("uh", "umm", "erm", “えー”, “嗯”) is allowed and does NOT violate rule #1.**
3. **All semantic content must appear in the final output. No summarizing. No shortening.**

---

# CORE TASKS
1. **Retention:** preserve all meaning.
2. **Correction:** fix ASR mistakes (typos, homophones, missing punctuation).
3. **Segmentation:** cut long text into natural sentences.
4. **Formatting:** output valid SRT wrapped in `<SRT>` and `</SRT>`.

---

# SEGMENTATION RULES (CRITICAL)
1. If an original block contains multiple sentences or is longer than {max_speech_s} seconds,
   - **split into multiple sub-lines**.
   - **Prioritize breaking sentences at punctuation marks**
2. Each SRT block must contain **ONE line only**.
3. Max line length:
   - CJK: ~25 characters
   - Latin/others: ~50 characters
4. If a sentence exceeds line limit → split visually but **not semantically harmful**.
5. The sentence segmentation results should not include sentences shorter than 1 second.


**Priority order (highest → lowest):**
1) semantic meaning
2) sentence integrity
3) visual length limit
4) timing allocation

---

# TIMING RULES
1. First sub-block start time = original start.
2. Last sub-block end time = original end.
3. Inner segments must have proportional durations based on text length.
4. Each block must be within **1s–{max_speech_s}s**.
5. Time must be strictly increasing:
   - no overlaps
   - no backward jumps
   - no duplicate timestamps

---

# LANGUAGE RULES
1. Auto-detect language (CJK, Latin, mixed).
2. Restore correct punctuation based on language habits.
3. For languages without explicit punctuation (zh/ja/ko), split based on semantic pauses.

---

# SRT OUTPUT RULES
1. Always discard original SRT numbering.
2. Rebuild numbering starting from **1**, strictly increasing.
3. Output must be:
```
<SRT>
1
00:00:00,000 --> 00:00:02,000
Text...
...
</SRT>
```
4. If any required structure is missing → regenerate internally before showing.

---

# Input SRT:
```

### 13.2 AI 字幕翻译提示词（位于 `prompts/srt` 目录，开启“发送完整字幕”时起效）
```text
# ROLE
You are a world-class "Dubbing Script Adapter" and "SRT Formatting Expert". 
Your exact objective is to translate ONLY the SRT subtitles provided inside the `<INPUT>` tags into {lang}.

# CORE CHALLENGES & PRINCIPLES
1. **DUBBING LENGTH CONSTRAINT (CRITICAL)**: The output will be used for AI Voiceover (TTS). Different languages have vastly different syllable counts. To prevent the audio from playing too fast (audio-visual desync), you MUST be **aggressively concise**. Prioritize the core meaning using the shortest, most natural and fluent spoken expression in {lang}. 


# ABSOLUTE FORMATTING RED LINES (System Crash Warnings)
1. **STRICT TRANSLATION SCOPE**: Translate ONLY the text inside `<INPUT>` into {lang}.
2. **STRICT 1-TO-1 BLOCK MAPPING (NO MERGING)**:
   - Count the blocks inside `<INPUT>`. The output MUST have the EXACT SAME number of blocks.
   - **FATAL ERROR**: NEVER merge two blocks together, even if they form a single grammatical sentence. If a sentence is chopped across Block 1 and Block 2  or more, your {lang} translation MUST be forcibly chopped across Block 1 and Block 2 or more.
   - NEVER create new blocks. NEVER delete short blocks.
3. **IMMUTABLE METADATA**:
   - Do NOT alter the Index Numbers (1, 2, 3...).
   - Do NOT alter the Timestamps (00:00:00,000 --> ...).
   - Preserve the exact blank line between blocks.
4. **SILENT EXECUTION**: 
   - Output ONLY the valid SRT format inside `<TRANSLATE_TEXT>` tags. NO conversational filler, NO "Here is the translation".

# EXAMPLE OF "FRAGMENT MAPPING & CONDENSATION"
*Source Input (Contains typo "gona", sentence unnaturally split into 2 blocks):*
1
00:00:01,000 --> 00:00:02,500
I think I'm gona

2
00:00:02,600 --> 00:00:04,000
go to the hospital right now.

*WRONG OUTPUT (Fatal Error: Merged blocks & translated too literally/long for dubbing):*
1
00:00:01,000 --> 00:00:02,500
[Long, literal translation of the ENTIRE sentence in {lang} merged into Block 1]
2
00:00:02,600 --> 00:00:04,000
[Left empty, deleted, or repeated because Block 1 absorbed it]

*CORRECT OUTPUT (Perfect: Understood meaning, extremely concise, perfectly mapped fragments):*
1
00:00:01,000 --> 00:00:02,500
[Extremely concise translation of fragment "I need" in {lang}]

2
00:00:02,600 --> 00:00:04,000
[Extremely concise translation of fragment "to go to hospital" in {lang}]

---

{GLOSSARY_DICT}

# ACTUAL TASK
Translate and adapt ONLY the following SRT batch into {lang}. 
Remember: natural and fluent spoken {lang}, and STRICTLY preserve every single block split!
Output the result inside `<TRANSLATE_TEXT>` tags.

<INPUT>
{batch_input}
</INPUT>
```

---

## 14. 手动下载 faster-whisper(本地) 渠道的模型

国内用户在首次运行 `faster-whisper` 或 `openai-whisper` 渠道时，经常会因 HuggingFace 网络拦截导致下载报错。此时需要手动下载模型。

### 14.1 手动导入的基础规则
*   在 pyVideoTrans 的 **`models` 文件夹**内，为对应的模型建立专属的英文文件夹。文件夹命名规范必须**完全一致**。
*   进入对应模型的 HuggingFace 官方主页，点击 **`Files and versions`** 标签，将里面所有的文件（包括 `.json`、`.bin`、`.txt` 后缀文件，无需下载大文件夹内的）全部下载，拷贝并放入新建的专属子文件夹内。

### 14.2 常用离线模型目录规范

| 模型名称 | 创建文件夹名称（放入 `models/` 内） | 官方模型下载地址（若被墙可用国内镜像 `hf-mirror.com` 替换） |
|:---|:---|:---|
| **tiny** | `models--Systran--faster-whisper-tiny` | [Systran/faster-whisper-tiny](https://huggingface.co/Systran/faster-whisper-tiny/tree/main) |
| **base** | `models--Systran--faster-whisper-base` | [Systran/faster-whisper-base](https://huggingface.co/Systran/faster-whisper-base/tree/main) |
| **small** | `models--Systran--faster-whisper-small` | [Systran/faster-whisper-small](https://huggingface.co/Systran/faster-whisper-small/tree/main) |
| **medium**| `models--Systran--faster-whisper-medium`| [Systran/faster-whisper-medium](https://huggingface.co/Systran/faster-whisper-medium/tree/main) |
| **large-v3**| `models--Systran--faster-whisper-large-v3`| [Systran/faster-whisper-large-v3](https://huggingface.co/Systran/faster-whisper-large-v3/tree/main) |
| **large-v3-turbo**| `models--mobiuslabsgmbh--faster-whisper-large-v3-turbo`| [mobiuslabsgmbh/faster-whisper-large-v3-turbo](https://huggingface.co/mobiuslabsgmbh/faster-whisper-large-v3-turbo/tree/main) |
| **distil-large-v3** (限英语)| `models--Systran--faster-distil-whisper-large-v3`| [Systran/faster-distil-whisper-large-v3](https://huggingface.co/Systran/faster-distil-whisper-large-v3/tree/main) |

---

## 15. 常见问题排查与故障恢复 (FAQ)

### 15.1 启动与客户端基础运行故障

#### 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 即可无痛重建全套出厂配置。*

---

### 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: 在执行翻译合成时，任务管理器里显示 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 秒**，以低频率温和调用，即可彻底避免被封限流。

#### 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`。

---

### 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 切割过滤，可能判定该段音频无人类语音输入。

---

## 16. 官方参考文档链接

- [使用入门](https://pyvideotrans.com/getstart)
- [下载软件](https://pyvideotrans.com/downpackage)
- [MacOSX/Linux安装](https://pyvideotrans.com/deply)
- [单视频精修模式](https://pyvideotrans.com/danshipin)
- [高级选项](https://pyvideotrans.com/adv)
- [语音克隆](https://pyvideotrans.com/multi-role-dubbing)
- [导入本地已有的字幕或人声](https://pyvideotrans.com/localsrt)
- [修改提示词](https://pyvideotrans.com/prompt)
- [最佳配置推荐](https://pyvideotrans.com/bester)
- [cli命令行模式](https://pyvideotrans.com/cli)
- [字幕语音画面对齐](https://pyvideotrans.com/subtitle-sound-alignment)
- [常见问题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)
- [Huggingface_ASR渠道](https://pyvideotrans.com/huggingface)
- [字节语音识别大模型极速版](https://pyvideotrans.com/zijierecognmodel)
- [阿里百炼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)
- [Gemini大模型识别](https://pyvideotrans.com/gemini-recognition)
- [Deepgram.com语音识别api](https://pyvideotrans.com/deepgram)
- [faster-whisper-xxl.exe语音识别](https://pyvideotrans.com/xxl)
- [Whisper.cpp语音识别](https://pyvideotrans.com/whisper-cli)
- [Whisperx-api语音识别](https://pyvideotrans.com/whisperx-api)
- [智谱AI GLM-ASR语音识别](https://pyvideotrans.com/zhipu-ai)
- [STT语音识别API](https://pyvideotrans.com/stt)
- [VibeVoice-ASR](https://pyvideotrans.com/vibevoice-asr)
- [自定义语音识别API](https://pyvideotrans.com/recognapi)
- [Whisper.NET(AMD显卡加速)](https://pyvideotrans.com/whisper_net_setup)
- [对转录识别结果重新断句](https://pyvideotrans.com/blog/rephrase-llm)
- [faster/openai选择模型](https://pyvideotrans.com/selectmodel)
- [翻译渠道说明与介绍](https://pyvideotrans.com/fanyiqudao)
- [Microsoft翻译](https://pyvideotrans.com/microsoft)
- [Google翻译](https://pyvideotrans.com/googletranslate)
- [M2M100翻译](https://pyvideotrans.com/m2m100)
- [百度翻译](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翻译](https://pyvideotrans.com/libretranslate)
- [AzureGPT翻译](https://pyvideotrans.com/azure)
- [智谱AI](https://pyvideotrans.com/zhipu-ai)
- [DeepSeek](https://pyvideotrans.com/deepseek-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)
- [对接使用GroqCloud](https://pyvideotrans.com/groq)
- [配音渠道说明与介绍](https://pyvideotrans.com/peiyinqudao)
- [edge-TTS](https://pyvideotrans.com/edgetts)
- [Qwen3-TTS](https://pyvideotrans.com/qwen-tts)
- [OmniVoice-TTS](https://pyvideotrans.com/omnivoice)
- [VITS/Piper-TTS配音渠道](https://pyvideotrans.com/vitspiper)
- [GPT-SoVITS](https://pyvideotrans.com/gptsovits)
- [F5/Spark/index/voxpcm/Dia-TTS](https://pyvideotrans.com/f5tts)
- [CosyVoice](https://pyvideotrans.com/cosyvoice)
- [ChatterBox-TTS](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/multi-role-dubbing)
- [新增目标语言](https://pyvideotrans.com/newlanguage)
- [优化语音识别精度和断句效果](https://pyvideotrans.com/youhua)
- [调节VAD更精确控制语音识别结果](https://pyvideotrans.com/vad)
- [说话人识别](https://pyvideotrans.com/shuohuaren)
- [优化本地大模型接入](https://pyvideotrans.com/llmbetter)
- [提高AI渠道翻译字幕的质量](https://pyvideotrans.com/aitranslate)
- [Windos上配置CUDA和cuDNN](https://pyvideotrans.com/gpu)
- [为什么翻译后会出现“空白字幕行”？](https://pyvideotrans.com/faq17)
- [源码部署FunASR报错 paraformer-zh is not registered](https://pyvideotrans.com/blog/paraformer-zh-is-not-registered)
- [使用参考音频后合成声音后乱糟糟](https://pyvideotrans.com/aittserror)
- [edge-TTS配音出错](https://pyvideotrans.com/edgetts-error)
- [常见网络连接错误](https://pyvideotrans.com/httpconnecterror)
- [Gemini提示安全限制](https://pyvideotrans.com/gemini-safe)
- [window上安装python3.10](https://pyvideotrans.com/_posts/pythoninstall)
- [windows上安装CUDA12.6和cuDNN9.8](https://pyvideotrans.com/blog/cudacudnninstall)
- [如何在 Windows 10 上安装 Miniconda 并配置 AI 软件环境](https://pyvideotrans.com/blog/installconda)
- [用 uv 轻松玩转 Python 项目：从安装到运行，一步到位](https://pyvideotrans.com/blog/uv)
- [安装 Visual Studio Community 免费版,解决pip安装失败问题](https://pyvideotrans.com/blog/visualstudiocomm)
- [英伟达 RTX 5090 装机后无法使用 GPU 加速？别急，这里有解决办法](https://pyvideotrans.com/blog/5090s)
- [语音转录功能](https://pyvideotrans.com/speech2text)
- [语音合成功能](https://pyvideotrans.com/text2speech)
- [翻译字幕功能](https://pyvideotrans.com/translate-srt)
- [视频翻译功能](https://pyvideotrans.com/translate-video)
- [提取视频硬字幕为SRT](https://pyvideotrans.com/ocrsp)
- [Youtube视频下载](https://pyvideotrans.com/youtubedownload)
- [软件许可协议](https://pyvideotrans.com/law)
- [隐私政策](https://pyvideotrans.com/yinsizhengce)
- [文档使用协议](https://pyvideotrans.com/xieyi)
- [关于我们](https://pyvideotrans.com/guanyu)
- [联系我们](https://pyvideotrans.com/lianxi)
- [小额捐赠](https://pyvideotrans.com/about)
- [技术支持](https://pyvideotrans.com/support)
- [博客列表](https://pyvideotrans.com/bloglist)
- [软件技术架构](https://pyvideotrans.com/yuanli)
- [为什么网站有广告？](https://pyvideotrans.com/whyad)
---
----

## pyVideoTrans 软件许可与服务协议
更新日期：2025年10月21日

欢迎使用 pyVideoTrans（以下简称“本软件”）！本软件是一款免费、开源的本地视频翻译和语音转录工具。在安装、复制或以任何方式使用本软件前，请您务必仔细阅读并充分理解本协议中的所有条款。

您的安装、复制、下载或任何形式的使用行为，即表示您已阅读、理解并无条件接受本协议所有条款的约束。如果您不同意本协议的任何内容，请立即停止使用并从您的设备中彻底删除本软件。

1. 许可授予与软件性质

    开源免费：本软件是一款基于 GPL-v3 开源协议发布的免费软件。您可以从官方渠道（https://github.com/jianchang512/pyvideotrans）或文档站(https://pyvideotrans.com)获取本软件的源代码和Windows预打包版。
    禁止商业销售：开发者未授权任何实体或个人销售本软件。任何通过付费渠道获取本软件的行为均与开发者无关，开发者对此不承担任何责任。
    重要提醒：第三方 API 需您自行提供账户和密钥（仅本地存储），产生的费用由第三方收取，与开发者无关，开发者仅在软件中提供API对接技术规范。请查阅各 API 协议以确认商用许可及费用标准。
    


2. 数据隐私

    本地运行：本软件的核心功能完全在您的本地计算机上运行，不会收集或上传您的任何个人信息、视频文件或操作数据至开发者服务器。
    第三方服务：当您选择使用集成的第三方API服务（如 Microsoft Azure, OpenAI, Edge TTS等）时，相关数据将直接由您的计算机发送至相应的第三方服务提供商。您的数据处理将受限于该第三方服务商的隐私政策和使用条款。开发者不参与此过程，也不对第三方服务的数据安全和隐私泄露承担任何责任。
    版本更新与报错信息：软件通过 https://pyvideotrans.com/version.json 这个静态文件获取最新版本号; 当你在软件中点击“报告错误”按钮时，会打开 https://bbs.pyvideotrans.com/post 报错提交页面并显示错误信息，在该页面你仍需要再次点击“发布”按钮，才会向开发者提交错误信息，否则错误信息只会保留在本地和你的浏览器缓存中，不会提交。


3. 免责声明与责任限制

    本软件按“原样” 提供，不附带任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途适用性及非侵权性的保证。


    无保证：开发者不保证本软件能够满足您的所有需求，也不保证软件运行不会中断或出现错误。您将承担使用本软件所带来的一切风险。
    责任限制：在任何情况下，无论基于何种法律理论（无论是合同、侵权或其他），开发者均不对任何因使用或无法使用本软件而导致的任何形式的直接、间接、特殊、偶然或后果性损害承担责任。这包括但不限于：数据丢失、文件损坏、利润损失、业务中断、计算机故障或任何其他商业损害或损失，即便开发者已被告知存在此类损害的可能性。
    用户责任：您对通过本软件处理的所有内容负全部责任。您必须确保拥有处理这些内容的合法权利，并遵守您所在地区及中华人民共和国的所有适用法律法规，包括但不限于版权法和知识产权法。任何因非法使用本软件而导致的法律后果，均由您自行承担。


4. 您的义务

    数据备份：软件缺陷或不当操作可能导致数据丢失或文件损坏。在使用本软件处理任何重要文件之前，您有绝对责任对您的原始文件和重要数据进行充分备份。
    合法使用：您承诺不使用本软件进行任何非法活动，包括但不限于侵犯他人版权、传播非法信息等。


5. 其他条款

    协议修改：开发者保留随时修改本协议条款的权利。修改后的协议将在官方渠道公布，恕不另行通知。您继续使用本软件将被视为接受修改后的协议。
    最终解释权：在法律允许的最大范围内，本协议的最终解释权归本软件开发者所有。


6. 关于 pyvideotrans 处理产出物的版权归属说明：

    
1. 工具定位：pyvideotrans 是一款辅助翻译与配音的技术工具。软件本身不对用户处理后的产出物（包括但不限于翻译文本、配音音频、合成视频）主张任何版权。


    2.版权归属原则：产出物的版权归属通常取决于以下两个前提，请您自行评估确认：
     -原始素材授权：您必须拥有原始输入作品的合法版权或已获得足以支持二次创作/翻译的授权。
     -第三方服务协议：pyvideotrans 集成了多种大模型（如 Whisper, index-tts ,f5-tts ,DeepSeek等）及第三方 API（如 Edge-TTS, Google Translate 等）。产出物的商用权利受这些服务商的《服务协议》或《开源协议》约束。
	
	简单来说：如果你拥有原始素材的版权，那么使用本软件处理后你仍然拥有产出物的版权。如果你拥有版权的同时，使用的本地模型或第三方API允许商用，那么产出物你也可以商用。

3. 用户责任：用户在使用本软件过程中，应确保不侵犯任何第三方的知识产权。因原始素材侵权或违反第三方 API 使用规定而产生的法律后果，由用户自行承担。

4. 建议：由于不同模型和 API 的商用条款可能随时间变更（例如某些开源模型仅限非商业研究），建议您在进行商业使用前，详细阅读所选渠道提供商的最新服务条款。



如果您已阅读并同意上述所有条款，请开始使用本软件。否则，请删除本软件。

---

::: danger 防骗声明

- 本软件是一款基于 [GPL-V3 协议](https://www.gnu.org/licenses/gpl-3.0.html) 发布的开源软件。您可以从 [官方GitHub仓库](https://github.com/jianchang512/pyvideotrans) 或 [文档站](/downpackage) 下载和使用源代码或Windows预打包版。

- 【未授权商业销售行为】
本开发者未授权任何实体或个人销售本软件(例如淘宝、闲鱼、拼多多等)。
任何通过付费渠道获取本软件的行为均与开发者无关，开发者未授权也未从中受益，对此不承担任何责任，如果你是花钱购买并且想退款，请自行找卖家退钱或平台投诉，勿找开发者。

- 【无需登录或认证】下载预打包版或部署源码后就直接可用，无需登录或卡密验证，凡是需要此类操作才可使用的，都不是官方原版，请知悉。

- 【关于第三方API】
第三方 API 需您自行提供账户和密钥（仅本地存储），相关费用你需自行在第三方平台充值或购买，与开发者无关，开发者仅在软件中提供API对接的技术规范。

[查看软件使用和许可协议了解更多...](https://pyvideotrans.com/law)


:::