# 视频生成模块

## 功能概述

基于 FFmpeg 实现图片+音频生成配图视频功能，支持 Ken Burns 效果、字幕叠加、背景音乐混音等。

## 核心能力

- ✅ **Ken Burns 效果**：慢速缩放/平移动画，让静态图片"动起来"
- ✅ **音频同步**：图片切换与音频时长自动匹配
- ✅ **字幕叠加**：可选添加文字字幕
- ✅ **背景音乐**：可选添加背景 BGM 混音
- ✅ **多图轮播**：支持多个图片自动切换
- ✅ **多种尺寸**：支持竖屏(9:16)、横屏(16:9)、方形(1:1)

## 技术栈

- **后端**：Node.js + TypeScript + fluent-ffmpeg
- **前端**：uniapp-vue3
- **数据库**：MySQL + Prisma ORM
- **视频处理**：FFmpeg（开源免费，CPU 计算）

## 项目结构

```
server/src/modules/video-generator/
├── video-generator.controller.ts  # API 路由控制器
├── video-generator.service.ts     # 业务逻辑
├── video-generator.types.ts       # 类型定义
├── video-generator.ffmpeg.ts     # FFmpeg 命令封装
└── README.md                     # 模块文档

my-uniapp-vue3/src/
├── pages/video-generator/
│   ├── index.vue      # 视频项目列表页
│   ├── create.vue    # 创建/编辑视频页
│   └── preview.vue   # 视频预览页
├── utils/video-generator-api.ts  # 前端 API 调用封装
└── types/video-generator.ts       # 前端类型定义
```

## API 接口

### 视频项目管理

| 接口 | 方法 | 描述 |
|------|------|------|
| `/api/video/projects` | GET | 获取视频项目列表 |
| `/api/video/projects` | POST | 创建视频项目 |
| `/api/video/projects/:id` | GET | 获取项目详情 |
| `/api/video/projects/:id` | PUT | 更新项目配置 |
| `/api/video/projects/:id` | DELETE | 删除项目 |
| `/api/video/projects/:id/generate` | POST | 开始生成视频 |
| `/api/video/projects/:id/status` | GET | 获取生成状态 |

### 素材管理

| 接口 | 方法 | 描述 |
|------|------|------|
| `/api/video/materials` | GET | 获取素材列表 |
| `/api/video/materials/upload` | POST | 上传素材 |
| `/api/video/materials/:id` | DELETE | 删除素材 |

### 快捷入口

| 接口 | 方法 | 描述 |
|------|------|------|
| `/api/video/books/:bookId/generate` | POST | 从书籍生成视频 |

## 使用流程

### 1. 创建视频项目

```bash
curl -X POST http://localhost:3000/api/video/projects \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "我的有声书视频",
    "description": "测试视频描述",
    "config": {
      "images": [{"url": "https://xxx.jpg", "duration": 5, "transition": "fade"}],
      "audio": {"url": "https://xxx.mp3", "volume": 1},
      "video": {"width": 720, "height": 1280, "fps": 30, "bitrate": "2M", "format": "mp4"},
      "kenburns": {"enabled": true, "minZoom": 1.0, "maxZoom": 1.2}
    }
  }'
```

### 2. 启动生成

```bash
curl -X POST http://localhost:3000/api/video/projects/1/generate
```

### 3. 查询进度

```bash
curl http://localhost:3000/api/video/projects/1/status
```

## 前端页面

### 列表页 (`/pages/video-generator/index`)
- 显示所有视频项目
- 创建新视频按钮
- 项目状态和进度显示
- 预览、删除、重试操作

### 创建页 (`/pages/video-generator/create`)
- **步骤1**：选择素材（图片+音频）
- **步骤2**：配置效果（尺寸、Ken Burns、字幕）
- **步骤3**：生成视频并查看进度

### 预览页 (`/pages/video-generator/preview`)
- 视频播放器
- 下载和分享功能
- 重新生成选项

## FFmpeg 命令示例

### Ken Burns 效果

```bash
ffmpeg -loop 1 -i image.jpg -i audio.mp3 \
  -vf "zoompan=z='if(gte(zoom,1.0),min(zoom+0.001,1.2),1.0)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=1:s=720x1280:fps=30" \
  -c:v libx264 -preset fast -crf 18 \
  -c:a aac -b:a 192k \
  -pix_fmt yuv420p -shortest \
  output.mp4
```

### 带字幕

```bash
ffmpeg -loop 1 -i image.jpg -i audio.mp3 \
  -vf "scale=720:1280:force_original_aspect_ratio=decrease,pad=720:1280:(ow-iw)/2:(oh-ih)/2:color=black,drawtext=text='标题':fontsize=24:fontcolor=white:borderw=2:bordercolor=black:x=(w-text_w)/2:y=h-text_h-20" \
  -c:v libx264 -preset fast \
  -c:a aac -b:a 192k \
  -pix_fmt yuv420p -shortest \
  output.mp4
```

## 数据库模型

### VideoProject

| 字段 | 类型 | 描述 |
|------|------|------|
| id | Int | 主键 |
| userId | Int? | 用户ID |
| title | String | 项目标题 |
| description | String? | 描述 |
| coverUrl | String? | 封面图 |
| configJson | String? | 配置JSON |
| outputUrl | String? | 输出视频URL |
| duration | Int? | 视频时长（秒） |
| fileSize | Int? | 文件大小（字节） |
| bookId | Int? | 关联书籍ID |
| audioId | Int? | 关联音频ID |
| status | String | 状态 |
| progress | Int | 生成进度 |

### VideoMaterial

| 字段 | 类型 | 描述 |
|------|------|------|
| id | Int | 主键 |
| userId | Int? | 用户ID（null=公共素材） |
| type | String | 类型（image/audio/template） |
| name | String | 素材名称 |
| url | String | 素材URL |
| thumbnail | String? | 缩略图 |
| tags | String? | 标签（JSON数组） |
| category | String? | 分类 |

## 待优化项

- [ ] 实现素材库功能（图片/音频素材管理）
- [ ] 添加更多转场效果（滑动、缩放等）
- [ ] 实现视频剪辑（截取音频片段）
- [ ] 添加更多字幕样式（描边、阴影等）
- [ ] 集成 AI 图片生成（根据描述生成配图）
- [ ] 实现视频压缩优化
- [ ] 添加水印功能

## 注意事项

1. **FFmpeg 依赖**：确保服务器已安装 FFmpeg
2. **临时文件**：定期清理 `temp/` 目录下的临时文件
3. **文件大小**：建议单次生成视频不超过 5 分钟
4. **并发限制**：建议限制同时生成的视频数量（防止资源耗尽）

## 部署

### 1. 安装 FFmpeg

**macOS**:
```bash
brew install ffmpeg
```

**Ubuntu/Debian**:
```bash
sudo apt update
sudo apt install ffmpeg
```

**Windows**:
从 https://ffmpeg.org/download.html 下载并配置环境变量

### 2. 创建输出目录

```bash
mkdir -p public/videos
mkdir -p temp/images
mkdir -p temp/audio
```

### 3. 运行服务

```bash
cd server
npm install
npm run dev
```
