# Day 1 - ViGent 数字人口播系统开发

**日期**：2026-01-13  
**开发环境**：Windows 11 (本地开发) / Ubuntu 24.04 (服务器部署)  
**目标平台**：Dell PowerEdge R730 (2× RTX 3090 24GB)

---

## 🎯 今日目标

搭建数字人口播视频生成系统的完整框架，包括：
1. 后端 API (FastAPI)
2. 前端 UI (Next.js)
3. 视频生成流程 (TTS + FFmpeg)
4. 社交媒体发布功能

---

## 📦 项目初始化

### 后端项目结构
```
backend/
├── app/
│   ├── api/              # API 路由
│   │   ├── materials.py  # 素材管理
│   │   ├── videos.py     # 视频生成
│   │   └── publish.py    # 社交发布
│   ├── services/         # 核心服务
│   │   ├── tts_service.py      # EdgeTTS 配音
│   │   ├── video_service.py    # FFmpeg 视频合成
│   │   ├── lipsync_service.py  # MuseTalk 唇形同步
│   │   └── publish_service.py  # Playwright 自动发布
│   └── core/
│       └── config.py     # 配置管理
├── requirements.txt
└── .env.example
```

### 前端项目
- 使用 Next.js 14 + TypeScript + Tailwind CSS
- 主页面: 视频生成界面
- 发布页面: `/publish` 多平台发布管理

---

## 🔧 TTS + 视频合成

### EdgeTTS 集成
- 使用 `edge-tts` 库实现免费中文语音合成
- 支持多种音色: 云溪、云健、云扬、晓晓、晓伊

### FFmpeg 视频合成
```python
# 核心命令
ffmpeg -i video.mp4 -i audio.mp3 -c:v copy -c:a aac -map 0:v -map 1:a output.mp4
```

### 🐛 Bug 修复: asyncio subprocess 问题

**问题**：在 FastAPI BackgroundTasks 中调用 `asyncio.create_subprocess_exec` 导致 `NotImplementedError`

**原因**：BackgroundTasks 运行在非 asyncio 上下文中

**修复**：将 `_run_ffmpeg` 和 `_get_duration` 改为使用同步 `subprocess.run`

```python
# 修复前
result = await asyncio.create_subprocess_exec(...)

# 修复后
result = subprocess.run(cmd, shell=True, capture_output=True, text=True, encoding='utf-8')
```

**状态**：✅ 已修复，视频生成成功

---

## 🎬 MuseTalk 唇形同步集成

### 架构设计
- GPU0: 其他服务
- GPU1: MuseTalk 唇形同步

### 代码实现
- `lipsync_service.py` 支持本地模式和远程 API 模式
- 通过 `CUDA_VISIBLE_DEVICES=1` 指定使用 GPU1
- 如未配置，自动跳过唇形同步

---

## 📱 社交媒体发布

### 支持平台
| 平台 | 状态 |
|------|------|
| 抖音 | ✅ 框架完成 |
| 小红书 | ✅ 框架完成 |
| 微信视频号 | ✅ 框架完成 |
| 快手 | ✅ 框架完成 |
| B站 | ✅ 框架完成 |

### 技术方案
- 使用 Playwright 进行浏览器自动化
- Cookie 管理实现免登录发布
- 前端提供账号管理和一键发布 UI

---

## 📚 文档产出

| 文件 | 说明 |
|------|------|
| `README.md` | 项目说明 |
| `DEPLOY_MANUAL.md` | 手动部署指南 |
| `deploy.sh` | 一键部署脚本 |
| `.env.example` | 环境配置模板 |

---

## ✅ 今日完成

1. ✅ FastAPI 后端框架搭建
2. ✅ EdgeTTS 语音合成服务
3. ✅ FFmpeg 视频合成服务
4. ✅ MuseTalk 唇形同步集成 (代码层面)
5. ✅ Next.js 前端 UI (视频生成 + 发布管理)
6. ✅ Playwright 社交媒体发布服务
7. ✅ 端到端视频生成测试通过
8. ✅ 服务器部署文档编写

---


### 下午调试记录 (Afternoon Debugging Session)

**1. 前端 "Undefined" 错误**
- **现象**：视频生成失败，弹窗显示 "undefined"。
- **原因**：
  1. 后端 `videos.py` 在异常捕获时未设置 `message` 字段，前端无法获取错误信息。
  2. 路径解析逻辑错误导致文件未找到。
- **修复**：
  - 后端补充 `tasks[task_id]["message"]` 字段。
  - 修复 `pathlib.Path` 引用缺失。

**2. 路径解析问题**
- **现象**：本地测试时无法找到素材文件。
- **原因**：Windows 本地路径 (`d:\...`) 与相对路径混合使用，且 `BASE_DIR` 指向了错误的父级目录。
- **修复**：
  - `materials.py` 所有返回路径改为相对路径 (`uploads/materials/xxx`)。
  - `videos.py` 增加智能路径解析：非绝对路径自动拼接 `BASE_DIR`。
  - `config.py` 调整 `BASE_DIR` 指向项目根目录。

**3. 语法错误修复**
- **现象**：`page.tsx` 出现 `Parsing ecmascript source code failed`。
- **原因**：调试代码逻辑错误地插入到了 JSX渲染块中。
- **修复**：完全重写 `page.tsx`，规范化代码结构，增加 "Raw Response" 调试面板。

**4. 本地 Fallback 逻辑验证**
- **现象**：进度条从 5% 直接跳到 100%。
- **原因**：本地 MuseTalk 未启用，系统触发 `fallback` 逻辑（仅复制文件）。
- **验证**：符合预期行为，确保了无 GPU 环境下的流程连通性。

---

## 📋 明日计划

1. 在服务器上部署系统
2. 下载 MuseTalk 模型权重
3. 测试完整唇形同步流程
4. 优化前端 UI 交互体验