video-dubbing 1.1.0

An AI powered tool to execute end-to-end video dubbing.

Video Dubbing - 视频译配自动化工具

简体中文 | English

Video Dubbing 是一款 AI 驱动的命令行视频译配工具, 可进行语音识别 (ASR)、文本翻译、语音生成 (TTS), 实现端到端视频译配, 并支持批量处理视频文件, 一键生成多语言配音视频.

成品展示:

• CMU15-445 数据库系统导论
• CMU15-721 高级数据库系统
• CS149 并行计算

✨ 功能特性

• 功能全面: ASR → 翻译 → TTS 全链路自动化
  • 高精度语音识别 powered by OpenAI-Whipser
  • 支持使用兼容 OpenAI 的任意 LLM API 进行翻译
  • 基于 Edge-TTS 的高质量语音合成
• 配置高度灵活: 各功能可独立开关, 以用于字幕批量翻译、语音合成等场景
• 丰富的后处理选项: 内置音轨/字幕添加功能, 支持字幕格式自定义
• 批量处理: 支持 glob 匹配, 一键批处理
• 多硬件支持: 支持在 CPU/CUDA/NPU 平台上运行

🚀 快速开始

配置运行环境

要求: Python 3.11, ffmpeg, ffprobe

推荐使用优秀的 Python 环境管理工具 astral-sh/uv

安装 ffmpeg & ffprobe:

• Windows: 下载 此链接 并解压, 将 bin/ffmpeg.exe 和 bin/ffprobe.exe 复制到某个位于 PATH 中的目录
• MacOS: brew install ffmpeg
• Linux: ...

安装 Video Dubbing

按需选择以下安装方式:

最小安装:

适用于无须 ASR, 仅需翻译和 TTS 的场景, 可避免安装 pytorch, pandas 等大型依赖项, 占用空间仅 ~20MB

pip install video-dubbing
# or
uv tool install -p 3.11 video-dubbing # with uv

基础安装:

pip install video-dubbing[asr]
# or
uv tool install -p 3.11 video-dubbing[asr] # with uv

华为 NPU:

pip install video-dubbing[npu]
# or
uv tool install -p 3.11 video-dubbing[npu] # with uv

理论上只要 torch_npu 支持的平台都可以运行, 在 Ascend 910B3 上测试通过, 若你成功在其他平台上运行, 欢迎提交 PR 更新此处.

基础用法

由于配置项较多, 推荐使用配置文件设定大多数配置项. 首先生成默认配置文件:

生成配置文件:

dub -gc # 将在当前目录下生成 config.json, 包含默认配置

而后在执行时, 通过 -c 参数指定配置文件, 并添加其他参数覆盖配置文件中的设置:

加载配置文件:

dub -c config.json # 后加其他命令行参数

示例

示例 1: 批量转译 videos 目录下所有 mp4 文件为中文:

dub -c config.json --input-videos videos/*.mp4 --use-html

示例 2: 批量翻译 subs 目录下的字幕为中文:

dub -c config.json --input-subtitles subs/*.srt --asr False --tts False

⚠️ 注意事项

• 不建议一开始就直接批处理大量文件, 建议先尝试单个文件, 确保配置正确
• 可设置 --debug 及 --log_dir 打开调试模式并保存日志, 以便排查问题
• 上报 Issue 时请提供详细的配置信息及日志, 以便更快定位问题

文件限制:

• 视频文件支持格式取决于 ffmpeg, 常见格式如 mp4, mkv, webm 等均支持
• 字幕文件仅支持 srt 格式, 其他格式可使用 ffmpeg 转换为 srt
• 确保字幕文件编码为 UTF-8, 否则可能导致乱码问题
• 若仅指定视频, 必须开启 ASR; 若仅指定字幕, 无法开启 ASR; 若同时指定, 则二者数量和顺序必须一一对应

NPU 相关:

• 使用 NPU 时, --device 保持为 cuda 即可, 无需修改

LLM 相关:

• --use_html 选项当原文字幕分句良好时推荐开启(即每行都基本以句号结尾), 否则推荐关闭. 使用 whisper 转译英文视频生成的字幕一般都符合此要求.

⚙️ 全部配置参数

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        加载 JSON 或 YAML 格式的配置文件 (default: None)
  -gc, --gen-config     生成默认配置文件 (default: False)
  -v, --version         show program's version number and exit

General:
  --input_videos INPUT_VIDEOS [INPUT_VIDEOS ...], --input-videos INPUT_VIDEOS [INPUT_VIDEOS ...]
                        待处理的视频文件 (default: [])
  --input_subtitles INPUT_SUBTITLES [INPUT_SUBTITLES ...], --input-subtitles INPUT_SUBTITLES [INPUT_SUBTITLES ...]
                        待处理的字幕文件 (srt 格式) (default: [])
  --output_dir OUTPUT_DIR, --output-dir OUTPUT_DIR
                        输出目录. 留空则使用输入文件所在目录 (default: None)
  --asr [ASR]           语音识别开关 (default: True)
  --translate [TRANSLATE]
                        翻译开关 (default: True)
  --tts [TTS]           语音合成开关 (default: True)
  --debug [DEBUG]       调试模式 (default: False)
  --log_dir LOG_DIR, --log-dir LOG_DIR
                        日志目录, 若为空则不保存 (default: None)

ASR:
  --model MODEL         whisper 模型型号 (default: turbo)
  --model_dir MODEL_DIR, --model-dir MODEL_DIR
                        whisper 模型存储目录 (default: None)
  --device DEVICE       用于运行 ASR 相关模型的硬件设备 (default: cuda)
  --align [ALIGN]       进行词汇对齐 (default: False)
  --diarize [DIARIZE]   进行说话者分离 (default: False)
  --hf_token HF_TOKEN, --hf-token HF_TOKEN
                        Hugging Face token. 用于下载需同意用户协议的某些模型 (default: )

Translate:
  --target_lang TARGET_LANG, --target-lang TARGET_LANG
                        目标语言 (default: 简体中文)
  --base_url BASE_URL, --base-url BASE_URL
                        LLM API 地址 (default: https://api.openai.com/v1)
  --api_key API_KEY, --api-key API_KEY
                        LLM API key (default: )
  --llm_model LLM_MODEL, --llm-model LLM_MODEL
                        LLM 模型 (default: )
  --use_html [USE_HTML], --use-html [USE_HTML]
                        使用 HTML 标记请求多行翻译. 当字幕分句良好时推荐开启, 否则推荐关闭 (default: False)
  --remove_ellipsis [REMOVE_ELLIPSIS], --remove-ellipsis [REMOVE_ELLIPSIS]
                        移除字幕行尾的省略号 (default: False)
  --llm_req_rate LLM_REQ_RATE, --llm-req-rate LLM_REQ_RATE
                        LLM 请求速率 (r/s) (default: 5)
  --batch_size BATCH_SIZE, --batch-size BATCH_SIZE
                        单次请求 LLM 翻译的最大行数. 过大会提高失败率 (default: 10)

TTS:
  --voice VOICE         TTS 声音. 参考 https://gist.github.com/BettyJJ/17cbaa1de96235a7f5773b8690a20462 (default: zh-CN-YunyangNeural)
  --tts_req_rate TTS_REQ_RATE, --tts-req-rate TTS_REQ_RATE
                        TTS 请求速率 (r/10s) (default: 3)
  --audio_format AUDIO_FORMAT, --audio-format AUDIO_FORMAT
                        音频输出格式 (default: aac)
  --add_track [ADD_TRACK], --add-track [ADD_TRACK]
                        添加 TTS 音频到视频 (default: True)
  --track_title TRACK_TITLE, --track-title TRACK_TITLE
                        TTS 音轨标题. 默认使用 voice 名称 (default: None)

Subtitle:
  --soft [SOFT]         添加字幕方式 (True: 软 / False: 硬) (目前仅支持软字幕) (default: True)
  --add_asr_sub [ADD_ASR_SUB], --add-asr-sub [ADD_ASR_SUB]
                        将语音识别字幕添加到视频 (default: True)
  --asr_sub_title ASR_SUB_TITLE, --asr-sub-title ASR_SUB_TITLE
                        语音识别字幕标题 (default: None)
  --asr_sub_style ASR_SUB_STYLE, --asr-sub-style ASR_SUB_STYLE
                        语音识别字幕样式. 参考 https://github.com/yuanshanhua/video-dubbing/blob/main/docs/subtitle_style_zh.md (default: None)
  --add_trans_sub [ADD_TRANS_SUB], --add-trans-sub [ADD_TRANS_SUB]
                        将译文字幕添加到视频 (default: True)
  --trans_sub_title TRANS_SUB_TITLE, --trans-sub-title TRANS_SUB_TITLE
                        译文字幕标题 (default: None)
  --trans_sub_style TRANS_SUB_STYLE, --trans-sub-style TRANS_SUB_STYLE
                        译文字幕样式 (default: None)
  --add_bilingual_sub [ADD_BILINGUAL_SUB], --add-bilingual-sub [ADD_BILINGUAL_SUB]
                        将双语字幕添加到视频 (default: True)
  --bilingual_sub_title BILINGUAL_SUB_TITLE, --bilingual-sub-title BILINGUAL_SUB_TITLE
                        双语字幕标题 (default: None)
  --bilingual_sub_style BILINGUAL_SUB_STYLE, --bilingual-sub-style BILINGUAL_SUB_STYLE
                        双语字幕样式 (default: None)

🙏 致谢

本项目基于以下优秀开源项目:

• OpenAI-Whisper
• FFmpeg
• whisperX
• edge-tts
• aiolimiter