架构文档

系统概览

访谈视频处理器基于分离的渲染后端架构，支持两种视觉效果生成方式：

Browser Backend: HTML/CSS/Anime.js + Playwright 浏览器自动化（推荐）
PIL Backend: Python PIL 纯 Python 实现（备选方案）

典型的数据流如下：

视频文件 + 字幕文件
    ↓
内容分析器（提取建议）
    ↓
用户审批配置
    ↓
渲染引擎（生成帧序列）
    ├→ Browser: HTML → Playwright → 截图
    └→ PIL: Python → PIL 绘制
    ↓
视频合成器（MoviePy）
    ↓
输出视频

核心模块

1. video_processor.py

主入口和协调器，负责：

命令行参数解析
配置文件加载验证
渲染器选择（自动或手动指定）
多种组件类型的分发处理
视频合成和导出

关键函数：

process_video(): 主处理流程
_generate_clips_browser(): 使用浏览器渲染器生成图层
_generate_clips_pil(): 使用 PIL 渲染器生成图层

2. browser_renderer.py

Playwright 浏览器自动化渲染器，负责：

Playwright 浏览器实例管理
HTML 模板加载与渲染
动画状态管理（通过 seek 控制当前帧）
截图捕获和图像输出

关键类和方法：

BrowserRenderer: 主类，生命周期管理
render_fancy_text_frames(): 花字渲染
render_term_card_frames(): 名词卡片渲染
render_lower_third_frames(): 人物条渲染
以及其他 8 个组件的渲染方法

工作原理：

加载 HTML 模板
    ↓
注入配置参数（JSON）
    ↓
调用 JavaScript initAnimation()
    ↓
循环：
  - 计算当前帧时间
  - 调用 JavaScript seek(t)
  - Playwright 截图
  - 保存为 PNG

3. content_analyzer.py

内容分析引擎，负责：

从字幕文件提取信息
分析内容，识别：
- 嘉宾信息（人物条）
- 话题切换点（章节标题）
- 关键观点（花字短语）
- 专业术语（名词卡片）
- 精彩言论（金句卡片）
- 数字数据（数据动画）
- 核心要点（要点列表）
- 社交媒体信息（社交条）

包含多个 Dataclass 定义建议类型：

LowerThirdSuggestion
ChapterTitleSuggestion
FancyTextSuggestion
TermCardSuggestion
QuoteCalloutSuggestion
AnimatedStatsSuggestion
BulletPointsSuggestion
SocialBarSuggestion

4. fancy_text.py（PIL 备选方案）

纯 Python PIL 实现的花字生成器：

PIL 文字渲染与描边
阴影效果实现
旋转和缩放变换
Spring 动画应用

5. term_card.py（PIL 备选方案）

纯 Python PIL 实现的名词卡片生成器：

圆角矩形绘制
渐变边框（Pillow 模拟）
文字布局和自动换行
动画效果（滑入、淡出）

6. animations.py

动画工具函数库（用于 PIL 后端）：

spring(): Spring 物理引擎实现
- 参数：frame, fps, from_value, to_value, damping, stiffness
- 模拟 Remotion 风格弹性动画
interpolate(): 线性插值函数
- 支持任意输入/输出范围映射
- 支持超出范围处理（clamp/extend/wrap）

模板系统

9 个 HTML 模板位于 templates/ 目录，每个对应一种组件：

模板	组件类型	用途
fancy-text.html	花字	概括观点短语
term-card.html	名词卡片	解释专业术语
lower-third.html	人物条	显示嘉宾信息
chapter-title.html	章节标题	话题切换标题
quote-callout.html	金句卡片	突出精彩言论
animated-stats.html	数据动画	展示数字数据
bullet-points.html	要点列表	总结核心要点
social-bar.html	社交条	社交媒体引导
video-config.json.template	配置模板	JSON 配置示例

模板特点：

独立的 HTML 结构，可单独测试
JavaScript initAnimation(config) 函数接收配置
seek(timeMs) 方法用于帧控制（Playwright 调用）
CSS 变量支持主题切换
Anime.js 动画库支持

主题系统

CSS 主题在 static/css/ 目录：

主题	文件	特点	场景
notion	theme-notion.css	温暖知识风，柔和渐变	教育、知识分享
cyberpunk	theme-cyberpunk.css	霓虹未来感，鲜艳对比	科技、前沿话题
apple	theme-apple.css	极简优雅，中性色系	商务、专业访谈
aurora	theme-aurora.css	渐变流光，炫彩效果	创意、艺术内容

每个主题通过 CSS 变量定义：

:root[data-theme="notion"] {
  --primary-color: #f5b041;
  --secondary-color: #3498db;
  --accent-color: #e74c3c;
  /* ... */
}

模板通过 data-theme 属性激活主题。

动画引擎

Anime.js 集成

用于浏览器后端的帧动画
支持 Spring 物理、缓动曲线等高级效果
通过 seek() 方法实现帧级控制

Spring 动画原理

x(t) = to_value - (to_value - from_value) * exp(-damping*t) * cos(stiffness*t)

通过调整 damping 和 stiffness 参数实现不同的弹性效果。

配置文件格式

JSON 配置包含以下顶级字段：

{
  "theme": "notion",           # 选择主题
  "lowerThirds": [...],        # 人物条数组
  "chapterTitles": [...],      # 章节标题数组
  "keyPhrases": [...],         # 花字数组
  "termDefinitions": [...],    # 名词卡片数组
  "quotes": [...],             # 金句卡片数组
  "stats": [...],              # 数据动画数组
  "bulletPoints": [...],       # 要点列表数组
  "socialBars": [...]          # 社交条数组
}

数据流详解

1. 配置阶段

用户提供视频 + 字幕
    ↓
ContentAnalyzer.analyze_subtitle() 读取 .srt
    ↓
返回 8 种类型的建议对象列表
    ↓
用户编辑或确认建议
    ↓
生成或修改 config.json

2. 渲染阶段（Browser 后端）

video_processor 加载配置
    ↓
对每个组件：
  - 确定时间范围
  - 创建 BrowserRenderer 实例
  - 加载对应 HTML 模板
  - 通过 JavaScript 注入配置
  - 循环渲染帧：
    * 计算当前时间
    * 调用 seek(timeMs)
    * Playwright 截图
    * 保存 PNG 序列
  - 使用 MoviePy ImageClip 构建视频层
    ↓
合并所有层（原视频 + 效果层）
    ↓
导出最终视频

3. 渲染阶段（PIL 后端）

video_processor 加载配置
    ↓
对每个组件：
  - 确定时间范围和帧数
  - 循环渲染帧：
    * 调用 fancy_text.py / term_card.py
    * 应用 animations.py 动画函数
    * 使用 PIL 绘制到内存
    * 保存 PNG 序列
  - 使用 MoviePy ImageClip 构建视频层
    ↓
合并所有层（原视频 + 效果层）
    ↓
导出最终视频

文件依赖关系

video_processor.py （主）
├── browser_renderer.py
│   ├── templates/*.html
│   └── static/css/*.css
│       ├── effects.css
│       └── theme-*.css
├── fancy_text.py （PIL 备选）
│   └── animations.py
├── term_card.py （PIL 备选）
│   └── animations.py
├── content_analyzer.py
├── moviepy
│   ├── VideoFileClip
│   ├── CompositeVideoClip
│   └── ImageClip
└── 配置文件
    └── config.json

扩展指南

添加新组件

1. 创建 HTML 模板

在 templates/ 目录创建 your-component.html，包含：

<script>
function initAnimation(config) {
  // 初始化：使用 config 参数设置 DOM 元素
  // 返回 totalMs：动画总时长
}

function seek(timeMs) {
  // 关键帧：根据 timeMs 设置动画状态
  // 由 Playwright 调用
}
</script>

2. 添加渲染方法

在 BrowserRenderer 类中添加：

def render_your_component_frames(self, config, output_dir=None):
    # 类似 render_fancy_text_frames 的实现
    pass

3. 在 video_processor.py 中注册

在 _generate_clips_browser() 中添加分支处理新组件。

4. 更新 content_analyzer.py

添加对应的 Suggestion dataclass。

5. 添加配置验证

在配置加载时验证新组件的必需字段。

添加新主题

1. 创建 CSS 文件

在 static/css/ 目录创建 theme-yourtheme.css：

:root[data-theme="yourtheme"] {
  --primary-color: #...;
  --secondary-color: #...;
  --accent-color: #...;
  --bg-color: #...;
  /* ... */
}

2. 在模板中引用

<link rel="stylesheet" href="../static/css/theme-yourtheme.css">

3. 更新文档

在 SKILL.md 中列出新主题。

性能考虑

Browser 后端性能

优点：高质量输出，支持复杂 CSS/动画
缺点：需要 Chromium，较慢（但可控）
优化：
- 使用 --headless 模式
- 预热浏览器实例
- 批量渲染多组件时复用实例

PIL 后端性能

优点：快速，无额外依赖
缺点：效果有限，不支持复杂动画
优化：
- 预计算变换矩阵
- 使用 NumPy 加速计算

依赖分析

核心依赖

moviepy>=1.0.3: 视频合成
pillow>=10.0.0: 图像处理（两个后端都需要）
numpy>=1.24.0: 数值计算
pysrt>=1.1.2: SRT 字幕解析
playwright>=1.40.0: 浏览器自动化（可选）

依赖大小

总计：约 100-150MB（包括 Playwright + Chromium）
仅 PIL 后端：约 50-80MB

故障排除

Playwright/Chromium 问题

# 手动安装
pip install playwright
playwright install chromium

# 验证
playwright codegen --browser chromium

MoviePy 依赖问题

# macOS
brew install ffmpeg

# Ubuntu
sudo apt-get install ffmpeg

# 验证
moviepy-script --version

内存问题

长视频：分段处理或降低分辨率
多组件：批量处理时控制并发

测试策略

单元测试

动画函数：spring(), interpolate()
配置解析和验证
渲染器初始化

集成测试

完整工作流：输入 → 渲染 → 输出
两个后端对比（视觉一致性）
不同主题的渲染

性能测试

帧渲染速度
内存使用
长视频处理

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History