# 数字人口播视频生成系统 - 实现计划

## 项目目标

构建一个开源的数字人口播视频生成系统，功能包括：
- 上传静态人物视频 → 生成口播视频（唇形同步）
- TTS 配音或声音克隆
- 字幕自动生成与渲染
- AI 自动生成标题与标签
- 一键发布到多个社交平台

---

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                    前端 (Next.js)                        │
│         素材管理 | 视频生成 | 发布管理 | 任务状态         │
└─────────────────────────────────────────────────────────┘
                            │ REST API
                            ▼
┌─────────────────────────────────────────────────────────┐
│                   后端 (FastAPI)                         │
├─────────────────────────────────────────────────────────┤
│  异步任务队列 (asyncio)                                 │
│  ├── 视频生成任务                                        │
│  ├── TTS 配音任务                                        │
│  └── 自动发布任务                                        │
└─────────────────────────────────────────────────────────┘
        │               │               │
        ▼               ▼               ▼
  ┌──────────┐   ┌──────────┐   ┌──────────┐
  │LatentSync│   │  FFmpeg  │   │Playwright│
  │ 唇形同步  │   │ 视频合成  │   │ 自动发布  │
  └──────────┘   └──────────┘   └──────────┘
```

---

## 技术选型

| 模块 | 技术选择 | 备选方案 |
|------|----------|----------|
| **前端框架** | Next.js 16 | Vue 3 + Vite |
| **UI 组件库** | TailwindCSS (自定义组件) | Ant Design |
| **后端框架** | FastAPI | Flask |
| **任务队列** | FastAPI BackgroundTasks (asyncio) | Celery + Redis |
| **唇形同步** | **LatentSync 1.6** | MuseTalk / Wav2Lip |
| **TTS 配音** | EdgeTTS | CosyVoice |
| **声音克隆** | **Qwen3-TTS 1.7B** ✅ | GPT-SoVITS |
| **视频处理** | FFmpeg | MoviePy |
| **自动发布** | Playwright | 自行实现 |
| **数据库** | Supabase (PostgreSQL) | MySQL |
| **文件存储** | Supabase Storage | 阿里云 OSS |

> **修正 (18:10)**：当前实现采用 Next.js 16、FastAPI BackgroundTasks 与 Supabase Storage/Auth，自动发布基于 Playwright。

---

## ✅ 现状补充 (Day 17)

- 前端已拆分为组件化结构（`features/home/ui/`），主页面逻辑集中。
- 通用工具 `media.ts` 统一处理 API Base / 资源 URL / 日期格式化。
- 作品预览弹窗统一样式，并支持素材/发布预览复用。
- 标题/字幕预览按素材分辨率缩放，效果更接近成片。

---

## 分阶段实施计划

### 阶段一：核心功能验证 (MVP)

> **目标**：验证 LatentSync + EdgeTTS 效果，跑通端到端流程

#### 1.1 环境搭建

参考 `models/LatentSync/DEPLOY.md` 完成 LatentSync 环境与权重部署。

#### 1.2 集成 EdgeTTS

```python
# tts_engine.py
import edge_tts
import asyncio

async def text_to_speech(text: str, voice: str = "zh-CN-YunxiNeural", output_path: str = "output.mp3"):
    communicate = edge_tts.Communicate(text, voice)
    await communicate.save(output_path)
    return output_path
```

#### 1.3 端到端测试脚本

```python
# test_pipeline.py
"""
1. 文案 → EdgeTTS → 音频
2. 静态视频 + 音频 → LatentSync → 口播视频
3. 添加字幕 → FFmpeg → 最终视频
"""
```

#### 1.4 验证标准
- [ ] LatentSync 能正常推理
- [ ] 唇形与音频同步率 > 90%
- [ ] 单个视频生成时间 < 2 分钟

---

### 阶段二：后端 API 开发

> **目标**：将核心功能封装为 API，支持异步任务

#### 2.1 项目结构

```
backend/
├── app/
│   ├── main.py              # FastAPI 入口
│   ├── api/
│   │   ├── videos.py        # 视频生成 API
│   │   ├── materials.py     # 素材管理 API
│   │   └── publish.py       # 发布管理 API
│   ├── services/
│   │   ├── tts_service.py   # TTS 服务
│   │   ├── lipsync_service.py  # 唇形同步服务
│   │   └── video_service.py    # 视频合成服务
│   ├── tasks/
│   │   └── celery_tasks.py  # Celery 异步任务
│   ├── models/
│   │   └── schemas.py       # Pydantic 模型
│   └── core/
│       └── config.py        # 配置管理
├── requirements.txt
└── docker-compose.yml       # Redis + API
```

#### 2.2 核心 API 设计

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/materials` | POST | 上传视频素材 | ✅ |
| `/api/materials` | GET | 获取素材列表 | ✅ |
| `/api/videos/generate` | POST | 创建视频生成任务 | ✅ |
| `/api/videos/tasks/{id}` | GET | 查询任务状态 | ✅ |
| `/api/videos/generated` | GET | 获取历史作品列表 | ✅ |
| `/api/publish` | POST | 发布到社交平台 | ✅ |

#### 2.3 BackgroundTasks 任务定义

```python
# app/api/videos.py
background_tasks.add_task(_process_video_generation, task_id, req, user_id)
```

---

### 阶段三：前端 Web UI

> **目标**：提供用户友好的操作界面

#### 3.1 页面设计

| 页面 | 功能 |
|------|------|
| **素材库** | 上传/管理多场景视频素材 |
| **生成视频** | 输入文案、选择素材、生成预览 |
| **任务中心** | 查看生成进度、下载视频 |
| **发布管理** | 绑定平台、一键发布、定时发布 |

#### 3.2 技术实现

```bash
# 创建 Next.js 项目
npx create-next-app@latest frontend --typescript --tailwind --app

# 安装依赖
cd frontend
npm install axios swr
```

---

### 阶段四：社交媒体发布

> **目标**：集成 social-auto-upload，支持多平台发布

#### 4.1 复用 social-auto-upload

```bash
# 复制模块
cp -r SuperIPAgent/social-auto-upload backend/social_upload
```

#### 4.2 Cookie 管理

```python
# 用户通过浏览器登录 → 保存 Cookie → 后续自动发布
```

#### 4.3 支持平台
- 抖音
- 小红书
- 微信视频号
- 快手

---

### 阶段五：优化与扩展

| 功能 | 实现方式 |
|------|----------|
| **声音克隆** | 集成 GPT-SoVITS，用自己的声音 |
| **AI 标题/标签生成** | 调用大模型 API 自动生成标题与标签 ✅ |
| **批量生成** | 上传 Excel/CSV，批量生成视频 |
| **字幕编辑器** | 可视化调整字幕样式、位置 |
| **Docker 部署** | 一键部署到云服务器 | ✅ |

---

### 阶段六：MuseTalk 服务器部署 (Day 2-3) ✅

> **目标**：在双显卡服务器上部署 MuseTalk 环境

- [x] Conda 环境配置 (musetalk)
- [x] 模型权重下载 (~7GB)
- [x] Subprocess 调用方式实现
- [x] 健康检查功能

### 阶段七：MuseTalk 完整修复 (Day 4) ✅

> **目标**：解决推理脚本的各种兼容性问题

- [x] 权重检测路径修复 (软链接)
- [x] 音视频长度不匹配修复
- [x] 推理脚本错误日志增强
- [x] 视频合成 MP4 生成验证

### 阶段八：前端功能增强 (Day 5) ✅

> **目标**：提升用户体验

- [x] Web 视频上传功能
- [x] 上传进度显示
- [x] 自动刷新素材列表

### 阶段九：唇形同步模型升级 (Day 6) ✅

> **目标**：从 MuseTalk 迁移到 LatentSync 1.6

- [x] MuseTalk → LatentSync 1.6 迁移
- [x] 后端代码适配 (config.py, lipsync_service.py)
- [x] Latent Diffusion 架构 (512x512 高清)
- [x] 服务器端到端验证

### 阶段十：性能优化 (Day 6) ✅

> **目标**：提升系统响应速度和稳定性

- [x] 视频预压缩优化 (1080p → 720p 自动适配)
- [x] 进度更新细化 (实时反馈)
- [x] **常驻模型服务** (Persistent Server, 0s 加载)
- [x] **GPU 并发控制** (串行队列防崩溃)

### 阶段十一：社交媒体发布完善 (Day 7) ✅

> **目标**：实现全自动扫码登录和多平台发布

- [x] QR码自动登录 (Playwright headless + Stealth)
- [x] 多平台上传器架构 (B站/抖音/小红书)
- [x] Cookie 自动管理
- [x] 定时发布功能

### 阶段十二：用户体验优化 (Day 8) ✅

> **目标**：提升文件管理和历史记录功能

- [x] 文件名保留 (时间戳前缀 + 原始名称)
- [x] 视频持久化 (历史视频列表 API)
- [x] 素材/视频删除功能

### 阶段十三：发布模块优化 (Day 9) ✅

> **目标**：代码质量优化 + 发布功能验证

- [x] B站/抖音登录+发布验证通过
- [x] 资源清理保障 (try-finally)
- [x] 超时保护 (消除无限循环)
- [x] 完整类型提示

### 阶段十四：用户认证系统 (Day 9) ✅

> **目标**：实现安全、隔离的多用户认证体系

- [x] Supabase 云数据库集成 (本地自托管)
- [x] JWT + HttpOnly Cookie 认证架构
- [x] 用户表与权限表设计 (RLS 准备)
- [x] 认证部署文档 (Docs/SUPABASE_DEPLOY.md)

### 阶段十五：部署稳定性优化 (Day 9) ✅

> **目标**：确保生产环境服务长期稳定

- [x] 依赖冲突修复 (bcrypt)
- [x] 前端构建修复 (Production Build)
- [x] PM2 进程守护配置
- [x] 部署手册更新 (Docs/DEPLOY_MANUAL.md)

### 阶段十六：HTTPS 全栈部署 (Day 10) ✅

> **目标**：实现安全的公网 HTTPS 访问

- [x] 阿里云 Nginx 反向代理配置
- [x] Let's Encrypt SSL 证书集成
- [x] Supabase 自托管部署 (Docker)
- [x] 端口冲突解决 (3003/8008/8444)
- [x] Basic Auth 管理后台保护

### 阶段十七：声音克隆功能集成 (Day 13) ✅

> **目标**：实现用户自定义声音克隆能力

- [x] Qwen3-TTS HTTP 服务 (独立 FastAPI，端口 8009)
- [x] 声音克隆服务封装 (voice_clone_service.py)
- [x] 参考音频管理 API (上传/列表/删除)
- [x] 前端 TTS 模式选择 UI
- [x] Supabase ref-audios Bucket 配置
- [x] 端到端测试验证

### 阶段十八：手机号登录迁移 (Day 15) ✅

> **目标**：将认证系统从邮箱迁移到手机号

- [x] 数据库 Schema 迁移 (email → phone)
- [x] 后端 API 适配 (auth.py/admin.py)
- [x] 11位手机号校验 (正则验证)
- [x] 修改密码功能 (/api/auth/change-password)
- [x] 账户设置下拉菜单 (修改密码 + 有效期显示 + 退出)
- [x] 前端登录/注册页面更新
- [x] 数据库迁移脚本 (migrate_to_phone.sql)

### 阶段十九：深度性能优化与服务守护 (Day 16) ✅

> **目标**：提升系统响应速度与服务稳定性

- [x] Flash Attention 2 集成 (Qwen3-TTS 加速 5x)
- [x] LatentSync 性能调优 (OMP 线程限制 + 原生 Flash Attn)
- [x] Watchdog 服务守护 (自动重启僵死服务)
- [x] 文档体系更新 (部署手册与运维指南)

---

## 项目目录结构 (最终)

---

## 开发时间估算

| 阶段 | 预计时间 | 说明 |
|------|----------|------|
| 阶段一 | 2-3 天 | 环境搭建 + 效果验证 |
| 阶段二 | 3-4 天 | 后端 API 开发 |
| 阶段三 | 3-4 天 | 前端 UI 开发 |
| 阶段四 | 2 天 | 社交发布集成 |
| 阶段五 | 按需 | 持续优化 |

**总计**：约 10-13 天可完成 MVP

---

### 阶段二十：代码质量与安全优化 (Day 20) ✅

> **目标**：全面提升代码健壮性、安全性与配置灵活性

- [x] **安全性修复**：硬编码 Cookie/Key 移除，ffprobe 安全调用，日志脱敏
- [x] **配置化改造**：存储路径、CORS、录屏开关全面环境变量化
- [x] **性能优化**：API 异步改造 (httpx/asyncio)，大文件流式上传
- [x] **构建优化**：Remotion 预编译，统一启动脚本 `run_backend.sh`

---

## 验证计划

### 阶段一验证
1. 运行 `test_pipeline.py` 脚本
2. 检查生成视频的唇形同步效果
3. 确认音画同步

### 阶段二验证
1. 使用 Postman/curl 测试所有 API 端点
2. 验证任务队列正常工作
3. 检查视频生成完整流程

### 阶段三验证
1. 在浏览器中完成完整操作流程
2. 验证上传、生成、下载功能
3. 检查响应式布局

### 阶段四验证
1. 发布一个测试视频到抖音
2. 验证定时发布功能
3. 检查发布状态同步

---

## 硬件要求

| 配置 | 最低要求 | 推荐配置 |
|------|----------|----------|
| **GPU** | NVIDIA GTX 1060 6GB | RTX 3060 12GB+ |
| **内存** | 16GB | 32GB |
| **存储** | 100GB SSD | 500GB SSD |
| **CUDA** | 11.7+ | 12.0+ |

---

## 下一步行动

1. **确认你的 GPU 配置** - MuseTalk 需要 NVIDIA GPU
2. **选择开发起点** - 从阶段一开始验证效果
3. **确定项目位置** - 在哪个目录创建项目

---

> [!IMPORTANT]
> 请确认以上计划是否符合你的需求，有任何需要调整的地方请告诉我。