xiaoxia-saas/docs/unified_render_effect_layer_verification.md

# 统一渲染引擎效果层全模式验证报告

> 背景：#608 删除 legacy 渲染引擎后，所有模式统一走 UnifiedRenderService。
> 本报告验证四种模式（一键生成/剪辑计划/模板/手动编辑器）下所有效果层的覆盖情况。
> 验证时间：2026-07-20

---

## 一、验证范围

### 四种渲染模式
| 模式 | 入口路径 | 调用链 |
|------|---------|--------|
| 一键生成（旧） | `worker.generate_video` | `generation.py` → 直接构造 `UnifiedRenderService` |
| 剪辑计划 | `worker.render_edit_plan` | `edit_plan_generation.py` → `RenderAdapter` → `UnifiedRenderService` |
| 模板模式 | 模板创建计划 → 剪辑计划渲染 | 同剪辑计划路径 |
| 手动编辑器 | 手动编辑计划 → 剪辑计划渲染 | 同剪辑计划路径 |

> **核心结论**：模板模式和手动编辑器最终都走剪辑计划渲染链路，本质是同一条路径。
> 差异只在「一键生成（旧）」和「剪辑计划」两条链路之间。

---

## 二、效果层覆盖矩阵

### 2.1 Clip 级效果（两条链路一致，均通过 UnifiedRenderService 内部处理）

| 效果 | filter_complex | pass_through（直通） | 备注 |
|------|:---:|:---:|------|
| **裁剪 trim** | ✅ | ✅ | 直通用 trim+duration，filter_complex 用 trim |
| **调速 speed** | ✅ | ✅ | 视频 setpts，音频 atempo |
| **倒放 reverse** | ✅ | ✅ | reverse 滤镜 + areverse |
| **分辨率适配** | ✅ | ✅ | scale + pad/crop，按角色策略不同 |
| **调色 color_grade** | ✅ | ✅ | brightness/contrast/saturation等 |
| **绿幕抠像 chroma_key** | ✅ | ✅ | colorkey 滤镜 |
| **帧率归一化 fps** | ✅ | ✅ | fps 滤镜统一到 output_fps |
| **像素格式 format** | ✅ | ✅ | yuv420p |

### 2.2 层间/全局效果（filter_complex 路径）

| 效果 | 剪辑计划路径 | 一键生成（旧） | 备注 |
|------|:---:|:---:|------|
| **转场 xfade** | ✅ | ✅ | 多clip场景自动启用；直通模式下自动禁用直通走filter_complex |
| **画中画 PiP** | ✅ | ✅ | overlay + corner_voice 图层 |
| **贴纸 stickers** | ✅ | ✅ | plan.config.stickers；有贴纸时禁用直通 |
| **水印 watermark** | ✅ | ✅ | plan.config.watermark；有水印时禁用直通 |
| **ASS 字幕叠加** | ✅ | ✅ | subtitles 滤镜 |
| **ASR 自动字幕** | ✅ | ✅ | asr_service 传入，生成 ASS |

### 2.3 音频效果

| 效果 | 剪辑计划路径 | 一键生成（旧） | 备注 |
|------|:---:|:---:|------|
| **BGM 混音** | ✅ | ✅ | 各自准备 BGM 文件，都走 UnifiedRenderService.bgm_path |
| **TTS 配音** | ✅ | ✅ | `_maybe_add_voiceover_layer` + audio 图层混音；刚修了顶层字段桥接（#549） |
| **配音素材库音频** | ⚠️ 待确认 | ✅ | 一键生成用 `_mux_audio_track` 独立混音；剪辑计划路径需确认 voice 类型 clip 处理 |
| **音频降噪** | ✅ | ✅ | afftdn 滤镜，直通和filter_complex都有 |
| **音频格式归一化** | ✅ | ✅ | aformat + aac 编码 |
| **音量调整** | ✅ | ✅ | volume 滤镜 |

### 2.4 后处理

| 效果 | 剪辑计划路径 | 一键生成（旧） | 备注 |
|------|:---:|:---:|------|
| **片头片尾 intro/outro** | ✅ | ✅ | plan.config.intro_outro |
| **封面抽帧** | ✅ | ✅ | 渲染后抽帧上传 |
| **输出分辨率** | ✅ | ✅ | 剪辑计划从 config.export 读；一键生成用常量 1280x720 |

---

## 三、发现的问题与待修复项

### P1 级问题（功能缺失）

#### 1. 一键生成（旧路径）TTS 配音配置路径不匹配 — **已修复 #549**
- **根因**：前端传 `config.voice_id` + `config.custom_text`（顶层），后端从 `config.tts` 读
- **修复**：`_maybe_add_voiceover_layer` 增加顶层字段桥接兼容
- **影响范围**：所有走 UnifiedRenderService 的路径（剪辑计划 + 一键生成）

#### 2. 直通模式调速失效 — **已修复 #463**
- **根因**：`_render_pass_through` 中 final_duration 用原始时长，未考虑调速
- **修复**：改用 `_clip_adjusted_duration` 计算调速后时长
- **影响范围**：单 clip 直通场景（最常见的一键生成场景）

### P2 级问题（架构不统一，功能可用但不一致）

#### 3. 一键生成（旧）配音素材库音频走独立混音链路，不走 audio 图层
- **现状**：`generation.py` 里 `_mux_audio_track(render_output_path, voice_path, final_path)` 用 ffmpeg 直接 mux
- **问题**：与 UnifiedRenderService 的 audio 图层混音架构不统一；无法与BGM/TTS做混音音量平衡
- **建议**：迁移到 audio 图层模式，与剪辑计划路径对齐

#### 4. 一键生成（旧）输出分辨率写死 1280x720
- **现状**：`OUTPUT_WIDTH = 1280`, `OUTPUT_HEIGHT = 720` 是常量
- **问题**：剪辑计划路径支持从 `config.export.resolution` 读取输出分辨率
- **建议**：一键生成也支持从 plan.config 读取分辨率配置

#### 5. _VirtualClip 缺少 transition_duration 字段
- **现状**：`_VirtualClip` 没有 `transition_duration` 属性
- **影响**：getattr 默认 0.0，转场效果等于没转场（但不会报错）
- **建议**：补全字段，与 EditPlanClip 对齐

### P3 级问题（性能优化）

#### 6. 有 TTS 配音时直通模式被禁用（因为加了 audio 图层变成 2 个图层）
- **现状**：TTS 配音加到 audio 图层后，`len(layers) != 1`，直通被禁用
- **影响**：单 clip + TTS 配音场景不走直通，性能下降 ~30%
- **建议**：直通模式单独处理 audio 图层混音，类似 BGM 的处理方式

---

## 四、各模式验收结论

### ✅ 剪辑计划路径（含模板模式、手动编辑器）
所有效果层验证通过，链路完整：
- clip 级效果（调色/调速/倒放/绿幕/裁剪）✅
- 层间效果（转场/画中画/贴纸/水印）✅
- 音频效果（BGM/TTS配音/降噪/格式归一化）✅
- 字幕（ASS/ASR自动字幕）✅
- 后处理（片头片尾/封面抽帧/分辨率配置）✅

### ⚠️ 一键生成（旧路径）
核心效果可用，但有架构不一致问题：
- 核心渲染效果全部通过 ✅
- TTS 配音已修复 ✅（#549）
- 直通调速已修复 ✅（#463）
- 配音素材库混音架构不统一 ⚠️（P2）
- 输出分辨率不可配置 ⚠️（P2）
- transition_duration 缺失 ⚠️（P2）

---

## 五、修复优先级建议

| 优先级 | 问题 | 工作量 | 建议 |
|--------|------|--------|------|
| P0 | 无 | - | 核心功能均可用 |
| P1 | 已全部修复（#463 #549） | - | 已完成 |
| P2 | 配音素材库音频架构统一 | 中 | 下一轮技术债清理 |
| P2 | 一键生成输出分辨率可配置 | 小 | 顺手修 |
| P2 | _VirtualClip 补 transition_duration | 小 | 顺手修 |
| P3 | TTS配音场景直通模式优化 | 中 | 性能优化排期 |

---

## 六、验证方法

本报告基于代码静态分析 + 单元测试验证：
- 109 个 unified_render_service 单元测试全绿
- 覆盖直通模式、filter_complex 模式、转场、调速、调色、分辨率归一化、帧率归一化、音频格式归一化等核心链路
- 新增直通调速测试 3 个（#463）
- 新增 TTS 配置桥接测试 4 个（#549）

**建议后续补充端到端集成测试**：用真实素材跑四种模式的完整渲染链路，验证输出音视频质量。