翻译引擎（配音标签页）

翻译引擎（Dub 标签页）¶

VoiceStudio 的配音分为两个步骤：转写 → 翻译 → 朗读。其中的翻译步骤是可插拔的——在 Dub 标签页的引擎下拉菜单中选择引擎。有两个引擎是内置的，并且始终可离线使用；其余引擎需要一个小型可选的 Python 包。

Electron 的 设置 > 模型 > 翻译 页面会同时显示可用和不可用的引擎，因此安装和配置选项始终可见。

如果你选择的引擎其包尚不可导入，引擎标签会显示一个高亮的安装入口，并且——如果你仍然尝试翻译——后端会返回一条可操作的错误信息，明确告诉你要安装什么（安装命令是单一来源的，因此按钮和错误信息永远不会不一致）。

自带翻译（粘贴翻译）¶

你不必使用上述任何引擎。如果你已经在其他地方翻译过转录文稿——ChatGPT、DeepL 网站、人工翻译——点击分段表格上方的粘贴翻译并粘贴结果即可。它会映射到你已有的分段上：无需重新转写，不会有时间轴丢失，原始转录文本（text_original）保持原样，因此之后的全部翻译仍然可以从源文本进行。

三种输入格式会被自动检测：

你还可以直接将 .srt/.vtt 文件拖入（或选取）到对话框中。

在你确认之前，不会应用任何内容：对话框会以「之前 → 之后」的形式预览每一行，标记没有匹配到的行，并统计有多少粘贴的行未被使用。只有当没有任何内容匹配时，应用按钮才会被禁用；未匹配的行会保持原样，整个粘贴操作是一个单独的撤销步骤。你更改过的行会被自动标记为需要重新生成，因此一次 Regen N changed 操作只会重新朗读这些行。

这只会写入当前选中的目标语言，因此你可以为每个语言标签页粘贴不同的外部翻译，而不会影响其他语言。

安装可选翻译引擎（源码安装 vs 打包安装）¶

如何添加引擎取决于你安装 VoiceStudio 的方式。

源码安装 / 开发环境安装（一键）¶

如果你克隆了仓库并通过源码运行 VoiceStudio（uv sync + 开发启动器）或通过 Docker 运行，那么应用可以为你安装引擎：

1. 在 Dub 标签页中，打开翻译设置并从引擎下拉菜单中选择你想要的引擎（例如 Google Translate）。
2. 引擎标签旁边会出现一个高亮的安装按钮。点击它。
3. VoiceStudio 会将安装执行到后端正在使用的同一个 Python 环境中（uv pip install <package> --python <backend-interpreter>），然后重新探测。当它报告“重启后端以加载它”时，请重启，使新安装的模块可以被导入。

你也可以手动安装到后端的虚拟环境（venv）中：

uv pip install deep_translator   # Google / DeepL / Microsoft / MyMemory
uv pip install argostranslate    # Argos (already bundled; rarely needed)
uv pip install openai            # LLM (OpenAI-compatible) provider

然后重启后端。

打包版本 / 安装程序构建（只读——使用弹出浮层）¶

签名桌面安装程序（.dmg、.msi、AppImage、.deb）附带一个只读、代码签名的 Python 环境。向其中安装额外的包会破坏签名，因此这些构建版本中有意禁用了应用内安装。在这些版本中选择未安装的引擎会显示一个高亮按钮，点击后打开一个包含你所需一切的小型弹出浮层：

• 确切命令——如果你确实在某处有源码检出，并且想在那里使用在线引擎，可以运行该命令（附带一个复制到剪贴板的按钮）。
• 切换到 Argos（已捆绑，离线）——一键完成。Argos 和 NLLB 在所有构建版本中始终可以导入，因此这是有保证的逃生通道：你可以立即继续配音，完全离线，无需安装。
• 返回此页面的链接。

对打包构建版本的建议：直接使用 Argos（快速、离线）或 NLLB-200（更重、质量更高、离线）。它们不需要安装任何内容，并且永远不会离开你的电脑。只有在可以添加相应包的源码安装环境中，才去使用在线引擎。

翻译质量：Fast、Autofit、Cinematic¶

Dub 标签页中的质量控件（以及 设置 → 翻译）决定翻译的生成方式：

• Fast——直接从所选引擎（Argos、NLLB、Google 等）进行一次性翻译。不使用 LLM，不感知时间轴。
• Cinematic——由 LLM 对直译结果进行润色（反映 → 改编），以获得自然、符合上下文的措辞。
• Autofit——Cinematic 加上一次严格的时间适配处理：LLM 重写每一行，使其目标语言的朗读时间适配在分段的时间槽内（绝不超出）。这样可以保持视频的时间轴完整，并避免翻译内容超出其时间槽时出现音频时间拉伸的问题。适配会感知每种语言的发音速度。

Cinematic 和 Autofit 需要一个 LLM（见下文）。如果没有配置任何 LLM，它们会回退到 Fast，并显示提示。

LLM 引擎上的两阶段质量增强（自动术语表 + 反思过程）¶

当 LLM（OpenAI 兼容） 引擎作为活动翻译器时，默认会运行两个额外的质量阶段。在 Dub 标签页的翻译设置中，这两者都在质量控制（Quality control）旁边带有复选框（它们仅对 LLM 引擎显示——MT 引擎无法运行任何一个阶段）：

• 自动术语表（Auto glossary） — 在逐段翻译之前，额外的一次 LLM 过程会读取整个转录文本，提取一份简短的主题摘要以及一份源语言 → 目标语言的术语映射。该摘要会附带在每个片段的翻译提示中，因此角色姓名、地名和反复出现的领域术语在第 3 段和第 300 段中保持一致。它会与你的手动术语表合并——发生冲突时以你的条目为准。结果按目标语言与配音项目一起缓存，因此重新翻译未更改的转录文本不会产生额外调用；编辑片段后会重新提取。
• 反思过程（Reflect pass） — 在每段直接翻译之后，LLM 会评判草稿的冗长程度以及生硬/不自然的语体，然后将其改写为自然的口语对话。这会让每段消耗 3 次 LLM 调用，而不是 1 次——在慢速或按量计费的提供商上处理长视频时请关闭此功能。如果任何细化步骤失败或超时，将静默保留直接翻译结果；细化永远不会导致某个片段失败。

适配预测（所有质量等级）¶

每个翻译还会额外获得一次合成前的适配检查——无需 LLM。对于每个片段，VoiceStudio 会预测翻译后的台词需要多长时间来说完（根据作业中已生成的片段，对您的语音/引擎进行自我校准，并以每种语言的语速表作为冷启动回退方案），然后将其与时间槽以及下一句之前可借用的静音时间进行比较。Smart Fit 上限只能通过可闻的加速来吸收的片段会获得 Tight fit 徽章；没有任何适配方式可以挽救的片段会获得 Won't fit +Ns 徽章——这样你可以在 GPU 时间被消耗在最终会被裁剪的台词上之前缩短文本。这些徽章仅供参考：生成永远不会被阻止。

Suggest shorter lines（建议更短台词）（Quality 下的复选框，默认关闭）更进一步：对于每个“Won't fit”片段，它会请求已配置的 LLM 提供保留原意的更短改写，并在该行中以一键式 Use shorter rewrite（使用更短改写） 建议的形式呈现。它绝不会自动改写任何内容；如果未配置 LLM（或出现任何 LLM 错误），它就直接不做任何事。

LLM 提供商（用于 Cinematic / Autofit）¶

设置 → 系统 → LLM Providers（LLM 提供商） 是配置 LLM 的唯一入口。选择一个提供商，粘贴其 API 密钥，选择模型，对其进行测试，然后“用于翻译”。支持的选项包括：OpenAI、OpenRouter、OrcaRouter、Cheaper Inference、Opper、API Route、Groq、Cerebras、Google AI（Gemini）、Mistral、Cohere、NVIDIA、GitHub Models、Cloudflare、Hugging Face、SambaNova、SiliconFlow、iFLYTEK Astron MaaS、本地 Ollama / LM Studio（离线，无需密钥），以及自定义 OpenAI 兼容端点。

在此输入的密钥会以加密形式存储在您的机器上，并且永远不会返回到 UI。若要完全离线设置，请选择 Ollama（ollama pull llama3.1）或 LM Studio——不会有任何数据离开您的机器。高级用户仍可通过环境变量覆盖任何提供商（例如 GROQ_API_KEY，或旧的 TRANSLATE_BASE_URL / TRANSLATE_API_KEY / TRANSLATE_MODEL，这些变量映射到 Custom 提供商）。

OrcaRouter 无需 UI 即可通过 ORCAROUTER_API_KEY 配置，并可使用 ORCAROUTER_BASE_URL 和 ORCAROUTER_MODEL 覆盖其默认设置。

Cheaper Inference 是一个 OpenAI 兼容网关，覆盖多个实验室的模型。默认使用 gpt-5.4-mini；价格取决于所选模型和请求，详见其提供商目录。无需 UI 时，设置 CHEAPER_INFERENCE_API_KEY；并使用 CHEAPER_INFERENCE_BASE_URL 和 CHEAPER_INFERENCE_MODEL 覆盖默认设置。

Opper 是一个托管于欧盟的 AI 网关，提供一个 OpenAI 兼容 API 和一个密钥，覆盖 50+ 提供商的 700+ 个模型（默认模型为 claude-sonnet-4-6）。在提供商设置中输入来自 platform.opper.ai 的密钥，或设置 OPPER_API_KEY，并使用 OPPER_MODEL 覆盖模型。端点只能在提供商设置中更改，因为 Opper 自己的工具将 OPPER_BASE_URL 用于不同的 URL。

API Route 使用 OpenAI 兼容端点 https://global.api-route.com/v1，默认模型为 deepseek-v4.1-flash。在提供商设置中选择 API Route 并输入你的 API 密钥，或设置 API_ROUTE_API_KEY。使用 API_ROUTE_BASE_URL 和 API_ROUTE_MODEL 覆盖端点和模型。要固定活动提供商，请设置 LLM_DEFAULT_PROVIDER=api-route。与其他托管提供商一样，云端请求需要显式选择和已配置的密钥。

iFLYTEK Astron MaaS 使用 IFLYTEK_API_KEY、IFLYTEK_BASE_URL 和 IFLYTEK_MODEL。它没有默认模型：请从 MaaS 控制台 中服务的模型卡片复制模型 ID（例如 Spark X2.5）。默认 Base URL 是按量付费的推理 API；Token Plan 密钥只能与 https://maas-token-api.cn-huabei-1.xf-yun.com/v2 配合使用，而来自旧版 Spark HTTP API（spark-api-open.xf-yun.com）的密钥与二者均不兼容。

如果想改为离线运行 Spark X2.5，请使用现有的 Ollama 提供商运行开放权重 4B 或 1.7B 模型（ollama pull SparkLLM/Spark-X2.5-4B，然后将其设置为模型），或在 LM Studio 中加载。

使用 LLM_DEFAULT_PROVIDER 固定活动提供商¶

默认情况下，用于 Cinematic/Autofit 的 LLM 是你在 设置 → LLM Providers 中标记为“用于翻译”的那个。若要强制使用特定提供商而不受已存储选择的影响——这对于无头/CI/Docker 运行或共享机器非常方便——请在启动后端之前将 LLM_DEFAULT_PROVIDER 环境变量设置为提供商 ID：

LLM_DEFAULT_PROVIDER=groq        # or openai, openrouter, orcarouter, cheaperinference, opper, api-route, cerebras, iflytek, ollama, custom, …

活动提供商的解析顺序为：LLM_DEFAULT_PROVIDER（环境变量）→ 你已保存的选择 → 第一个有密钥的提供商 → 无。该 id 必须是 VoiceStudio 能够识别的 id（即 设置 → LLM 提供商 中显示的 id）；未知值会被忽略，解析会继续回退到你已保存的选择。只要设置了此环境变量，它就会优先于应用内选择器；因此，如果 UI 中的选择看似“无效”，请检查是否导出了 LLM_DEFAULT_PROVIDER。

LLM 技能（按功能路由）¶

设置 → 系统 → LLM 技能 列出了每个由 LLM 驱动的功能——Cinematic 和 Autofit 翻译、语速槽位适配、术语表自动提取、方向解析和听写清理——并允许你单独切换每个功能，或将某个功能路由到特定提供商，而不是使用全局活动提供商。这样，敏感任务（例如听写清理）可以保留在本地 Ollama/LM Studio 模型上，而较重的任务则使用远程提供商。被禁用的技能与未配置 LLM 时的表现完全相同：Cinematic/Autofit 回退到 Fast，听写清理直接透传原始文本，方向解析使用关键词启发式。所有功能默认启用并使用“活动提供商”，因此现有配置的行为不受影响。

API 密钥（在线机器翻译引擎）¶

非 LLM 的在线引擎需要密钥，请在后端启动前将其设置为环境变量（或在 设置 → 凭据 中设置）：

• DeepL： DEEPL_API_KEY（可选：DEEPL_BASE_URL，用于自托管 / 专业版 HTTPS 端点）。
• Microsoft Translator： MICROSOFT_API_KEY（可选：MICROSOFT_BASE_URL，且必须使用 HTTPS）。

编辑工作区¶

转录完成后，拖动视频/时间轴列与转录文本列之间的分隔条，可为任一侧留出更多空间。分隔条也可以用键盘操作：聚焦后，使用左/右箭头键以 5% 步长调整，或使用 Home/End 跳到最小/最大值。VoiceStudio 会记住此设备上的分隔比例。较窄的工作区会将两个面板改为上下堆叠，这样两个编辑器都不会因过小而无法使用。

故障排除¶

• “google 翻译引擎需要可选的 deep_translator Python 包……” — 说明该包未安装。从源码安装时，点击安装按钮（或运行上面的命令）并重启。在打包构建中，请通过弹出菜单切换到 Argos/NLLB。
• 安装按钮无反应 / 提示“在打包构建中已禁用” — 你使用的是经过签名的安装程序构建（符合预期）。请使用 Argos/NLLB，或在从源码检出的版本中添加该包。
• 已安装但仍然提示“需要安装” — 重启后端，让 Python 加载新安装的模块。
• “使用 'argos' 进行离线翻译不可用：其 CTranslate2 后端无法启动” — Argos 运行在 CTranslate2 上，较旧的 CTranslate2 版本（4.4.0 及以下）会向 Linux 内核请求可执行栈，而强化过的内核会拒绝此请求。VoiceStudio 首先会尝试通过清除该标志就地修复库。如果无法做到（只读安装），请在 Python 3.12+ 上重新安装后端（CTranslate2 4.8+ 不再有此类请求），或运行一次 patchelf --clear-execstack <library>。与此同时，NLLB（本地）仍然可用（#692）。

SRT 和 WebVTT 导出的每个字幕时间戳都会四舍五入一次到最近的毫秒，包括进位到下一秒或下一分钟。兼容 OpenAI 的转录导出使用相同的格式化器。

粘贴翻译接受无小时时间戳的 WebVTT 文件。只有行首的时间记录才启用时间戳匹配；句子内部类似时间戳的文本仍作为对话保留。

字幕导入会保留数字型对话，例如年份和倒计时，包括混合有编号和无编号条目的文件。条目编号仅在识别出的字幕边界处被移除。

Argos 接受中文/简体中文名称、普通话别名以及 zh-CN 等语言标签。繁体中文请求（zh-TW、zh-Hant 和显示名称）会被明确拒绝；如需繁体中文，请选择 NLLB，而不是静默地收到另一种文字。

混合或格式错误的 SRT 文件可能让一个孤立的数字无法与口语对话区分。导入器只在字幕边界和连续编号支持的情况下移除编号；有歧义的非连续编号会作为文本保留，以避免静默丢数据。标准带索引的 SRT 和 WebVTT 导出可避免这种歧义。

如果 Argos 原生运行时无法加载，桌面端和浏览器端客户端都会显示本地化的恢复指引：重新安装后端或选择 NLLB。API 会返回稳定的 argos_runtime_unavailable 错误码，且不会暴露原生库路径。

WebVTT 导入使用 WebVTT 块解析规则 将元数据块与字幕标识符分开：标识符后紧接的时间行构成一条字幕，即使该标识符是 NOTE、STYLE 或 REGION。元数据中后续的时间示例会被忽略，空字幕永远不会借用下一条字幕的标识符作为对话。

配音转录会在静音说话人分离、参考优化和清理步骤期间发出 keepalive。断开连接会停止排队的模型任务；已在运行的原生调用会保留其模型直到完成，之后清理会恢复 TTS。任务流还会要求代理禁用缓冲，以便 keepalive 能及时到达客户端。

WebVTT 导出会转义不安全的字幕文本，同时保留导入的字幕标记和既有引用。兼容 OpenAI 的 VTT 转录响应会转义所有标记和引用，因为新识别的语音是纯文本。SRT 输出则保持不变。

下载和粘贴的 WebVTT 字幕在编辑或合成前会解码一次字符引用，因此 Q&A 变成 Q&A。SubRip 没有转义机制，因此 SubRip 文本会按原样保留 &。

粘贴、选取和下载的字幕，以及导入 Stories 的 SubRip 文件，会从口语文本中移除卡拉 OK 时间戳、字幕标签（<c>、<i>、<font>、<v Name>）和 SubRip 对齐覆盖（{\an8}），以免配音朗读标记。<br> 换行会读作一个空格。在 SubRip 中，这些标签之外的 < 仍作为对话保留（2 < 3、<laughter>）。WebVTT 和 SubRip 导出只在某一行仍保留导入时写入的文字时才写出原始字幕语法；即使粘贴、编辑或翻译后落在相同文字上，也会按纯文本导出；WebVTT 导出 SubRip 字幕时会转义该对话 <，以便重新导入后读起来一致。

下载的滚动字幕在翻译前会对其短暂重复的桥接字幕进行去重。普通连续字幕会保留有意的重复词和短语，即使其时间戳相接。 ```

新的 WebVTT 导入会保留源 cue 语法以及解码后的文本，在未修改的导出中，字面转义标签和实体将原样保留。经过编辑的文本和较旧的项目仍沿用旧有的标记解释。