YouDub WebUI | 人才招聘

QQ 交流群：618246010

一个被真实创作者工作流验证过的开源视频本地化工具。

YouDub WebUI 可以把单个 YouTube 或 Bilibili 视频自动转换成目标语言配音版：下载视频、分离人声与背景音、识别字幕、翻译、生成配音、混音、压制字幕，最后输出可在线播放和下载的新视频。

核心成熟场景是 YouTube 英文 -> 中文配音；同时已经支持 Bilibili 中文 -> 英文配音。

English README: README.en.md

真实生产案例

作者的 B 站频道：黑纹白斑马（粉丝 80 万+，视频 2 万+）的全站作品均使用 YouDub WebUI 自动翻译配音，覆盖科技、游戏、科普、动物、历史等题材。

这不是一个只跑过 demo 的玩具项目。YouDub WebUI 的目标很明确：让个人创作者、开发者和小团队能够在本地掌控一条完整的视频本地化流水线，并且保留足够简单的架构，方便理解、调试和二次开发。

效果示例

下面两组样例均由本项目真实生成，可以在 GitHub 页面直接播放。左侧是原视频，右侧是自动生成的配音版本；配音版包含目标语言语音和字幕，同时保留原视频的背景音乐与音效。

1. Jensen Huang on Nvidia's Competition

原视频链接 · YouTube Shorts · 英文 -> 中文

原始英文	中文配音版
jensen_huang_source.mp4	jensen_huang_dubbed.mp4

2. How much YT paid me for 129 million shorts views

原视频链接 · YouTube 横屏长视频 · 英文 -> 中文 · 下方为开头 40 秒切片，完整版可在 demo-assets Release 下载

原始英文	中文配音版
blastoff_clip_source.mp4	blastoff_clip_dubbed.mp4

快速开始

1. 准备运行环境

已验证和推荐的运行方式：

Windows 10/11 + PowerShell 5.1+：推荐开发环境，也是本文档优先覆盖的平台。
Linux / WSL2 / macOS：后端和前端命令按 POSIX shell 给出；CUDA、FFmpeg、PyTorch/音频依赖需要按各平台实际环境安装。
CUDA GPU：推荐用于完整视频处理。DEVICE=cpu 可以运行部分流程，但完整转写、分离、TTS 会非常慢；DEVICE=mps 会让 Whisper 自动退回 CPU 以避开 MPS float64 限制。

基础依赖：

Python 3.12。
Node.js 20+。
FFmpeg / ffprobe，并确保命令在 PATH 中可用。
可访问 YouTube 的代理（处理 YouTube 视频时需要）
Netscape 格式的 YouTube Cookie（处理 YouTube 视频时推荐配置）
OpenAI 兼容 Chat Completions API 的 base URL、API key 和模型名

首次运行会下载或加载较大的 ASR、TTS、音频处理模型，请预留磁盘空间和网络时间。

平台注意事项：

Windows PowerShell 使用 .venv\Scripts\...，不要照抄 .venv/bin/...。
macOS/Linux 使用 .venv/bin/...。
如果系统里同时存在多个 Python，请先确认 py -0p（Windows）或 python3.12 --version（macOS/Linux）的结果。
代理、Cookie、模型缓存和工作目录都保存在本机；路径中含空格时，建议使用引号或写入 .env。

常见系统依赖安装示例：

# Windows PowerShell（任选你本机已有的包管理器）
winget install Gyan.FFmpeg.Shared
winget install OpenJS.NodeJS.LTS

Windows 上建议安装 FFmpeg 的 shared/full-shared 版本；安装后请确认 ffmpeg -version 和 ffprobe -version 可用，并且 FFmpeg 的 DLL 目录在 PATH 中，否则音频分离阶段可能无法加载 TorchCodec/FFmpeg 运行库。

# Ubuntu / Debian / WSL2
sudo apt update
sudo apt install -y ffmpeg nodejs npm

# macOS（Homebrew）
brew install ffmpeg node

如果你的系统包管理器无法提供 Python 3.12，建议从 Python 官网、pyenv、conda/mamba 或发行版推荐方式安装；关键是后续创建虚拟环境时确认使用的是 3.12。

2. 克隆项目

Windows PowerShell、macOS 和 Linux 通用：

git clone https://github.com/liuzhao1225/YouDub-webui.git
cd YouDub-webui
git submodule update --init --recursive

Demucs 以源码子模块引入，请不要跳过 git submodule update。

3. 安装依赖

Windows PowerShell

Python 依赖：

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\pip.exe install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt

前端依赖：

npm --prefix apps/web install --registry=https://registry.npmmirror.com

macOS / Linux / WSL2

Python 依赖：

python3.12 -m venv .venv
.venv/bin/python -m pip install -U pip
.venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt

前端依赖：

npm --prefix apps/web install --registry=https://registry.npmmirror.com

如果 Aliyun 镜像中某个 Python 包暂时不可用，再单独对失败的包使用 Tsinghua 源重试；不要把多个镜像混在同一条 resolver 命令里。

可选：NVIDIA CUDA GPU

如果要用 NVIDIA GPU 跑 Whisper、Demucs 或 VoxCPM，请在安装 requirements.txt 之前先安装 CUDA 版 PyTorch：

Windows PowerShell：

.\.venv\Scripts\pip.exe install -r requirements-pytorch-cu128.txt

Linux / WSL2：

.venv/bin/pip install -r requirements-pytorch-cu128.txt

requirements-pytorch-cu128.txt 默认使用 PyTorch 的 cu128 wheel 源。不同 NVIDIA 驱动或 CUDA 环境可能需要不同的 PyTorch CUDA 版本，请按 PyTorch 官方安装页选择匹配命令。CPU 用户和 macOS 用户不需要执行这一步；如果没有安装 CUDA 版 PyTorch，请在 .env 中设置 DEVICE=cpu。

安装后可以验证 CUDA 是否真的可用：

.venv/bin/python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

4. 配置环境

Windows PowerShell：

Copy-Item env.txt.example .env

macOS / Linux / WSL2：

cp env.txt.example .env

应用运行时读取 .env。不要提交 API key、Cookie、下载视频或生成产物。

后端默认强制认证；YOUDUB_AUTH_PASSWORD_HASH 未配置时会拒绝启动。请在本机交互式输入访问密码并生成 Argon2id 哈希，命令不会把明文密码写入 shell 历史：

Windows PowerShell：

.\.venv\Scripts\python.exe -c "from getpass import getpass; from pwdlib import PasswordHash; print(PasswordHash.recommended().hash(getpass('YouDub password: ')))"

macOS / Linux / WSL2：

.venv/bin/python -c "from getpass import getpass; from pwdlib import PasswordHash; print(PasswordHash.recommended().hash(getpass('YouDub password: ')))"

把输出的整行哈希填入 .env 的 YOUDUB_AUTH_PASSWORD_HASH。不要填写明文密码，也不要把真实哈希提交到 Git。

常用环境变量：

变量	说明
`WORKFOLDER`	每个任务的媒体、分段音频和中间产物目录。
`MODEL_CACHE_DIR`	ModelScope 模型缓存目录，默认用于 VoxCPM2。
`YOUDUB_AUTH_PASSWORD_HASH`	必填的登录密码 Argon2id 哈希；不接受明文密码。
`YOUDUB_AUTH_SESSION_TTL_SECONDS`	登录会话绝对有效期，默认 `604800` 秒（7 天）。
`YOUDUB_AUTH_COOKIE_SECURE`	HTTPS 部署必须设为 `true`；仅可信的本机 HTTP 开发可设为 `false`。
`YOUDUB_AUTH_COOKIE_SAMESITE`	会话 Cookie 的 SameSite 策略，可选 `lax` 或 `strict`；同源代理部署建议 `strict`。
`DEVICE`	模型运行设备，例如 `auto`、`cuda`、`cuda:0`、`mps`、`mps:0` 或 `cpu`；`auto` 按 CUDA、MPS、CPU 顺序选择。
`DEMUCS_DEVICE` / `WHISPER_DEVICE`	可选组件级设备覆盖；留空时使用 `DEVICE`。Whisper 选择 MPS 时会退回 CPU，因为词级时间戳对齐依赖 MPS 不支持的 float64 DTW。
`OPENAI_BASE_URL`	OpenAI 兼容 API 地址，例如 `https://api.openai.com/v1`。
`OPENAI_API_KEY`	翻译阶段使用的 API key。
`OPENAI_MODEL`	翻译阶段使用的 Chat Completions 模型。
`OPENAI_TRANSLATE_CONCURRENCY`	翻译阶段的并发请求数，默认 `50`。
`LOCAL_UPLOAD_MAX_BYTES`	本地视频上传大小上限，默认 4 GiB。
`LOCAL_SUBTITLE_MAX_BYTES`	可选本地 SRT 字幕上传大小上限，默认 20 MiB。
`YTDLP_PROXY_PORT`	yt-dlp 使用的本机代理端口，例如 `7890`。
`HTTP_PROXY` / `ALL_PROXY`	未在 UI 中设置代理端口时，yt-dlp 可读取 `HTTP_PROXY`；HTTPX/OpenAI SDK 也会读取这些环境代理。
`NO_PROXY`	逗号分隔的代理绕过列表；使用本地 OpenAI 兼容服务时建议包含 `localhost,127.0.0.1,::1`，避免本地请求绕行系统代理。
`VOXCPM_MODEL` / `VOXCPM_MODEL_DIR`	VoxCPM2 的 ModelScope 模型名或本地模型目录；VoxCPM 当前由上游包内部选择 CUDA/MPS/CPU，任务日志会显示为 `voxcpm=library-auto`。
`VOXCPM_LOAD_DENOISER` / `VOXCPM_CFG_VALUE` / `VOXCPM_INFERENCE_TIMESTEPS` / `VOXCPM_MIN_REFERENCE_MS`	VoxCPM2 推理参数。
`CORS_ALLOW_ORIGINS` / `CORS_ALLOW_ORIGIN_REGEX`	显式允许的跨源前端来源；不能使用 `*`。同源 Next 代理不需要配置。

默认 CORS 只允许 localhost、127.0.0.1 和 ::1 的 :3000。推荐始终使用 Next.js 同源 /api 代理；如果浏览器确实直连不同 origin 的后端，必须把完整、可信的 origin 追加到 CORS_ALLOW_ORIGINS，例如 https://youdub.example.com。CORS 不是认证或 CSRF 防护，后端仍会校验 HttpOnly 会话 Cookie 和每会话 CSRF token。

5. 启动服务

Windows PowerShell

后端：

.\.venv\Scripts\uvicorn.exe backend.app.main:app --reload --host 0.0.0.0 --port 8000

前端：

npm --prefix apps/web run dev -- --hostname 0.0.0.0 --port 3000

macOS / Linux / WSL2

后端：

.venv/bin/uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000

前端：

npm --prefix apps/web run dev -- --hostname 0.0.0.0 --port 3000

前端默认通过同源 /api/... 请求访问后端，并由 Next.js 代理到 http://127.0.0.1:8000。如果后端不在本机 8000 端口，启动前端时设置 NEXT_SERVER_API_BASE_URL，例如：

NEXT_SERVER_API_BASE_URL=http://192.168.1.10:8000 npm --prefix apps/web run dev -- --hostname 0.0.0.0 --port 3000

打开：

http://localhost:3000

如果从局域网、WSL2 或远程机器访问，浏览器里使用运行前端机器的实际 IP 或主机名，例如 http://192.168.1.20:3000。后端默认监听 0.0.0.0:8000，前端默认监听 0.0.0.0:3000。

浏览器应始终访问前端地址，由 Next.js 转发 /api；不要把认证信息放进 NEXT_PUBLIC_*、URL query 或前端存储。通过局域网或公网访问时，请在前端前面配置 HTTPS 反向代理并设置 YOUDUB_AUTH_COOKIE_SECURE=true。明文 HTTP 只适用于可信的本机开发环境。

运行时文件权限

在 POSIX 系统上，后端会在读取 .env、连接 SQLite 或启动 worker 前永久设置进程 umask 0077。启动迁移只检查文件系统元数据，不读取或改写文件内容，并执行以下策略：

data/、Cookie、日志和 WORKFOLDER 下的目录收紧为 0700，普通文件收紧为 0600。
SQLite 主库和 -journal、-wal、-shm sidecar、.env、env.txt、Cookie、上传与新生成产物保持 owner-only。
符号链接、特殊文件、异主文件和不安全的可写祖先会让启动失败；服务不会在权限迁移失败后继续启动 worker。
MODEL_CACHE_DIR 根目录必须由 root 或服务账号拥有且不可被其他用户写入；服务账号拥有的缓存根会收紧为 0700。缓存内部不做递归 chmod 或内容校验，因此部署前必须确认已有模型缓存可信。

建议用专用 OS 用户运行服务，并确保仓库及自定义 WORKFOLDER 的父目录不允许其他组或用户重命名目录项。该边界防护其他 UID 或不可信组用户，不防同 UID 进程、调试器或 root；更强隔离请使用独立账号、容器或系统服务沙箱。

首次启用或执行权限迁移时，应先停止仍会创建或删除运行时文件的旧实例；如果并行启动因 fail-closed 校验失败，请停止旧实例后重试启动。

Windows 的 chmod/umask 不等价于 NTFS ACL。Windows 部署需由管理员把仓库、.env、env.txt、data 和 WORKFOLDER 的 DACL 限制到服务账号；应用会做兼容性检查，但不能替代正确的 NTFS ACL。真实 .env、env.txt、Cookie、SQLite、data/ 和 workfolder/ 已被 .gitignore 排除，不要强制加入 Git。

页面里怎么用

使用生成哈希时设置的访问密码登录。
打开右上角 Settings。
粘贴 Netscape 格式 YouTube Cookie。
设置 yt-dlp 代理端口，例如 7890 或 20171。
填写 OpenAI base URL 和 API key。
点击 Get models 拉取模型列表，或手动输入模型名。
按 API 提供商额度调整 Translate concurrency。
回到首页，提交 YouTube URL、Bilibili URL，或上传本地视频。
- 本地视频可额外上传一份已翻译好的 .srt 字幕；上传后会跳过 Whisper 识别和 OpenAI 翻译，直接用这份字幕生成配音与压制字幕。
- 翻译方向决定字幕目标语言，例如选择“英文 -> 中文”时，上传的 SRT 会被视为中文字幕。
进入任务详情页查看阶段进度、运行日志和最终视频。

API key 和 Cookie 会在页面中脱敏显示，后端不会把 Cookie 明文返回给前端。

导出 YouTube Cookie

推荐使用 Chrome 扩展 Get cookies.txt LOCALLY（开源，Cookie 不出本机）：

在 Chrome 安装扩展并保持启用。
登录 https://www.youtube.com。
在 youtube.com 页面点击扩展图标，选择 Export -> Netscape，得到 cookies.txt。
把文件内容整段粘贴到 Settings 的 YouTube cookie 输入框。

请只处理你有权下载、转换和发布的视频内容。

工作流程

YouTube / Bilibili URL
  -> yt-dlp 下载单个视频
  -> Demucs 分离人声与背景音
  -> Whisper 识别语音并输出词级时间戳
  -> 句子与时间范围整理
  -> OpenAI 兼容 API 预处理全文并逐句并发翻译
  -> 按句切分原始人声作为参考音频
  -> VoxCPM2 生成目标语言配音
  -> 对齐配音时长并与背景音混音
  -> FFmpeg 压制字幕并输出最终 mp4

本地视频上传使用同一条后半段流水线。若同时上传已翻译 .srt 字幕，系统会从 SRT 生成内部字幕时间轴，跳过 Whisper 与 OpenAI 翻译阶段，然后继续切分参考音频、生成配音、混音并压制字幕。v1 仅支持本地视频搭配 .srt，不支持 URL 任务附加字幕。

功能亮点

真实可用的端到端流程：从 URL 到最终视频，不需要手动拆分音频、整理字幕或压制视频。
双来源入口：YouTube 英文 -> 中文是核心成熟场景；Bilibili 中文 -> 英文也已接入同一条任务流水线。
本地优先：SQLite、Cookie、日志、中间产物和最终视频都保存在本机目录中。
可观察任务进度：任务历史、阶段状态、阶段耗时、运行日志和错误信息都可以在页面里查看。
失败可恢复：失败任务可以从失败阶段继续执行，已成功阶段会复用缓存产物。
可重跑可清理：支持按任务 rerun，也支持删除任务记录、日志和 workfolder/ 下的会话目录。
结果可检查：任务成功后可在页面内播放最终视频，也可以下载 mp4 文件。
设置在 UI 内完成：YouTube Cookie、yt-dlp 代理端口、OpenAI base URL、API key、模型名和翻译并发数都可在 Settings 中维护。
适合二次开发：管线串行、模块边界清晰，方便替换 ASR、翻译、TTS 或字幕样式。

技术栈

Frontend: Next.js App Router, shadcn/ui, Tailwind CSS, Lucide icons
Backend: FastAPI, SQLite, in-process background worker
Download: yt-dlp
Source separation: Demucs source submodule
ASR: openai-whisper（默认 large-v3-turbo）
Translation: OpenAI-compatible Chat Completions API
TTS: VoxCPM2
Media processing: FFmpeg, pydub, librosa, audiostretchy

开发与测试

后端测试：

Windows PowerShell：

.\.venv\Scripts\pytest.exe backend/tests

macOS / Linux / WSL2：

.venv/bin/pytest backend/tests

前端检查：

npm --prefix apps/web run lint
npm --prefix apps/web run build

项目的主要目录：

backend/app/       FastAPI API、任务队列、流水线和模型适配器
backend/tests/     后端单元测试
apps/web/          Next.js WebUI
scripts/           辅助脚本
submodule/demucs/  Demucs 源码子模块

项目状态与贡献

YouDub WebUI 仍然是 MVP，但已经可以支撑真实创作者的日常视频本地化生产。当前优先级是保持最短链路稳定、保持架构简单，并让更多人能跑起来、改得动。

欢迎贡献：

改进安装和模型下载体验。
适配更多 ASR、TTS 或翻译后端。
优化字幕样式、横竖屏布局和语音时长对齐。
提升 YouTube / Bilibili 下载稳定性。
增强任务管理、产物管理和失败恢复体验。
补充不同平台的运行说明。

如果这个项目对你有帮助，欢迎 Star、Fork、提交 Issue 或 PR，也欢迎分享给关注 AI 视频本地化、开源工具和跨语言内容传播的人。

人才招聘

银河智学是一家人工智能教育科技企业，致力于将大模型技术与探究式教学范式深度融合，构建面向 AGI 时代的创新学习体系。

公司官网：xiaoluxue.com

我们正在北京海淀区中关村招聘以下岗位：

全栈研发工程师
高级 Go 后端架构师（内容平台 / 长任务编排 / AI Agent Runtime）

薪资范围：30–60K × 13 薪。

简历投递：liuzhao@xiaoluxue.com

社区交流

QQ 交流群：618246010

开源许可

本项目使用 Apache License 2.0，详见 LICENSE。

Name		Name	Last commit message	Last commit date
Latest commit History 137 Commits
.github/workflows		.github/workflows
apps/web		apps/web
backend		backend
scripts		scripts
submodule		submodule
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
env.txt.example		env.txt.example
package.json		package.json
requirements-pytorch-cu128.txt		requirements-pytorch-cu128.txt
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

YouDub WebUI | 人才招聘

真实生产案例

效果示例

1. Jensen Huang on Nvidia's Competition

2. How much YT paid me for 129 million shorts views

快速开始

1. 准备运行环境

2. 克隆项目

3. 安装依赖

Windows PowerShell

macOS / Linux / WSL2

可选：NVIDIA CUDA GPU

4. 配置环境

5. 启动服务

Windows PowerShell

macOS / Linux / WSL2

运行时文件权限

页面里怎么用

导出 YouTube Cookie

工作流程

功能亮点

技术栈

开发与测试

项目状态与贡献

人才招聘

社区交流

开源许可

Star History

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages