VideoLingo：给视频做字幕翻译、对齐和配音

跨语言看视频，最烦的往往不是听不懂，而是字幕又碎又硬、配音对不上口型。VideoLingo 把这条链路收成一套本地流水线：用 yt-dlp 拉片源（也可以直接丢本地文件），WhisperX 做词级转写，再用大模型做切分、术语和「翻译-反思-改写」，最后输出单行字幕，配音可选。

仓库在 Huanshere/VideoLingo，界面是 Streamlit。官方也提供在线试用 videolingo.io。下面按本机自建来写。

它实际在干什么

整条流程可以想成六步，每一步都能在界面里暂停、续跑：

下载或导入视频
WhisperX 转写（词级时间戳，尽量少幻觉）
NLP 加大模型做字幕切分，目标是 Netflix 那种单行字幕，避免一行里挤两句
术语表：你可以预先丢进 custom_terms.xlsx，模型也会自动抽术语，后面翻译会沿用
三步翻译：先译，再反思，再按片中语气改一版
可选配音：Azure / OpenAI / Fish / Edge / GPT-SoVITS 等，按原句时长对齐后再混进画面

输入语言目前对英语、法语、德语、意大利语、西班牙语比较稳，俄语和中文也能用（中文走了一套带标点增强的 Whisper）。翻译侧不限语种。配音语种取决于你选的 TTS。

它和一堆「丢进链接就出字幕」的脚本差在两点：强制单行，以及翻译不是一次生成完事。代价是链路更挑模型，JSON 格式不稳的小模型很容易在中途炸掉。

环境准备

FFmpeg 必须装，别用缺编码器的精简包（conda-forge 那份经常没有 libmp3lame）：

bash

# Debian / Ubuntu
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows（Chocolatey）
choco install ffmpeg

有 NVIDIA 显卡会快很多。Windows 上要先装 CUDA Toolkit 12.6 或更新，再装 cuDNN 9.3，并把 C:\Program Files\NVIDIA\CUDNN\v9.3\bin\12.6 加进 PATH，然后重启。安装脚本会读 nvidia-smi，自动挑 cu126 / cu128 / cu129 的 PyTorch 轮子。RTX 50 系会走到带 sm_100 的 cu129。不要自己去装 cu130 / cu131，ctranslate2 还停在 CUDA 12，会报找不到 cublas64_12.dll。

没有独显也能跑，Whisper 会慢一截。完全本地、不想交 API 的话，大模型用 Ollama，配音用 Edge TTS。这时把 config.yaml 里的 max_workers 设成 1，summary_length 降到大概 2000，否则本机上下文很容易撑不住。

用 uv 安装（推荐）

官方已经不维护 Conda 路线，改走 uv。setup_env.py 会装 uv、拉 Python 3.10、再按固定顺序装依赖：先锁 PyTorch 的 CUDA 版本，再用 --no-deps 装 demucs（防止 torchaudio 被降级），最后才是其余包。别自己打乱这个顺序。

bash

git clone https://github.com/Huanshere/VideoLingo.git
cd VideoLingo
python setup_env.py

启动：

bash

# macOS / Linux
.venv/bin/streamlit run st.py

# Windows
.venv\Scripts\streamlit run st.py

Windows 也可以双击 OneKeyStart.bat。浏览器打开后，在侧边栏填大模型的 API Key。接口是 OpenAI 兼容格式，所以 OpenRouter、DeepSeek、各家中转都能接。

有 GPU 并且驱动大于 550、CUDA 12.4 左右，也可以走 Docker：

bash

docker build -t videolingo .
docker run -d -p 8501:8501 --gpus all videolingo

镜像里不含 Whisper 权重，第一次跑会下载。想跳过的话，把模型目录挂到容器的 /app/_model_cache。Docker Hub 上有现成镜像 rqlove/videolingo:latest。

配模型和配音

翻译对齐要吐严格的 JSON，文档建议别用小于约 30B 的模型。默认走 OpenRouter 上的 deepseek/deepseek-v4-flash：284B MoE，每次激活约 13B，图的是便宜和速度快，不是推理上限。质量优先可以换成 Claude Sonnet / Opus 4.6、Gemini 3.1 Pro 这类。本机则用 Ollama 拉一个 32B 左右的模型，比如 qwen3-32b。

WhisperX 可以本机跑 large-v3，也可以走托管 API。背景音乐很吵时，打开人声分离；否则词级对齐用的 wav2vec 容易被伴奏带偏。字幕句尾如果是数字或特殊符号，有时会被提前切断，因为对齐模型听的是 “one”，对不上字符 1。

配音不是必须的。只出字幕可以关 TTS。要配的话常见组合是：

Azure TTS：中文自然，情感一般
OpenAI TTS：英文情绪好，中文口音偏外
Edge TTS：免费本机，效果一般
GPT-SoVITS：克隆最强，只稳中英文，需要和 VideoLingo 目录并列放整合包，配置最烦

自己的 TTS 可以改 core/all_tts_functions/custom_tts.py。

术语表在处理前写进 custom_terms.xlsx，三列大意是：原文、译名、备注。例如产品名、人名、梗，提前锁死，后面三步翻译才不会每次换一个译法。

跑一条任务

界面里贴 YouTube 链接，或上传本地视频。然后按默认流水线走即可。日志比较细，中途失败不用从头来：清掉出错的那一段缓存再续。

批量模式还在 beta，文档在仓库的 batch/ 目录，适合已经调通单条、要灌一批链接的情况。先别把批量当主路径。

多语混剪的片子要注意：WhisperX 强制对齐时会绑一种主语言，其他语言的句子可能被丢掉。多角色分别配音目前也做不到，说话人分离还不够稳。

常见坑

翻译阶段出现 All array must be of the same length 或 Key Error，多半是模型没按 JSON 回，或者内容被拒译。去看 output/gpt_log/error.json 里的 response / msg，删掉 output/gpt_log 再换一个更听话的模型重试。如果文件夹留着，下次会读到同一份坏响应，会一直失败。

local_files_only=True 是 Hugging Face 模型没下下来，确认能访问 huggingface.co。SSL / Timeout 一类对大陆网络很常见，换节点再跑。

Windows 上如果 spacy 提示找不到 xx_core_web_md，但 pip 又显示已装，通常是包装进了用户目录而不是当前环境。用该环境的 Python 强制重装：

bash

python -m pip install xx-core-web-md --no-user --force-reinstall --no-deps

更细的安装说明和报错列表见官方文档：开始使用（中文）。

配音很难 100% 贴上原片语速和语气，项目已经按句做了不少时长拉伸，但跨语种语序一变，口型对不上是正常的。先把字幕质量调稳，再决定要不要上克隆音色。

字节笔记本

VideoLingo：给视频做字幕翻译、对齐和配音

它实际在干什么

环境准备

用 uv 安装（推荐）

配模型和配音

跑一条任务

常见坑