YouTube / 本地视频 → 语音识别 → AI 概括总结(可选)→ AI 翻译 → 双语字幕压制 → AI 中文配音,一条命令搞定。支持命令行和 Web UI 两种使用方式。
- YouTube 视频下载 — 自动下载最高画质视频(可配置分辨率上限)
- 本地视频支持 — 直接传入本地视频文件路径,跳过下载
- 批量处理 — 支持同时传入多个文件 / 链接,按顺序依次处理,单个任务失败不影响后续
- 语音识别 — 基于 faster-whisper,本地 GPU 加速,生成精准英文字幕
- AI 翻译 — 调用 Qwen3.5 等大模型 API 批量翻译,支持并发请求(默认 10 并发)
- AI 内容总结(可选) — 基于英文
.srt字幕调用大模型生成中文专业总结,输出 Markdown 文档 - 双语字幕 — 自动生成 英文 / 中文 / 双语 三份
.srt字幕文件 - 硬字幕压制 — 通过 ffmpeg 将双语字幕烧录进视频,可直接上传 B 站
- AI 中文配音 — 使用 demucs 分离背景音;TTS 可选 edge-tts、阿里云 Qwen TTS(DashScope)或本地 CosyVoice,自动混合为配音视频
- AI 画质增强 — 基于 Real-ESRGAN 超分辨率,将视频放大至最高 4K,GPU 加速,自动限制输出不超过 4K 分辨率
- Web UI — 基于 Gradio 的可视化界面,拖拽上传 / 粘贴链接即可,实时查看处理日志
视频输入 → ① 下载/导入 → ①.5 AI画质增强(可选) → ② 语音识别(字幕) → ②.5 AI概括总结(可选)
→ ③ AI翻译(中文)
→ ④ 硬字幕压制 → ⑤ 音频分离(demucs) → ⑥ TTS语音合成
→ ⑦ 混合音频 → 配音视频输出
每一步都有跳过已存在文件的逻辑,中断后重跑会自动从上次断点继续。
先说结论:
- 没有 NVIDIA GPU,仍可用:下载、识别、翻译、字幕压制、AI 总结、AI 配音。
- 只有 AI 画质增强(Real-ESRGAN)要求 NVIDIA GPU + CUDA。
conda env create -f environment.yml
conda activate subforge# NVIDIA GPU(CUDA 12.4,推荐)
pip install -r requirements.cuda124.txt
# 无 NVIDIA GPU(CPU,仅不支持 AI 超分)
pip install -r requirements.cpu.txt -i https://pypi.tuna.tsinghua.edu.cn/simple| 工具 | 用途 | 安装方式 |
|---|---|---|
| ffmpeg | 视频压制 / 音频处理 / 探测 | winget install ffmpeg 或官网下载,需加入 PATH |
| yt-dlp | YouTube 下载 | 已包含在 requirements.txt |
python -c "import torch; print('torch:', torch.__version__, 'cuda:', torch.cuda.is_available())"
python -c "import gradio, faster_whisper, srt, openai; print('python deps ok')"
ffmpeg -version若输出 cuda: True,说明可用 AI 超分;若为 False,请在 UI 中关闭“AI 画质增强”。
Copy-Item .\config.example.json .\config.json然后编辑 config.json,至少填写:
{
"qwen_api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxx",
"qwen_base_url": "https://your-api-endpoint/v1",
"qwen_model": "your-model-name"
}faster-whisper 默认优先使用 GPU(CUDA),无 GPU 会自动回退 CPU:
- NVIDIA 显卡 + 安装 CUDA Toolkit
- 如无 GPU,脚本会自动回退到 CPU(速度较慢,建议将
whisper_model调小为base或tiny)
demucs 同样支持 GPU 加速,有 CUDA 时会自动使用。
AI 画质增强(Real-ESRGAN)仅支持 NVIDIA GPU(CUDA);无 CUDA 时会直接提示不可用,不再走 CPU 慢速增强。
本工具使用 OpenAI SDK 兼容接口,可接入阿里云百炼、DeepSeek、硅基流动等服务。
config.json含真实密钥,已被.gitignore排除,不会被 git 跟踪。
requirements.txt:项目主依赖(不含 torch 三件套)requirements.cuda124.txt:CUDA 12.4 环境的 torch 依赖(推荐)requirements.cpu.txt:CPU 环境的 torch 依赖(无 GPU 时使用,不支持 AI 超分)environment.yml:conda 一键建环境配置
若你所在网络访问外网较慢,优先使用上文的清华镜像参数安装基础依赖。
python app.py独立桌面窗口(套壳浏览器,依赖 pywebview,Windows 一般自带 WebView2 运行时):
pip install pywebview
python app.py --window
# 或简写
python app.py -w默认仍会在系统浏览器中打开 http://127.0.0.1:7860;加 --window 时用独立窗口加载同一地址,可用 --host / --port 改监听。
启动后在界面中:
- 设置 标签页:表单与 JSON 编辑器实时联动;保存并应用 会写入
config.json并 自动重启本程序,新进程重新加载配置,避免内存与磁盘不一致。 - 处理 标签页:
- 粘贴 YouTube 链接(每行一个)和/或上传本地视频文件
- 可选择是否压制硬字幕、是否启用 AI 中文配音、是否启用 AI 画质增强、是否启用 AI 内容总结
- 点击「开始处理」,右侧实时显示处理日志
- 处理完成后直接下载输出文件
python auto_subtitle.py "https://www.youtube.com/watch?v=XXXXX"python auto_subtitle.py ./input/my_video.mp4支持同时传入多个 YouTube 链接和/或本地文件,按顺序依次处理:
python auto_subtitle.py "https://youtu.be/AAA" ./input/a.mp4 "https://youtu.be/BBB" ./input/b.mp4- 每个任务独立处理,单个失败会跳过并继续后续任务
- 本地文件和 YouTube 链接可任意混合
命令行模式默认启用硬字幕压制;AI 配音与 AI 内容总结功能需通过 Web UI 开启。
每个视频会在 output/ 下自动创建以视频名命名的子目录:
output/
└── My_Video/
├── My_Video.mp4 # 原始视频
├── My_Video_en.srt # 英文字幕
├── My_Video_summary.md # AI 中文专业总结(可选)
├── My_Video_zh.srt # 中文字幕
├── My_Video_bilingual.srt # 双语字幕(中文在上)
├── My_Video_硬字幕.mp4 # 压制好的字幕视频
├── My_Video_audio.wav # 提取的音频(配音时生成)
├── My_Video_background.wav # 分离的背景音(配音时生成)
├── My_Video_tts.wav # TTS 合成语音(配音时生成)
└── My_Video_配音.mp4 # 最终配音视频(含字幕 + 中文配音)
所有配置集中在项目根目录的 config.json 中,修改后立即生效(无需改代码)。缺失的字段会自动使用默认值。
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
whisper_model |
"medium" |
tiny / base / small / medium / large-v3 |
模型越大越准但越慢,tiny 极快低精度,large-v3 最准 |
device |
"auto" |
auto / cuda / cpu |
推理设备,auto 自动检测 GPU |
compute_type |
"auto" |
auto / float16 / int8 / float32 |
推理精度,GPU 推荐 float16,CPU 推荐 int8 |
video_language |
null |
null / en / zh / ja / ko / fr / de / es / ru |
视频语言;null 表示自动检测,手动指定语言会更快更稳 |
subtitle_max_gap_ms |
2000 |
500~5000 | 词级停顿阈值(毫秒)。大于该值时优先直接断句,是最重要的“按停顿切句”参数 |
subtitle_max_chars |
120 |
40~220 | 基础字幕长度上限。新算法不会一到这个值就硬切,而是把它作为目标长度和后续硬上限的基准 |
日常通常只需要先调
subtitle_max_gap_ms和subtitle_max_chars。候选窗口大小已经下沉为算法内部默认值,其余可调项收进了subtitle_advanced,默认一般不用改。
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
subtitle_advanced.target_chars_ratio |
0.82 |
0.6~1.0 | 候选断点的目标长度比例,实际目标长度 = subtitle_max_chars * ratio |
subtitle_advanced.min_chars_ratio |
0.38 |
0.2~0.6 | 过短字幕惩罚阈值,低于该比例会明显降权,减少碎片句 |
subtitle_advanced.hard_max_chars_ratio |
1.35 |
1.1~1.8 | 超长硬上限比例,超过后必须在窗口内选断点 |
subtitle_advanced.hard_max_chars_bias |
18 |
0~40 | 小字幕上限补偿值,避免 subtitle_max_chars 较小时过早硬切 |
subtitle_advanced.soft_max_duration_sec |
4.8 |
2.5~6.0 | 软时长阈值,到达后开始积极寻找断点 |
subtitle_advanced.hard_max_duration_sec |
6.4 |
4.0~8.0 | 硬时长阈值,超过后必须落断点 |
subtitle_advanced.min_words |
3 |
1~8 | 最小词数要求,避免把一个完整句过早切成一两个词的碎片 |
subtitle_advanced.merge_max_gap_sec |
0.35 |
0.1~0.8 | 短尾句合并时允许的最大间隔 |
subtitle_advanced.merge_max_duration_sec |
6.0 |
3.0~8.0 | 合并后整条字幕允许的最大时长 |
subtitle_advanced.merge_max_chars_ratio |
1.35 |
1.0~1.8 | 合并后字幕最大长度比例 |
subtitle_advanced.merge_max_chars_bias |
24 |
0~40 | 合并后字幕长度补偿值 |
subtitle_advanced.short_tail_max_words |
3 |
1~6 | 认定为“短尾句”的最大词数 |
subtitle_advanced.short_tail_max_chars |
18 |
6~30 | 认定为“短尾句”的最大字符数 |
subtitle_advanced.short_tail_max_duration_sec |
1.4 |
0.5~2.5 | 认定为“短尾句”的最大时长 |
subtitle_advanced.split_max_duration_sec |
6.8 |
4.0~9.0 | 后处理拆分超长字幕时使用的最大时长阈值 |
新版断句器仍然保留内部清理步骤,例如短尾句合并和超长句拆分,但这些属于算法内部流程,不再单独打印后处理日志。
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
max_video_height |
1080 |
720 / 1080 / 1440 / 2160 |
YouTube 下载的最大分辨率 |
ytdlp_client |
"" |
ios / tv_embedded / web / "" |
模拟的 YouTube 客户端类型。ios 和 tv_embedded 有时可绕过 bot 检测;留空则使用默认 web 客户端 |
ytdlp_cookies |
"" |
文件路径或浏览器名 | cookies 配置,支持两种模式(见下方说明):填文件路径如 "./cookies.txt" 使用导出的 cookies 文件;填浏览器名如 "edge" 直接从浏览器读取。留空则不使用 |
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
qwen_api_key |
"" |
— | API Key(必填) |
qwen_base_url |
— | — | API 接口地址,填写所用服务商提供的 base URL |
qwen_model |
"qwen3.5-plus" |
qwen3.5-plus / qwen3.5-turbo / qwen-turbo |
翻译使用的模型 |
translate_batch_size |
50 |
10~100 | 每批翻译的字幕条数,越大越快但易超 token 限制 |
translate_concurrency |
10 |
1~20 | 并发请求批数,受 API QPS 限制 |
api_retry |
3 |
1~10 | 单批翻译失败的最大重试次数 |
api_sleep |
0.5 |
0~2 | 并发批次间的错开抖动上限(秒) |
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
font_size |
20 |
16~28 | 字体大小(像素) |
subtitle_font |
"Microsoft YaHei" |
Microsoft YaHei / SimHei / Arial / Noto Sans CJK SC |
字体名称 |
subtitle_primary_color |
"&H00FFFFFF" |
白色 &H00FFFFFF / 黄色 &H0000FFFF |
字体颜色(ASS 格式:&H + 透明度 + BGR 十六进制) |
subtitle_outline_color |
"&H00000000" |
黑色 &H00000000 |
描边颜色 |
subtitle_outline |
1 |
0=无 / 1=细边 / 2=粗边 |
描边粗细 |
subtitle_shadow |
0 |
0=关闭 / 1=轻阴影 / 2=重阴影 |
阴影偏移距离 |
subtitle_margin_v |
30 |
10~80 | 字幕距视频底部距离(像素),越大越高 |
在 config.json 中通过 tts_provider 选择引擎:
| 取值 | 说明 |
|---|---|
edge |
默认。无需额外密钥,使用微软 Edge 在线 TTS(语音列表) |
qwen_tts |
阿里云 DashScope 多模态 TTS,需配置 qwen_tts_api_key 等 |
cosyvoice |
本地 CosyVoice,首次使用会在 cosyvoice_local/ 自动创建独立环境并下载模型(详见该目录下说明) |
字幕合并(影响每条 TTS 的文本长度):tts_merge_gap_ms、tts_merge_max_chars 对 edge / qwen_tts 生效;使用 CosyVoice 时额外可用 cosyvoice_merge_max_chars。合并越激进,请求次数越少,但单条越长越容易超时或显存压力变大。
CosyVoice 模式 cosyvoice_mode:preset(预设说话人 + cosyvoice_voice)、zero_shot(参考音频 + 参考文案)、cross_lingual(跨语种,依服务端实现而定)。zero_shot 需填写 cosyvoice_prompt_audio_path 与 cosyvoice_prompt_text。可用项目根目录脚本 python generate_qwen_reference.py(需已配置 Qwen TTS)生成与 Cherry 等音色一致的参考 WAV,并自动生成同内容的 .txt 供 prompt 使用。
性能提示:CosyVoice 服务端按设计同一时间只处理一路合成(避免 OOM);cosyvoice_fp16 默认开启以降低显存占用。修改 cosyvoice_device 或与模型相关的配置后,需重启本地 CosyVoice 服务(关闭应用后重开,或自行结束对应进程)。
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
tts_provider |
"edge" |
edge / qwen_tts / cosyvoice |
配音引擎 |
tts_merge_gap_ms |
280 |
— | 相邻字幕若间隔小于此值(毫秒)可合并为一条 TTS |
tts_merge_max_chars |
90 |
— | 合并后单条字幕最大字符数(edge / qwen_tts 路径) |
tts_voice |
"zh-CN-YunjianNeural" |
参见 edge-tts 文档 | edge 下的发音人 |
tts_rate |
"+0%" |
-50% ~ +100% |
TTS 基础语速调整 |
tts_volume |
"+0%" |
-50% ~ +50% |
TTS 音量调整 |
tts_bg_volume |
0.5 |
0.0~1.0 | 背景音混合音量(0=静音,1=原音量) |
tts_max_speed |
1.5 |
1.0~2.0 | 合成语音长于画面对白时段时的最大加速倍率;1.0 表示不加速 |
| 参数 | 默认值 | 说明 |
|---|---|---|
qwen_tts_api_key |
"" |
DashScope API Key(必填) |
qwen_tts_base_url |
官方地址 | 一般无需修改 |
qwen_tts_model |
qwen3-tts-flash |
模型名 |
qwen_tts_voice |
Cherry |
音色名(以 DashScope 文档为准) |
| 参数 | 默认值 | 说明 |
|---|---|---|
cosyvoice_api_url |
http://127.0.0.1:9880 |
HTTP 服务地址 |
cosyvoice_port |
9880 |
与 URL 端口一致即可 |
cosyvoice_mode |
preset |
preset / zero_shot / cross_lingual |
cosyvoice_voice |
中文男 |
preset 模式下的预设说话人名称 |
cosyvoice_prompt_audio_path |
"" |
zero_shot 等模式下参考音频路径 |
cosyvoice_prompt_text |
"" |
与参考音频对应的文案 |
cosyvoice_device |
cpu |
推理设备:cpu / cuda / auto(bootstrap 会据环境选择 PyTorch CUDA/CPU 包) |
cosyvoice_repo_url |
官方 Git | CosyVoice 仓库地址 |
cosyvoice_model_id |
FunAudioLLM/CosyVoice-300M-SFT |
预训练模型 ID |
cosyvoice_ttsfrd_id |
FunAudioLLM/CosyVoice-ttsfrd |
ttsfrd 资源 ID |
cosyvoice_model_source |
auto |
模型下载源 |
cosyvoice_start_timeout |
900 |
首次拉起服务等待就绪的超时(秒) |
cosyvoice_request_timeout |
180 |
单次合成 HTTP 超时(秒) |
cosyvoice_merge_max_chars |
72 |
CosyVoice 路径下合并单条最大字符数 |
cosyvoice_fp16 |
true |
GPU 上是否使用半精度以省显存 |
| 参数 | 默认值 | 可选值 | 说明 |
|---|---|---|---|
enhance_model |
"RealESRGAN_x4plus" |
RealESRGAN_x4plus / RealESRGAN_x4plus_anime_6B / RealESRGAN_x2plus |
超分模型。通用视频用 x4plus;动漫/二次元用 x4plus_anime_6B(更轻量);只需 2x 放大用 x2plus |
enhance_outscale |
4 |
2 / 4 |
放大倍数。输出分辨率超过 4K(3840×2160)时会自动限制 |
模型权重文件(约 64MB)在首次运行时自动从 GitHub Releases 下载,保存在
realesrgan包目录的weights/下。
YouTube 对部分 IP 或视频启用 bot 检测,yt-dlp 会报错 Sign in to confirm you're not a bot,需要配置 cookies 供 yt-dlp 使用。
配置 cookies 的两种模式:
在 config.json 中填写浏览器名称:
"ytdlp_cookies": "edge"支持的浏览器名:edge、chrome、firefox、opera、brave、vivaldi 等。
注意:浏览器运行时 SQLite 数据库被锁,必须关闭浏览器后再运行才能读取成功。
- 在 Chrome / Edge 中安装扩展 Get cookies.txt LOCALLY
- 打开 youtube.com 并确保已登录账号
- 点击扩展图标 → 选择「Export As」→「cookies.txt」
- 将导出的文件保存到项目目录,例如
cookies.txt - 在
config.json中填写路径:"ytdlp_cookies": "./cookies.txt"
- cookies 文件包含账号登录信息,请勿分享或提交到 Git(
config.json已在.gitignore中,cookies 路径只存在于本机config.json里) - 导出的 cookies 文件有效期较短(通常几小时到几天),若下载再次报认证错误,重新导出一次即可。推荐使用模式一(从浏览器自动读取)以免反复导出
- 建议创建一个专用的小号用于导出 cookies,避免主账号暴露
torchaudio 2.10+ 默认依赖 torchcodec 保存音频,而 torchcodec 在 Windows 上需要 FFmpeg full-shared DLLs,通常会报 Could not load libtorchcodec 错误。
解决方案(本项目已内置处理):
- 确保已安装
soundfile:pip install soundfile - 卸载
torchcodec(如已安装):pip uninstall torchcodec - 本项目通过
_run_demucs.py包装脚本自动用soundfile替代torchcodec保存音频,无需手动修改 demucs 源码
- 将
whisper_model改为更小的模型(base或small) - demucs 可通过
--segment参数控制每次处理的音频长度(当前使用默认值)
- 增大
translate_batch_size(每批更多字幕,减少 API 调用次数) - 增大
translate_concurrency(更多并发请求,受 API 限速约束) - 使用更快的模型如
qwen3.5-turbo
- 降低
tts_max_speed(如设为1.2甚至1.0) - 使用 edge 时可将
tts_rate调为负值(如"-10%")减慢基础语速
- 第一次选择
cosyvoice时会克隆仓库、安装独立 venv、下载 SFT 模型与 ttsfrd 资源,耗时与磁盘占用都较大,属正常现象 - 日志在
cosyvoice_local/logs/server.log;若长期无响应可适当增大cosyvoice_start_timeout - NVIDIA 新卡(如需 CUDA 12.8 的驱动环境)由
cosyvoice_local/bootstrap.py安装匹配的 PyTorch cu128 轮子;仅 CPU 则安装 CPU 版 PyTorch,速度较慢
- 保持
cosyvoice_fp16: true,并避免在合成进行时并行多个任务 - 适当减小
cosyvoice_merge_max_chars或tts_merge_max_chars,缩短单次送入模型的文本 - 可在系统环境变量中设置
PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True缓解碎片化(依 PyTorch 版本而定)
- 画质增强仅支持 NVIDIA GPU;请先确认
python -c "import torch; print(torch.cuda.is_available())"输出为True - 如显存不足报 OOM,可在
auto_subtitle.py中将tile_size = 1024改小(如512)
- 这是预期行为:当前版本将 AI 超分限定为 NVIDIA GPU 才可用。
- 没有 GPU 时,请在 Web UI 取消勾选“AI 画质增强”,其他功能不受影响。
basicsr 依赖 lzma,conda 自建环境有时缺少 liblzma.dll:
# 将 base 环境的 DLL 复制到当前环境
Copy-Item "$env:CONDA_PREFIX\..\..\Library\bin\liblzma.dll" "$env:CONDA_PREFIX\Library\bin\"SubForge/
├── auto_subtitle.py # 核心处理脚本(多步流水线入口)
├── app.py # Gradio Web UI
├── settings_ui.py # Web「设置」页(编辑并保存 config.json)
├── config.py # 读取 config.json 的运行时常量
├── config.example.json # 配置模板(复制为 config.json)
├── config.json # 本地配置(已被 .gitignore 忽略)
├── utils.py # 通用工具
├── cosyvoice_manager.py # CosyVoice 本地服务拉起与健康检查
├── generate_qwen_reference.py # 用 Qwen TTS 生成本地参考音色 WAV/TXT(供 CosyVoice zero_shot)
├── _run_demucs.py # demucs 子进程包装(绕过 torchcodec)
├── _run_whisper.py # Whisper 子进程包装
├── steps/ # 各步骤实现(下载、转写、翻译、烧录、配音、增强等)
├── cosyvoice_local/ # CosyVoice 独立环境、vendor、模型(大部份在 .gitignore)
├── requirements.txt # 主依赖(不含 torch 三件套)
├── requirements.cpu.txt # CPU 版 torch
├── requirements.cuda124.txt # CUDA 12.4 版 torch(主项目推荐)
├── environment.yml # conda 一键建环境
├── input/ # 本地视频输入(默认忽略)
└── output/ # 处理结果输出(默认忽略)
MIT