视频生成系统

本文档引用的文件

video-generator.controller.ts
video-generator.service.ts
video-generator.ffmpeg.ts
video-generator.types.ts
ffmpeg.processor.ts
storage.service.ts
app.ts
README.md
video-generator.ts
video-generator-api.ts
create.vue
index.vue

简介

本系统是一个基于 FFmpeg 的视频生成平台，支持将静态图片与音频合成生成视频，内置 Ken Burns 效果、字幕叠加、背景音乐混音、多图轮播等能力。系统采用前后端分离架构：后端使用 Node.js + TypeScript + Koa，前端使用 uniapp-vue3，通过 RESTful API 进行交互。系统提供完整的视频项目生命周期管理、素材管理、进度监控与结果预览功能，并支持 OSS 与本地存储的无缝切换。

项目结构

后端模块位于 server/src/modules/video-generator，包含控制器、服务层、FFmpeg 封装与类型定义；服务层提供统一存储接口；前端位于 my-uniapp-vue3，包含视频生成页面与 API 封装。

graph TB
subgraph "后端"
A["Koa 应用<br/>app.ts"]
B["视频生成控制器<br/>video-generator.controller.ts"]
C["视频生成服务<br/>video-generator.service.ts"]
D["FFmpeg 封装<br/>video-generator.ffmpeg.ts"]
E["通用 FFmpeg 处理器<br/>ffmpeg.processor.ts"]
F["存储服务<br/>storage.service.ts"]
end
subgraph "前端"
G["视频生成页面<br/>create.vue"]
H["项目列表页面<br/>index.vue"]
I["API 封装<br/>video-generator-api.ts"]
J["类型定义<br/>video-generator.ts"]
end
A --> B --> C --> D
C --> E
C --> F
G --> I
H --> I
I --> B

图表来源

app.ts:1-194
video-generator.controller.ts:1-244
video-generator.service.ts:1-556
video-generator.ffmpeg.ts:1-300
ffmpeg.processor.ts:1-379
storage.service.ts:1-278
create.vue:1-365
index.vue:1-482
video-generator-api.ts:1-188
video-generator.ts:1-116

章节来源

README.md:23-40
app.ts:100-130

核心组件

视频生成控制器：提供 RESTful API，负责视频项目管理、生成触发与进度查询。
视频生成服务：封装业务逻辑，协调素材校验、文件下载、进度更新与状态管理。
FFmpeg 封装：提供图片+音频合成、Ken Burns 效果、字幕叠加、背景音乐混音、多图轮播等能力。
通用 FFmpeg 处理器：支持远程 URL 下载、音频合并、音视频混合、格式转换、裁剪与音量调整等。
存储服务：统一 OSS 与本地存储接口，支持上传、下载、删除与签名 URL。
前端页面与 API：提供视频项目创建、素材选择、生成进度监控与结果预览。

章节来源

video-generator.controller.ts:20-244
video-generator.service.ts:30-312
video-generator.ffmpeg.ts:20-280
ffmpeg.processor.ts:24-379
storage.service.ts:13-278
video-generator-api.ts:76-188

架构总览

系统采用分层架构：

表现层：uniapp-vue3 前端页面与 API 封装。
控制层：Koa 路由与控制器，处理请求与响应。
业务层：视频生成服务，协调数据与流程。
处理层：FFmpeg 封装与通用处理器，执行底层视频处理。

存储层：统一存储服务，支持 OSS 与本地存储。

graph TB
FE["前端页面<br/>create.vue/index.vue"]
API["API 封装<br/>video-generator-api.ts"]
CTRL["控制器<br/>video-generator.controller.ts"]
SVC["服务层<br/>video-generator.service.ts"]
FFMPEG["FFmpeg 封装<br/>video-generator.ffmpeg.ts"]
PROC["通用处理器<br/>ffmpeg.processor.ts"]
STORE["存储服务<br/>storage.service.ts"]
FE --> API --> CTRL --> SVC --> FFMPEG
SVC --> PROC
SVC --> STORE
FFMPEG --> STORE

图表来源

create.vue:107-315
index.vue:108-254
video-generator-api.ts:76-188
video-generator.controller.ts:20-244
video-generator.service.ts:154-312
video-generator.ffmpeg.ts:20-280
ffmpeg.processor.ts:24-379
storage.service.ts:13-278

详细组件分析

视频生成控制器

提供视频项目管理接口：创建、查询、更新、删除。
提供生成触发与进度查询接口：开始生成、获取状态。
提供素材管理接口：列表、上传、删除。

提供快捷入口：从书籍生成视频项目。

sequenceDiagram
participant FE as "前端"
participant API as "API 封装"
participant CTRL as "控制器"
participant SVC as "服务层"
participant FFMPEG as "FFmpeg 封装"
FE->>API : 调用生成视频
API->>CTRL : POST /api/video/projects/{id}/generate
CTRL->>SVC : generateVideoForProject(id)
SVC->>FFMPEG : generateVideo(image,audio,output,config)
FFMPEG-->>SVC : {duration,fileSize}
SVC-->>CTRL : {success,outputUrl,duration,fileSize}
CTRL-->>FE : 返回结果

图表来源

video-generator.controller.ts:111-129
video-generator.service.ts:154-312
video-generator.ffmpeg.ts:23-118

章节来源

video-generator.controller.ts:20-244

视频生成服务

视频项目管理：创建、查询、更新、删除。
生成流程：状态检查、素材校验、文件下载、进度更新、结果写回。
素材管理：上传、查询、删除。

从书籍生成视频项目：自动关联章节音频与标题。

flowchart TD
Start(["开始生成"]) --> LoadProj["加载项目"]
LoadProj --> CheckStatus{"状态是否为 processing?"}
CheckStatus --> |是| Fail["返回错误: 正在生成中"]
CheckStatus --> |否| UpdateStatus["更新状态为 processing"]
UpdateStatus --> CheckMedia{"音频/图片是否存在?"}
CheckMedia --> |否| Fail
CheckMedia --> |是| GenVideo["调用 FFmpeg 生成视频"]
GenVideo --> SaveResult["保存结果并更新状态"]
SaveResult --> Done(["完成"])
Fail --> End(["结束"])
Done --> End

图表来源

video-generator.service.ts:154-312
video-generator.ffmpeg.ts:23-118

章节来源

video-generator.service.ts:30-312

FFmpeg 封装

图片+音频合成：支持 Ken Burns 效果、缩放与填充、字幕叠加。
背景音乐混音：支持主音频与背景音乐混合。
多图轮播：支持多张图片按时序拼接。

视频信息获取：通过 ffprobe 获取时长、分辨率与文件大小。

classDiagram
class FFmpeg封装 {
+generateVideo(imagePath, audioPath, outputPath, config)
+generateVideoWithBgm(imagePath, audioPath, bgmPath, outputPath, config)
+generateSlideshow(images, audioPath, outputPath, config)
+getVideoInfo(filePath)
}
class 视频配置 {
+images : ImageConfig[]
+audio : AudioConfig
+bgm? : BgmConfig
+subtitle? : SubtitleConfig
+video : VideoParams
+kenburns : KenBurnsConfig
}
FFmpeg封装 --> 视频配置 : "使用"

图表来源

video-generator.ffmpeg.ts:20-280
video-generator.types.ts:74-93

章节来源

video-generator.ffmpeg.ts:20-280

通用 FFmpeg 处理器

远程文件下载：支持 HTTP/HTTPS 与本地路径。
音频合并：支持多个音频文件拼接。
音视频混合：支持替换音频或混合背景音乐。
音频格式转换、裁剪与音量调整。

临时文件清理：保证磁盘空间。

flowchart TD
Download["下载远程文件"] --> Merge["音频合并/音视频混合"]
Merge --> Convert["格式转换/裁剪/音量调整"]
Convert --> Upload["上传到存储"]
Upload --> Cleanup["清理临时文件"]

图表来源

ffmpeg.processor.ts:30-379

章节来源

ffmpeg.processor.ts:24-379

存储服务

统一 OSS 与本地存储接口，支持上传、下载、删除与签名 URL。

自动切换存储类型，便于部署与迁移。

classDiagram
class 存储服务 {
+setStorageType(type)
+getStorageType()
+uploadAudio(localPath, audioId)
+uploadVideo(localPath, videoId)
+uploadFile(localPath, category, id)
+downloadFile(url)
+deleteFile(url)
+getSignedUrl(url, expires)
}
存储服务 : "支持 OSS 与本地存储"

图表来源

storage.service.ts:13-278

章节来源

storage.service.ts:13-278

前端页面与 API

视频生成页面：三步式向导，支持素材选择、效果配置与生成。
项目列表页面：展示项目状态、进度与结果操作。

API 封装：统一请求与响应处理。

sequenceDiagram
participant Page as "创建页"
participant API as "API 封装"
participant Ctrl as "控制器"
participant Svc as "服务层"
Page->>API : 保存项目
API->>Ctrl : POST /api/video/projects
Ctrl->>Svc : createVideoProject
Svc-->>Ctrl : 返回项目
Ctrl-->>API : 返回项目
API-->>Page : 保存成功
Page->>API : 开始生成
API->>Ctrl : POST /api/video/projects/{id}/generate
Ctrl->>Svc : generateVideoForProject
Svc-->>Ctrl : 返回进度
Ctrl-->>API : 返回进度
API-->>Page : 轮询进度

图表来源

create.vue:268-312
video-generator-api.ts:98-139
video-generator.controller.ts:111-139
video-generator.service.ts:154-312

章节来源

create.vue:107-315
index.vue:108-254
video-generator-api.ts:76-188

依赖关系分析

控制器依赖服务层；服务层依赖 FFmpeg 封装与存储服务；通用处理器作为独立工具被服务层调用。
前端通过 API 封装调用后端接口。

应用启动时注册路由并挂载静态资源。

graph LR
CTRL["控制器"] --> SVC["服务层"]
SVC --> FFMPEG["FFmpeg 封装"]
SVC --> PROC["通用处理器"]
SVC --> STORE["存储服务"]
FE["前端"] --> API["API 封装"] --> CTRL
APP["应用启动"] --> CTRL
APP --> STORE

图表来源

app.ts:100-130
video-generator.controller.ts:20-244
video-generator.service.ts:154-312
ffmpeg.processor.ts:24-379
storage.service.ts:13-278

章节来源

app.ts:100-130

性能考虑

FFmpeg 参数优化
- 视频编码：使用 libx264，preset 设置为 fast，CRF 18，码率自适应以平衡质量与体积。
- 音频编码：AAC，码率 192k，满足大多数场景。
- 像素格式：yuv420p，兼容性最佳。
- 最短时长：-shortest，避免音频过长导致黑屏。
Ken Burns 效果
- zoompan 滤镜参数：minZoom/maxZoom 控制缩放范围，fps 控制平滑度，s 指定目标分辨率。
字幕渲染
- drawtext 滤镜：合理设置字体大小、颜色与描边，避免遮挡画面主体。
并发与资源控制
- 建议限制同时生成任务数量，防止 CPU/内存耗尽。
- 合理设置超时时间，避免长时间占用进程。
存储与临时文件
- 定期清理 temp 目录，避免磁盘空间不足。
- 使用 SSD 提升 I/O 性能。

[本节为通用性能指导，无需特定文件引用]

故障排除指南

FFmpeg 依赖缺失
- 确保服务器已安装 FFmpeg，并加入 PATH。
权限问题
- public/videos 与 temp 目录需具备写权限。
进度查询异常
- 检查项目状态字段与数据库连接。
生成失败
- 查看服务日志中的错误堆栈，定位具体环节（下载、FFmpeg 执行、存储上传）。
前端无法预览
- 检查静态资源挂载与 CORS 配置。

章节来源

README.md:186-192
app.ts:70-90

结论

该视频生成系统通过清晰的分层架构与完善的 FFmpeg 封装，实现了从图片与音频到成品视频的自动化处理。系统支持 Ken Burns 效果、字幕叠加与背景音乐混音，具备良好的扩展性与可维护性。结合统一存储服务与前端交互，能够满足移动端与 Web 端的视频生成需求。

[本节为总结性内容，无需特定文件引用]

附录

FFmpeg 命令行参数配置要点

视频编码
- -c:v libx264：H.264 编码器
- -preset fast：编码速度优先
- -crf 18：质量控制，数值越低质量越高
- -pix_fmt yuv420p：兼容性像素格式
音频编码
- -c:a aac：AAC 编码
- -b:a 192k：音频比特率
最短时长
- -shortest：以最短输入为准结束
Ken Burns 效果
- zoompan：缩放与平移动画
- z/x/y/d/s/fps：缩放比例、中心点、帧间隔、分辨率、帧率
字幕叠加
- drawtext：文本绘制，支持字体大小、颜色、描边与位置

章节来源

video-generator.ffmpeg.ts:87-98
video-generator.ffmpeg.ts:169-186
video-generator.ffmpeg.ts:252-262

视频合成算法与流程

图片+音频合成
- 输入：单张图片（循环）、音频文件
- 处理：Ken Burns 效果、缩放与填充、字幕叠加
- 输出：MP4 视频
背景音乐混音
- 输入：图片（循环）、主音频、背景音乐
- 处理：主音频与背景音乐混合，映射到视频音频轨道
- 输出：MP4 视频
多图轮播
- 输入：多张图片列表、音频文件
- 处理：拼接图片序列，缩放与填充，字幕叠加
- 输出：MP4 视频

章节来源

video-generator.ffmpeg.ts:23-118
video-generator.ffmpeg.ts:123-199
video-generator.ffmpeg.ts:204-280

字幕生成与渲染

字幕位置：支持顶部、中部、底部三种位置，动态计算 Y 坐标。
字体样式：支持字体大小、颜色、描边与边距。
文本内容：来自配置对象，支持章节标题等动态内容。

章节来源

video-generator.ffmpeg.ts:67-83
video-generator.ffmpeg.ts:233-248

视频格式转换

支持 MP3、WAV、AAC 等常见音频格式转换。
通过通用处理器执行转换命令，完成后上传至存储服务。

章节来源

ffmpeg.processor.ts:217-261

内存管理策略

临时文件管理：下载与处理过程产生的中间文件在完成后清理。
进度回调：监听 FFmpeg 进度，避免阻塞主线程。
超时控制：为长耗时操作设置超时，防止资源泄漏。

章节来源

ffmpeg.processor.ts:346-375
video-generator.ffmpeg.ts:100-117

批量处理策略

任务队列：建议引入队列服务，限制并发数量。
断点续传：记录生成进度，异常恢复后继续。
资源监控：监控 CPU、内存与磁盘使用，动态调整并发。

[本节为通用策略建议，无需特定文件引用]

代码示例路径

调用 FFmpeg 进行视频处理
- video-generator.ffmpeg.ts:23-118
- video-generator.ffmpeg.ts:123-199
- video-generator.ffmpeg.ts:204-280
实现字幕同步
- video-generator.ffmpeg.ts:67-83
- video-generator.ffmpeg.ts:233-248
优化视频质量
- video-generator.ffmpeg.ts:87-98
- video-generator.ffmpeg.ts:169-186
- video-generator.ffmpeg.ts:252-262

视频生成系统.md 20 KB History Raw

视频生成系统

目录

简介

项目结构

核心组件

架构总览

详细组件分析

视频生成控制器

视频生成服务

FFmpeg 封装

通用 FFmpeg 处理器

存储服务

前端页面与 API

依赖关系分析

性能考虑

故障排除指南

结论

附录

FFmpeg 命令行参数配置要点

视频合成算法与流程

字幕生成与渲染

视频格式转换

内存管理策略

批量处理策略

代码示例路径

视频生成系统.md 20 KB

History Raw