Skip to content

scwf/open-dubbing

BranchesTags

Repository files navigation

AI配音工具

📖 项目介绍

AI配音工具是一个专业的AI语音克隆配音解决方案，通过先进的TTS模型将SRT字幕文件或TXT文本转换为高质量的配音音频。工具支持多种时间同步策略，能够精确匹配字幕时长，生成与视频完美同步的配音。

主要特性

  • 🎯 精确同步: 支持时间拉伸策略，确保配音与字幕时长完全匹配
  • 🎨 高质量音频: 基于Fish-speech\IndexTTS2\CosyVoice\F5等模型，生成自然流畅的语音
  • ⚙️ 灵活策略: 提供基础策略和拉伸策略，适应不同需求
  • 🎭 情感控制: IndexTTS2引擎支持情感表达控制，可通过音频、向量、文本等方式调节语音情感
  • ✨ 图形化界面: 提供直观易用的 Web UI，支持文件拖拽上传、参数在线配置和实时进度展示，极大简化了操作流程。
  • 📊 实时监控: 专业日志系统，实时显示处理进度和状态

🎬 演示视频

点击查看演示视频

🏗️ 项目架构

open-dubbing/
├── run.sh                        # 一键部署启动（默认 index-tts2，安装 + 启动 Web UI）
├── install-index-tts2.sh         # IndexTTS2 环境安装脚本
├── install-fish-speech.sh        # Fish Speech 环境安装脚本
├── install-f5-tts.sh             # F5-TTS 环境安装脚本
├── install-cosyvoice.sh          # CosyVoice 环境安装脚本
├── test-index-tts2.sh            # IndexTTS2 引擎冒烟测试
├── test-fish-speech.sh           # Fish Speech 引擎冒烟测试
├── test-f5-tts.sh                # F5-TTS 引擎冒烟测试
├── test-cosyvoice.sh             # CosyVoice 引擎冒烟测试
├── server.py                     # Web UI 服务入口（FastAPI）
├── requirements.txt              # 主项目 Python 依赖
├── .gitmodules                   # Git submodule 配置
├── deps/                         # 第三方引擎源码（Git submodule，固定 commit）
│   ├── index-tts/                # IndexTTS2 上游源码
│   ├── fish-speech/              # Fish Speech 上游源码
│   └── CosyVoice/                # CosyVoice 上游源码
├── models/                       # 模型权重缓存（.gitignore，由 install-*.sh 下载）
├── resources/                    # 静态资源（演示视频、Web UI 截图等）
│   └── reference_voices/         # 内置参考音频（name.ext + name.txt 成对存放）
├── ai_dubbing/
│   ├── run_dubbing.py            # [入口] CLI 配音任务（命令行参数）
│   ├── run_optimize_subtitles.py # [入口] 字幕优化（仅改文本，不合成音频）
│   ├── validate_durations.py     # 字幕时长校验工具
│   ├── dubbing.conf.example      # 配置文件模板
│   ├── web/                      # Web UI 前端
│   │   ├── static/               # CSS、JavaScript
│   │   └── templates/            # HTML 模板
│   ├── test/                     # 单元测试
│   └── src/
│       ├── config.py             # 各引擎与全局配置
│       ├── logger.py             # 日志系统
│       ├── audio_processor.py    # 音频后处理
│       ├── parsers/              # SRT / TXT 解析
│       ├── strategies/           # 时间同步策略（basic / stretch）
│       ├── optimizer/            # 字幕文本优化（LLM）
│       ├── tts_engines/          # TTS 引擎适配层
│       │   ├── index_tts2_engine.py
│       │   ├── fish_speech_engine.py
│       │   ├── f5_tts_engine.py
│       │   └── cosy_voice_engine.py
│       └── utils/                # 公共工具（路径、环境初始化等）
├── skills/
│   └── subtitle-voice-dubbing/   # Agent Skill（供 AI Agent 调用本仓库配音能力）
│       ├── SKILL.md
│       └── reference.md
└── README.md

说明：

  • deps/：三个引擎通过 Git submodule 锁定上游 commit；F5-TTS 无 submodule，由 pip install f5-tts 提供。
  • models/：已在 .gitignore 中，不纳入版本库；运行对应 install-*.sh 后自动下载到该目录。
  • skills/：面向 AI Agent 的平台无关技能包（见下方 Agent Skill）；SKILL.md 定义配音工作流，reference.md 提供引擎、参数与故障排查等延伸阅读。
  • 运行方式：Web UI（server.py / run.sh）与 CLI（run_dubbing.py）共用同一套 src/ 逻辑。

🚀 快速开始

获取源码

本项目依赖以下第三方源码仓库，并且固定到经过验证的 commit，不跟随上游最新版本漂移：

路径 上游仓库 固定 commit 对应运行模型
deps/CosyVoice https://github.com/FunAudioLLM/CosyVoice ace7c47f41bbd303aa6bf1ea80e6f9fbd595cd40 Fun-CosyVoice3-0.5B
deps/fish-speech https://github.com/fishaudio/fish-speech d3df50503b36314a964f66cac1af1e19e95bcfa3 openaudio-s1-mini
deps/index-tts https://github.com/index-tts/index-tts db5b39bb6ad903c219b2dd33d60b0f0bdaede664 IndexTTS-2

推荐使用带 submodule 的方式克隆：

git clone --recursive git@github.com:scwf/open-dubbing.git
cd open-dubbing

如果在克隆过程中遇到 deps/index-tts 的 Git LFS 下载失败（例如上游 LFS 配额临时超限），可以临时跳过 LFS smudge：

Windows PowerShell:

$env:GIT_LFS_SKIP_SMUDGE=1
git clone --recursive git@github.com:scwf/open-dubbing.git
cd open-dubbing

Linux / macOS:

GIT_LFS_SKIP_SMUDGE=1 git clone --recursive git@github.com:scwf/open-dubbing.git
cd open-dubbing

如果已经 clone 过主仓库，再执行一次：

git submodule update --init --recursive

说明：

  • 安装脚本只会初始化仓库中已经锁定的 submodule 版本，不会自动拉取上游最新源码
  • 如果未初始化 submodule，请先执行上面的命令，再运行各引擎安装脚本

一键部署运行（推荐，本地人工运行场景）

项目提供了 run.sh 一键部署脚本，可以自动完成环境配置、依赖安装、模型下载和服务启动：

./run.sh

脚本功能：

  • 🔧 自动创建和激活 index-tts2 Conda 环境
  • 📦 安装所有必需的依赖包（包括 FFmpeg、PyTorch 等）
  • 🔗 初始化并安装已锁定版本的 IndexTTS2 引擎
  • 📥 下载预训练模型
  • ⚙️ 自动生成配置文件
  • 🌐 启动 Web UI 服务器

执行完成后，服务将在 http://127.0.0.1:8000 运行，您可以直接在浏览器中开始使用。

手动环境配置

项目为每个 TTS 引擎提供了独立的安装脚本，您可以根据需要选择安装：

IndexTTS2 引擎（推荐）

默认使用模型：IndexTTS-2

./install-index-tts2.sh

Fish Speech 引擎

默认使用模型：openaudio-s1-mini

./install-fish-speech.sh

F5-TTS 引擎

默认使用模型：F5TTS_v1_Base

./install-f5-tts.sh

CosyVoice 引擎

默认使用模型：Fun-CosyVoice3-0.5B

./install-cosyvoice.sh

安装后启动服务：

每个 TTS 引擎使用独立的 conda 环境，使用哪个引擎需激活对应环境：

# Fish Speech 引擎
conda activate fish-speech

# IndexTTS2 引擎  
conda activate index-tts2

# F5-TTS 引擎
conda activate f5-tts

# CosyVoice 引擎
conda activate cosyvoice

注意：在 Web UI 中记得将 TTS 引擎设置为对应的引擎类型（fish_speech、index_tts2、f5_tts、cosy_voice）。

📝 使用说明

💻 Web UI 交互界面

为了提供更直观、便捷的操作体验，项目内置了一个基于 FastAPI 的 Web 界面。

启动 Web 服务

在项目根目录下运行以下命令：

# 激活对应python环境后运行如下命令
python server.py

服务启动后，在浏览器中打开 http://127.0.0.1:8000 即可访问。

界面功能概览

AI Dubbing Web UI

Web UI 主要分为以下几个功能区域：

  1. 文件上传区：

    • SRT/TXT 文件：上传您的主字幕文件。
    • 参考音频：点击“添加参考音频”按钮，可以添加一个或多个参考音频-文本对。每个参考音频都需要一段对应的文本，用于声音克隆。

  2. 配置选项：

    • TTS 引擎：选择用于语音合成的核心模型，如 fish_speech。
    • 策略：选择音频与字幕的时间同步策略，如 stretch 策略会严格匹配时长。
    • 语言：选择字幕对应的语言。

  3. 高级配置：

    • 提供对 并发数、字幕优化、时间借用 等高级参数的精细调整。
    • IndexTTS2 情感控制：当选择 index_tts2 引擎时，会显示专门的情感控制面板，支持以下能力：
      • 情感模式：自动分析、音频提示、情感向量、文本描述四种模式。
      • 情感强度：可调节情感表达的强烈程度（0.0-1.0）。
      • 随机采样：增加语音的自然变化。
    • 所有配置修改后，可点击 “保存配置” 将其写入 dubbing.conf 文件，便于 Web 端或其他配置文件流程复用。

  4. 开始处理：

    • 所有参数设置完毕后，点击 “开始配音” 按钮启动任务。
    • 处理过程中，页面会实时显示任务进度。完成后，会提供最终音频文件的下载链接。

python脚本方式运行模式(给第三方程序调用或者AI Agent调用)

Agent Skill

skills/subtitle-voice-dubbing/ 是本仓库内置的 Agent Skill，供 Cursor、Claude Code 等 AI Agent 按结构化流程调用配音能力（默认走 CLI，而非 Web UI）。

文件 用途
skills/subtitle-voice-dubbing/SKILL.md 主技能文档：触发条件、仓库根目录约定、用户交互工作流（获取字幕 → 选参考音 → 选引擎 → 执行 → 交付）
skills/subtitle-voice-dubbing/reference.md 延伸阅读：各平台挂载方式、Conda 环境、CLI 参数、内置参考音、故障排查

使用方式：

  • 随仓库使用：Clone 后让 Agent 阅读 skills/subtitle-voice-dubbing/SKILL.md 即可执行配音；所有 shell 命令须在 open-dubbing 仓库根目录 下运行（Skill 内以 <REPO_ROOT> 表示）。
  • 复制到平台技能目录（可选）：可将 skills/subtitle-voice-dubbing/ 复制或链接到 Cursor 的 .cursor/skills/、Claude Code 的技能目录等，便于自动发现；配音命令仍须在 clone 出的 open-dubbing 根目录执行，与 Skill 文件物理位置无关。
  • 通用引用：在 system prompt 或工具说明中加入：请先阅读 <repo>/skills/subtitle-voice-dubbing/SKILL.md，再执行配音任务。

Skill 设计遵循仓库内的 Agent Skill 黄金法则与最佳实践。详细平台配置见 skills/subtitle-voice-dubbing/reference.md 的「在 Agent 平台中使用」一节。

1. 直接传入命令行参数

先激活对应的 Python / Conda 环境。默认命令行示例基于 index-tts2 环境：

conda activate index-tts2

环境和引擎映射如下：

TTS 引擎参数 Conda 环境 默认模型
index_tts2 index-tts2 IndexTTS-2
fish_speech fish-speech openaudio-s1-mini
f5_tts f5-tts F5TTS_v1_Base
cosy_voice cosyvoice Fun-CosyVoice3-0.5B

如果你要切换到其他引擎，请先激活上表对应环境，再执行下面的命令。

python ai_dubbing/run_dubbing.py \
  --input-file "subtitles/movie.srt" \
  --output-file "output/movie_dubbed.wav"

常用参数说明：

--input-file             输入文件路径（SRT 或 TXT，必填）
--output-file            输出音频文件路径（必填）
--voice-files            参考音频列表；默认 resources/reference_voices/mcs.mp3
--prompt-texts           参考文本列表；默认读取 resources/reference_voices/mcs.txt
--tts-engine             可选：index_tts2, fish_speech, f5_tts, cosy_voice；默认 index_tts2
--strategy               可选：stretch, basic；未传时自动选择（SRT=stretch，TXT=basic）
--emotion-text           IndexTTS2 文本情感描述，默认“平静”
--emotion-alpha          IndexTTS2 情感强度，默认 0.5

如果你要覆盖默认参考音频/文本，可以这样传：

python ai_dubbing/run_dubbing.py \
  --input-file "subtitles/movie.srt" \
  --output-file "output/movie_dubbed.wav" \
  --voice-files "voices/ref1.wav" "voices/ref2.mp3" \
  --prompt-texts "这是第一段参考音频文本" "这是第二段参考音频文本" \
  --tts-engine index_tts2 \
  --emotion-text "平静、克制" \
  --emotion-alpha 0.5

策略默认会按输入类型自动决定：

SRT / 字幕文件 -> stretch
TXT / 纯文本文件 -> basic

IndexTTS2启动注意事项

需要注意的是，社区版 index-tts 在加载 w2v-bert、MaskGCT、campplus、bigvgan 等辅助依赖时，会使用相对路径 ./checkpoints/hf_cache 作为缓存目录。因此必须先切换到预期的工作目录，否则这些缓存可能会落到当前目录对应的 ./checkpoints/hf_cache 下，并触发重复下载。

推荐写法：

cd /path/to/open-dubbing
python ai_dubbing/run_dubbing.py \
  --input-file "/mnt/c/path/to/input.srt" \
  --output-file "/mnt/c/path/to/output.wav"

如果从 Windows 侧调用 wsl.exe，也建议显式先 cd：

wsl.exe -e bash -lc "cd /path/to/open-dubbing && conda run -n index-tts2 --no-capture-output python ai_dubbing/run_dubbing.py --input-file /mnt/c/path/to/input.srt --output-file /mnt/c/path/to/output.wav"

其他附属功能：仅优化字幕（不合成音频）

python ai_dubbing/run_optimize_subtitles.py

其他附属功能：校验字幕时长

python ai_dubbing/validate_durations.py "subtitles/movie.srt"

About

🎙️ AI Dubbing Tool - Professional Voice Cloning & Synchronization: Transform your subtitles into high-quality dubbed audio using cutting-edge TTS models.

Resources

Readme
Activity

Stars

14 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages