FFmpeg 合成分镜完整功能指南

📌 功能概述

已成功实现 FFmpeg 视频合成的完整功能链路，支持：

🎥 8种运镜效果：推进、拉远、左移、右移、上移、下移、旋转
🔄 25+种转场效果：淡入淡出、擦除、滑动、圆形展开/收缩等
📝 ASS字幕渲染：自适应字号、底部边距、左右边距
📊 质量打分系统：自动评估视频质量，优化前后对比
🚀 一键视频增强：超分辨率 + 插帧，提升视频质量
💾 数据库持久化：合成成功后自动保存结果
🤖 智能模式：根据内容类型自动选择合适的运镜和转场

🚀 快速开始

1. 前端配置界面

在 FFmpegComposeDialog.vue 中，新增了运镜 & 转场配置区域：

vue

启用运镜：[开关]
运镜模式：智能选择 / 手动配置 / 无运镜
内容类型：解说类 / 剧情类 / 知识类 / 搞笑类 / 通用

启用转场：[开关]
转场模式：智能选择 / 手动选择
转场类型：淡入淡出 / 左擦除 / 右擦除 / ...
转场时长：0.1~2秒

2. API 调用示例

javascript

const options = {
  // 基础配置
  impl: 'ffmpeg-python',
  resolution: '1280x720',
  fps: 30,
  
  // 运镜配置
  enable_camera: true,          // 启用运镜
  camera_mode: 'auto',          // 智能选择运镜类型
  content_type: 'narration',    // 内容类型：解说类
  
  // 转场配置
  enable_transition: true,      // 启用转场
  transition_mode: 'auto',      // 智能选择转场类型
  transition_duration: 0.5      // 转场时长0.5秒
}

3. timeline_json 手动配置运镜

如果使用 camera_mode: 'manual'，可在每个片段中指定运镜：

json

{
  "segments": [
    {
      "videoUrl": "https://...",
      "audioUrl": "https://...",
      "camera_motion": "zoom_in"     // 推进效果
    },
    {
      "videoUrl": "https://...",
      "audioUrl": "https://...",
      "camera_motion": "pan_left"    // 左移效果
    }
  ]
}

🎬 运镜效果说明

可用运镜类型

类型	说明	适用场景
`zoom_in`	推进（Ken Burns）	解说、重点突出
`zoom_out`	拉远	全景展示
`pan_left`	左移	横向场景
`pan_right`	右移	横向场景
`pan_up`	上移	纵向场景
`pan_down`	下移	纵向场景
`rotate_cw`	顺时针旋转	动感效果
`rotate_ccw`	逆时针旋转	动感效果
`none`	无运镜	保持稳定

智能运镜规则

根据 content_type 自动选择：

解说类 (narration)：交替推进和拉远，>5s片段才加运镜
剧情类 (drama)：左移、右移、无运镜循环
知识类 (knowledge)：保持稳定，>5s才推进
搞笑类 (comedy)：灵活多变，推进+左右移动

🔄 转场效果说明

常用转场类型

类型	说明	推荐时长
`fade`	淡入淡出	0.5s
`dissolve`	溶解	0.5s
`wipeleft`	左擦除	0.5s
`wiperight`	右擦除	0.5s
`slideleft`	左滑动	0.3s（快）
`slideright`	右滑动	0.3s（快）
`circleopen`	圆形展开	0.8s（慢）
`circleclose`	圆形收缩	0.8s（慢）
`pixelize`	像素化	0.5s

智能转场规则

根据 content_type 自动选择：

解说类：简单淡入淡出 / 溶解
剧情类：多样化转场（淡入、擦除、溶解）
知识类：保持简洁，仅淡入淡出
搞笑类：活泼效果（圆形、滑动、像素化）

📝 ASS字幕系统

核心特性

自适应字号
- 根据视频分辨率自动计算：fontsize = height × 3.54%
- 范围限制：32-80px（防止极端情况）
- 1920p 竖屏 → 68px，1080p → 42px，720p → 32px
智能边距
- 底部边距：margin_v = height × 13% （~250px @ 1920p）
- 左右边距：margin_lr = width × 1.85% （~20px @ 1080p）
- 避免被移动设备UI遵挡
样式配置
- 字体：Arial（通用，可扩展）
- 颜色：白色文字 + 黑色描边
- 描边宽度：outline = fontsize × 6%
- 阴影：2px 偏移，增强可读性
- 对齐方式：底部居中（Alignment=2）

分辨率对照表

分辨率	字号	描边	底部边距	左右边距
1080x1920 (9:16)	68px	4px	250px	20px
720x1280 (9:16)	45px	3px	166px	13px
1920x1080 (16:9)	38px	2px	140px	36px
2160x3840 (4K 9:16)	136px	8px	499px	40px

技术决策：为什么使用 ASS 而非 drawtext？

特性	SRT (subtitles滤镜)	drawtext滤镜	ASS (subtitles滤镜)
样式控制	默认样式	精细控制	精细控制
底部边距	固定	可调整	可调整
左右边距	无	可调整	可调整
字号自适应	不支持	需手动	自动
多行支持	支持	需手动\n	支持
渲染性能	高	中	高
调试难度	易	难	中
稳定性	高	低（未调试完成）	高

结论：ASS 格式兼具 drawtext 的灵活性和 SRT 的稳定性，是最佳选择。

📊 质量打分与增强系统

质量评估维度

json

{
  "overall_score": 71.25,
  "grade": "B",
  "dimensions": {
    "sharpness": 60,      // 清晰度
    "brightness": 100,    // 亮度
    "contrast": 80,       // 对比度
    "colorfulness": 70,   // 色彩丰富度
    "noise_level": 90     // 噪点水平（越低越好）
  }
}

一键增强功能

超分辨率 (Upscale)
- 使用 FFmpeg Lanczos 算法
- 默认 2倍放大：720p → 1440p
帧率插帧 (Interpolation)
- 使用 FFmpeg minterpolate 算法
- 默认目标：60fps
质量重新评估
- 增强后自动重新打分
- 前后对比展示：71.25 → 75.25

数据库字段设计

sql

-- storyboard 表新增字段
ALTER TABLE storyboard ADD COLUMN (
  compose_video_key VARCHAR(255) COMMENT '合成视频OSS Key（原始）',
  enhanced_video_key VARCHAR(255) COMMENT '增强视频OSS Key',
  compose_options TEXT COMMENT '合成配置JSON',
  quality_score TEXT COMMENT '质量评分JSON（before/after）',
  compose_job_id VARCHAR(128) COMMENT '合成任务ID',
  enhance_job_id VARCHAR(128) COMMENT '增强任务ID',
  compose_status VARCHAR(32) COMMENT '合成状态'
);

quality_score JSON 结构：

json

{
  "before": {
    "overall_score": 71.25,
    "grade": "B",
    "dimensions": {...}
  },
  "after": {
    "overall_score": 75.25,
    "grade": "B",
    "dimensions": {...}
  }
}

🔧 技术实现要点

后端架构

pybridge/src/bridge/
├── camera_motion.py          # 运镜效果生成器
├── transition_effects.py     # 转场效果处理器
├── ffmpeg_runner.py          # FFmpeg 命令构建器（已集成）
└── ffmpeg_python_adapter.py  # ffmpeg-python 适配器

FFmpeg Filter 实现

运镜示例（推进效果）

bash

zoompan=z='min(1.0+on*0.0167,1.5)':d=90:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=1280x720

转场示例（xfade淡入淡出）

bash

[v1][v2]xfade=transition=fade:duration=0.5:offset=4.5[xf1]
[xf1][v3]xfade=transition=fade:duration=0.5:offset=9.0[vout]

处理流程

原始视频 → 缩放 → 运镜效果 → 变速对齐 → xfade转场 → 字幕渲染 → 最终编码

📊 Pipeline 可视化

前端会动态显示处理阶段：

✅ 音频拼接
✅ 视频缩放
🔄 运镜效果  ← 当前阶段
⏳ 转场合成
⏳ 字幕渲染
⏳ 最终编码

🧪 测试建议

测试用例1：智能模式（解说类）

javascript

{
  enable_camera: true,
  camera_mode: 'auto',
  enable_transition: true,
  transition_mode: 'auto',
  content_type: 'narration'
}

预期效果：

运镜：推进/拉远交替
转场：淡入淡出/溶解

测试用例2：手动模式（剧情类）

javascript

{
  enable_camera: false,  // 不加运镜
  enable_transition: true,
  transition_mode: 'manual',
  transition_type: 'wipeleft',  // 统一左擦除
  transition_duration: 0.3
}

测试用例3：完全关闭

javascript

{
  enable_camera: false,
  enable_transition: false
}

预期效果：传统 concat 拼接，无运镜无转场

⚠️ 注意事项

性能影响
- 运镜和转场会增加约 20-30% 处理时间
- 转场使用 xfade filter，比 concat 慢
兼容性
- FFmpeg 版本需 >= 4.3（支持 xfade）
- 运镜效果对短片段（<3s）自动禁用
时长计算
- 转场会缩短总时长（每个转场占用 transition_duration 秒）
- 示例：3个5秒视频，0.5秒转场 → 总时长 = 15 - 0.5*2 = 14秒
默认配置
- 为保证兼容性，默认关闭运镜和转场
- 用户需手动启用

🔧 故障排查

问题1：xfade 转场报错

错误信息：Unknown filter 'xfade'

解决方案：升级 FFmpeg 到 4.3+

bash

ffmpeg -version  # 检查版本

问题2：运镜效果不明显

可能原因：片段太短（<3s）被自动跳过

解决方案：

使用更长的视频片段
或调整 camera_motion.py 中的最小时长限制

问题3：转场时间不准确

可能原因：offset 计算错误

检查日志：查看生成的 filter_complex 命令

bash

cat /path/to/job.log | grep "xfade"

📈 后续优化方向

场景识别：通过 AI 分析场景相似度，智能选择转场类型
运镜预览：前端实时预览运镜效果
批量配置：一键应用运镜/转场模板到所有片段
性能优化：GPU 加速 xfade 渲染
更多效果：3D 运镜、自定义缓动曲线

💡 使用技巧

解说视频：启用智能运镜 + 简单转场，增加动感但不喧宾夺主
剧情短片：使用手动模式，根据情节选择合适的转场
知识讲解：关闭运镜，仅使用淡入淡出保持专业
娱乐搞笑：全开智能模式，让系统自动添加活泼效果

📝 变更日志

2025-12-15 - 字幕系统优化

✅ ASS字幕渲染：从SRT模式升级为ASS格式
✅ 自适应字号：根据视频分辨率自动计算最佳字号（1920p→68px）
✅ 智能边距：底部边距13%（~250px），左右边距1.85%（~20px）
✅ 描边优化：描边宽度为字号的6%，阴影2px偏移
✅ 字号算法：fontsize = height × 3.54%，范围限制32-80px
✅ 完美适配：1080x1920竖屏、1920x1080横屏、4K等分辨率
⚠️ 技术决策：放弃drawtext模式，统一使用SRT→ASS转换

2025-12-15 - 质量打分与数据持久化

✅ 质量打分前后对比：展示优化前后的质量变化（71.25→75.25）
✅ 数据库集成：新增7个字段到storyboard表
- compose_video_key: 合成视频OSS Key（原始）
- enhanced_video_key: 增强视频OSS Key
- quality_score: 质量评分JSON（before/after）
- compose_options: 合成配置JSON
- compose_job_id / enhance_job_id: 任务追溯
- compose_status: 合成状态
✅ 失败保护：合成失败禁止写入数据库，防止脏数据
✅ Phinx迁移：使用数据库迁移工具管理结构变更

2025-12-15 - 初始版本发布

✅ 实现 8 种运镜效果
✅ 实现 25+ 种转场效果
✅ 智能模式支持 4 种内容类型
✅ 前端配置界面集成
✅ Pipeline 可视化更新

开发团队: Stooland AI 视频团队
技术栈: FFmpeg + Python FastAPI + Vue3 + ThinkPHP8

FFmpeg 合成分镜完整功能指南 ​

📌 功能概述 ​

🚀 快速开始 ​

1. 前端配置界面 ​

2. API 调用示例 ​

3. timeline_json 手动配置运镜 ​

🎬 运镜效果说明 ​

可用运镜类型 ​

智能运镜规则 ​

🔄 转场效果说明 ​

常用转场类型 ​

智能转场规则 ​

📝 ASS字幕系统 ​

核心特性 ​

分辨率对照表 ​

技术决策：为什么使用 ASS 而非 drawtext？ ​

📊 质量打分与增强系统 ​

质量评估维度 ​

一键增强功能 ​

数据库字段设计 ​

🔧 技术实现要点 ​

后端架构 ​

FFmpeg Filter 实现 ​

运镜示例（推进效果） ​

转场示例（xfade淡入淡出） ​

处理流程 ​

📊 Pipeline 可视化 ​

🧪 测试建议 ​

测试用例1：智能模式（解说类） ​

测试用例2：手动模式（剧情类） ​

测试用例3：完全关闭 ​

⚠️ 注意事项 ​

🔧 故障排查 ​

问题1：xfade 转场报错 ​

问题2：运镜效果不明显 ​

问题3：转场时间不准确 ​

📈 后续优化方向 ​

💡 使用技巧 ​

📝 变更日志 ​

2025-12-15 - 字幕系统优化 ​

2025-12-15 - 质量打分与数据持久化 ​

2025-12-15 - 初始版本发布 ​

FFmpeg 合成分镜完整功能指南

📌 功能概述

🚀 快速开始

1. 前端配置界面

2. API 调用示例

3. timeline_json 手动配置运镜

🎬 运镜效果说明

可用运镜类型

智能运镜规则

🔄 转场效果说明

常用转场类型

智能转场规则

📝 ASS字幕系统

核心特性

分辨率对照表

技术决策：为什么使用 ASS 而非 drawtext？

📊 质量打分与增强系统

质量评估维度

一键增强功能

数据库字段设计

🔧 技术实现要点

后端架构

FFmpeg Filter 实现

运镜示例（推进效果）

转场示例（xfade淡入淡出）

处理流程

📊 Pipeline 可视化

🧪 测试建议

测试用例1：智能模式（解说类）

测试用例2：手动模式（剧情类）

测试用例3：完全关闭

⚠️ 注意事项

🔧 故障排查

问题1：xfade 转场报错

问题2：运镜效果不明显

问题3：转场时间不准确

📈 后续优化方向

💡 使用技巧

📝 变更日志

2025-12-15 - 字幕系统优化

2025-12-15 - 质量打分与数据持久化

2025-12-15 - 初始版本发布