fix(#549): 预设配音无声 - 字幕对齐TTS配音模式 + ASR缓存 (#628)

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com> Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>
2026-07-20 12:49:54 +08:00
parent e5fffe40c1
commit f01f4803e4
3 changed files with 511 additions and 3 deletions
@@ -0,0 +1,153 @@
+# 统一渲染引擎效果层全模式验证报告
+
+> 背景：#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）
+
+**建议后续补充端到端集成测试**：用真实素材跑四种模式的完整渲染链路，验证输出音视频质量。