README.md

metadata

title: Universal Fast Dubbing
emoji: 🎬
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

🎬 Universal Fast Dubbing v3.0

全网通用AI配音插件 - 支持YouTube、Bilibili、Netflix、TikTok等全平台视频

功能特点

• 🎯 智能语音识别: 基于 Whisper V3 的高精度语音转文字
• 🌐 多语言翻译: 使用 Llama 3 进行智能翻译和角色识别
• 🎤 自然语音合成: Edge-TTS / SiliconFlow 高质量配音
• ⚡ 音画同步对齐: 精确到 ±0.3秒 的音频同步
• 🚀 双模式支持: URL直接处理 + 录制模式

支持平台

平台	URL模式	录制模式
YouTube	✓	✓
Bilibili	✓	✓
Netflix	✗	✓
TikTok	✓	✓
Twitter/X	✓	✓

快速开始

1. 配置 API 密钥

在 Space Settings 中添加以下 Secrets：

# 必需（二选一或同时配置）
GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxx
SILICONFLOW_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 可选配置
API_PROVIDER=auto  # auto, groq, siliconflow
TTS_PROVIDER=edge-tts  # edge-tts, siliconflow

2. 使用 Web 界面

1. 选择处理模式（自动检测/URL/录制）
2. 输入视频URL 或 上传录制的音频
3. 点击"开始配音"按钮
4. 等待处理完成，下载配音结果

3. 配合 Chrome 扩展使用

安装配套的 Chrome 扩展，可以直接在视频网站上一键配音：

1. 下载扩展代码
2. 在 Chrome 中加载 extension/ 文件夹
3. 配置后端地址为此 Space 的 URL
4. 在视频页面点击扩展图标开始配音

API 使用

配音处理 API

import requests

# 处理视频URL
response = requests.post(
    "https://your-space.hf.space/api/process",
    json={
        "mode": "url",
        "url": "https://www.youtube.com/watch?v=xxxxx"
    }
)

result = response.json()
audio_url = result["audio_url"]

获取系统状态

response = requests.get("https://your-space.hf.space/api/status")
status = response.json()
print(f"系统健康: {status['healthy']}")
print(f"内存使用: {status['performance']['memory_mb']} MB")

获取后端配置

response = requests.get("https://your-space.hf.space/api/config")
config = response.json()
print(f"API提供商: {config['api_provider']}")
print(f"TTS提供商: {config['tts_provider']}")

技术架构

后端技术栈

• Web框架: FastAPI + Uvicorn
• 模板引擎: Jinja2 + Tailwind CSS
• 语音识别: Groq Whisper V3 / SiliconFlow SenseVoice
• 翻译引擎: Groq Llama 3
• 语音合成: Edge-TTS / SiliconFlow (Fish Speech, CosyVoice2, MOSS-TTSD)
• 音频处理: FFmpeg + Pydub + Librosa
• 视频下载: yt-dlp

处理流程

标准处理流程

视频URL/录制音频
    ↓
音频提取 (yt-dlp / 直接上传)
    ↓
语音识别 (Whisper V3 带时间戳)
    ↓
翻译 + 角色识别 (Llama 3)
    ↓
语音合成 (Edge-TTS / SiliconFlow)
    ↓
音频同步对齐 (时间戳匹配)
    ↓
配音音频输出

流式异步处理流程 (v3.1 新增)

扩展点击AI配音
    ↓
Native Host 下载音频 (yt-dlp)
    ↓
扩展端上传到 HF 后端
    ↓
SSE 流式处理 ←──────────────────┐
    ↓                           │
语音识别 (Whisper V3 带时间戳)   │ 实时进度反馈
    ↓                           │
按时间戳智能分段                  │
    ↓                           │
┌─────────────────────────────┐ │
│ 并行处理每段:                │ │
│   翻译 (Llama 3)            │ │
│   → TTS (Edge-TTS)          │ │
│   → 音频同步对齐             │ │
│   → 分段音频输出 ────────────┼─┘
└─────────────────────────────┘
    ↓
第一段完成即开始播放 (目标 <30秒)
    ↓
隐藏遮罩，视频从头播放

流式处理优势:

• 首段配音 30 秒内开始播放
• 实时进度反馈，用户体验更好
• 分段并行处理，整体速度更快
• SSE 连接稳定，兼容 HF Spaces 代理

配置说明

API 提供商选择

Groq (推荐用于精确时间戳)

• 优势: Whisper V3 带精确时间戳，免费额度充足
• 限制: 每分钟 20 次 ASR 请求
• 获取: console.groq.com

GROQ_API_KEY=your_key
API_PROVIDER=groq
TTS_PROVIDER=edge-tts

SiliconFlow (推荐用于高质量中文TTS)

• 优势: 多种高质量 TTS 模型，支持多角色对话
• 限制: ASR 无时间戳（需后处理）
• 获取: cloud.siliconflow.cn

SILICONFLOW_API_KEY=your_key
API_PROVIDER=siliconflow
TTS_PROVIDER=siliconflow
SILICONFLOW_TTS_MODEL=fishaudio/fish-speech-1.5

混合模式 (最佳质量)

GROQ_API_KEY=your_groq_key
SILICONFLOW_API_KEY=your_sf_key
API_PROVIDER=groq  # ASR 用 Groq
TTS_PROVIDER=siliconflow  # TTS 用 SiliconFlow
SILICONFLOW_TTS_MODEL=FunAudioLLM/CosyVoice2-0.5B

性能优化配置

# 启用低码率音频（加速处理）
USE_LOW_QUALITY_AUDIO=true

# 并发处理数（根据硬件调整）
MAX_CONCURRENT_WORKERS=3

# 缓存时长（秒）
CACHE_DURATION=3600

# 最大同时会话数
MAX_SESSIONS=10

限制说明

• 视频时长: 建议 15 分钟以内
• 同步精度: ±0.3 秒
• 支持语言: 英语、日语 → 中文
• 并发处理: 根据硬件配置自动调整

常见问题

Q: 为什么某些网站不支持 URL 模式？

A: Netflix、Amazon Prime 等平台有 DRM 保护，无法直接下载音频。请使用录制模式。

Q: 如何提高处理速度？

A:

1. 启用 USE_LOW_QUALITY_AUDIO=true
2. 减少并发数 MAX_CONCURRENT_WORKERS=2
3. 处理较短的视频片段

Q: API 调用失败怎么办？

A:

1. 检查 API Key 是否正确配置
2. 确认账户配额未用尽
3. 尝试切换 API_PROVIDER 到另一个提供商

Q: 音频同步不准确？

A:

1. 确保使用 Groq Whisper V3（带时间戳）
2. 检查原视频音频质量
3. 调整 SYNC_THRESHOLD 参数

项目结构

universal-fast-dubbing/
├── app.py                   # FastAPI 主入口
├── Dockerfile               # Docker 构建配置
├── DEPLOYMENT.md            # 部署说明
│
├── backend/                 # Python 后端模块
│   ├── requirements.txt     # Python 依赖
│   ├── packages.txt         # 系统依赖 (ffmpeg)
│   ├── modules/             # 核心处理模块
│   │   ├── gateway.py       # API 网关
│   │   ├── groq_client.py   # Groq API 客户端 (ASR + LLM)
│   │   ├── siliconflow_client.py  # SiliconFlow 客户端
│   │   ├── stream_processor.py    # 流式异步处理器 (v3.1)
│   │   ├── processor.py     # 配音处理器
│   │   ├── segmenter.py     # 音频分段器
│   │   ├── tts_generator.py # Edge-TTS 生成器
│   │   ├── audio_sync.py    # 音频同步引擎
│   │   ├── router.py        # API 路由
│   │   ├── logging_config.py # 结构化日志
│   │   ├── performance_monitor.py # 性能监控
│   │   └── errors.py        # 统一错误处理
│   └── temp/                # 临时文件目录
│
├── templates/               # Jinja2 模板
│   └── index.html           # Web 界面
│
├── static/                  # 静态资源
│   └── style.css            # Tailwind CSS
│
├── extension/               # Chrome 扩展
│   ├── manifest.json        # 扩展配置 (Manifest V3)
│   ├── background/          # Background Service Worker
│   │   └── background.js    # 消息处理、Native Messaging
│   ├── content/             # Content Scripts
│   │   └── dubbing-ui.js    # 视频页面 UI 注入
│   ├── popup/               # Popup 界面
│   ├── options/             # 设置页面
│   └── icons/               # 扩展图标
│
└── local_audio_service/     # Native Host 服务
    ├── native_host.js       # Node.js Native Messaging Host
    ├── native_host.bat      # Windows 启动脚本
    ├── install.bat          # 注册表安装脚本
    ├── com.ufd.native.json  # Native Host 配置
    └── yt-dlp.exe           # 视频下载工具

开发指南

本地开发

# 克隆项目
git clone <your-repo-url>
cd universal-fast-dubbing/backend

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入 API 密钥

# 启动服务
python app.py

部署到 Hugging Face Spaces

1. Fork 本项目
2. 在 HF 创建新 Space，选择 Gradio SDK
3. 连接 Git 仓库或上传文件
4. 在 Settings 中配置 Secrets（API 密钥）
5. 等待构建完成

详细部署说明请查看 DEPLOYMENT.md

性能监控

系统内置性能监控，可在"系统状态"标签页查看：

• 内存使用: 实时内存占用
• CPU使用率: 处理器负载
• 成功率: API调用成功率
• 活跃会话: 当前处理中的任务数
• 缓存统计: 缓存命中率

许可证

MIT License

致谢

• Groq - 提供高速 LPU 推理
• SiliconFlow - 提供多样化 AI 模型
• Edge-TTS - 微软 Edge 语音合成
• yt-dlp - 视频下载工具
• Gradio - Web 界面框架

技术支持

如遇到问题，请：

1. 查看"系统状态"标签页的错误信息
2. 检查 Space Logs 中的详细日志
3. 提交 Issue 并附上错误信息

---

注意: 本项目仅供学习和研究使用，请遵守各视频平台的服务条款。