xiaoxia/xiaoxia-saas
1
0
Fork 0
Code Issues 11 Pull Requests 2 Actions Packages Projects Releases 7 Wiki Activity

feat: 转场特效引擎 — 14种转场预设 + TransitionEngine抽象 + 降级策略 #293

Merged
xiaoxia merged 1 commits from feat/transition-engine into develop 2026-07-14 11:03:56 +08:00
Conversation 1 Commits 1 Files Changed 12
+958 -6
xiaoxia commented 2026-07-14 00:08:58 +08:00
Owner
Copy Link
Copy Source

转场特效引擎

基于 FFmpeg xfade 滤镜的统一转场抽象层，为统一渲染管道提供镜头间过渡效果能力。

核心能力

1. TransitionEngine 抽象层

  • TransitionType 枚举：14种转场效果统一管理
  • TransitionConfig 配置类：解析+验证+边界钳制
  • TransitionEngine 引擎类：封装转场构建、降级、批量解析
  • 新增转场只需加枚举项 + 映射，无需改核心逻辑

2. 14种转场预设

类别 效果
基础 淡入淡出(fade)、溶解(dissolve)
滑入 左/右/上/下滑入 (slideleft/right/up/down)
缩放 缩放(zoom)
擦除 左/右/上/下擦除 (wipeleft/right/up/down)
特效 圆形扩散(circlecrop)、矩形扩散(rectcrop)

3. 转场时长

  • 可配置范围：0.3s ~ 2.0s
  • 默认值：0.5s
  • 超出范围自动钳制，不报错
  • 短素材自动减半（不超过片段时长的50%）

4. 降级策略

  • 不支持的转场效果 → 自动降级为硬切(cut)
  • 失败不阻断渲染流程
  • 只打 warning 日志

5. 剪辑计划集成

  • EditPlanClip 新增 transition_duration 字段
  • transition_effect 已存在，扩展了支持的类型
  • 0 表示使用全局默认值，向后兼容

6. 别名系统

  • 支持下划线写法：slide_left → slideleft
  • 支持简写：wipe → wipeleft、zoom → zoomin
  • 支持别名：crossfade → dissolve
  • 大小写不敏感

改动文件 (10个)

  • 新增 transition_engine.py — 转场引擎核心 (~500行)
  • 修改 ffmpeg_utils.py — 扩展转场映射 (17种)
  • 修改 unified_render_service.py — 接入TransitionEngine
  • 修改 edit_plan_clip.py — 新增transition_duration字段
  • 修改 models.py — 数据库新增列
  • 修改 edit_plan_clip_repository.py — ORM映射
  • 修改 edit_plan_service.py — Service层
  • 修改 edit_plans.py — API Schema
  • 修改 edit_plans_timeline.py — 响应体
  • 新增 test_transition_engine.py — 54个单测

测试结果

  • ✅ 54个转场引擎单测 全绿
  • ✅ 84个统一渲染测试 全绿（无回归）
  • ✅ 16个渲染适配器测试 全绿（无回归）
## 转场特效引擎 基于 FFmpeg xfade 滤镜的统一转场抽象层，为统一渲染管道提供镜头间过渡效果能力。 ## 核心能力 ### 1. TransitionEngine 抽象层 - `TransitionType` 枚举：14种转场效果统一管理 - `TransitionConfig` 配置类：解析+验证+边界钳制 - `TransitionEngine` 引擎类：封装转场构建、降级、批量解析 - 新增转场只需加枚举项 + 映射，无需改核心逻辑 ### 2. 14种转场预设 | 类别 | 效果 | |------|------| | 基础 | 淡入淡出(fade)、溶解(dissolve) | | 滑入 | 左/右/上/下滑入 (slideleft/right/up/down) | | 缩放 | 缩放(zoom) | | 擦除 | 左/右/上/下擦除 (wipeleft/right/up/down) | | 特效 | 圆形扩散(circlecrop)、矩形扩散(rectcrop) | ### 3. 转场时长 - 可配置范围：0.3s ~ 2.0s - 默认值：0.5s - 超出范围自动钳制，不报错 - 短素材自动减半（不超过片段时长的50%） ### 4. 降级策略 - 不支持的转场效果 → 自动降级为硬切(cut) - 失败不阻断渲染流程 - 只打 warning 日志 ### 5. 剪辑计划集成 - `EditPlanClip` 新增 `transition_duration` 字段 - `transition_effect` 已存在，扩展了支持的类型 - 0 表示使用全局默认值，向后兼容 ### 6. 别名系统 - 支持下划线写法：`slide_left` → `slideleft` - 支持简写：`wipe` → `wipeleft`、`zoom` → `zoomin` - 支持别名：`crossfade` → `dissolve` - 大小写不敏感 ## 改动文件 (10个) - 新增 `transition_engine.py` — 转场引擎核心 (~500行) - 修改 `ffmpeg_utils.py` — 扩展转场映射 (17种) - 修改 `unified_render_service.py` — 接入TransitionEngine - 修改 `edit_plan_clip.py` — 新增transition_duration字段 - 修改 `models.py` — 数据库新增列 - 修改 `edit_plan_clip_repository.py` — ORM映射 - 修改 `edit_plan_service.py` — Service层 - 修改 `edit_plans.py` — API Schema - 修改 `edit_plans_timeline.py` — 响应体 - 新增 `test_transition_engine.py` — 54个单测 ## 测试结果 - ✅ 54个转场引擎单测 全绿 - ✅ 84个统一渲染测试 全绿（无回归） - ✅ 16个渲染适配器测试 全绿（无回归）
xiaoxia commented 2026-07-14 09:17:31 +08:00
Author
Owner
Copy Link
Copy Source

✅ 代码审计通过

10个文件/921行，转场引擎架构设计优秀。

审查要点确认：

  • ✅ TransitionType 枚举 + 别名映射 + 标准化名称解析，扩展性好
  • ✅ TransitionConfig.parse 降级策略完善：不支持的转场自动fallback到fade
  • ✅ 转场时长边界钳制：0.3s~2s，且不超过clip时长的一半（保守限制）
  • ✅ 14种转场预设，分类清晰（基础/滑入/缩放/擦除/特殊）
  • ✅ 490行测试覆盖：枚举解析、配置验证、降级策略、xfade链构建
  • ✅ UnifiedRenderService 集成点干净，替换了原有的 build_xfade_filter_chain 直接调用

架构亮点： 新增转场只需加枚举项 + XFADE_TRANSITION_MAP映射，无需改核心逻辑

## ✅ 代码审计通过 10个文件/921行，转场引擎架构设计优秀。 **审查要点确认：** - ✅ TransitionType 枚举 + 别名映射 + 标准化名称解析，扩展性好 - ✅ TransitionConfig.parse 降级策略完善：不支持的转场自动fallback到fade - ✅ 转场时长边界钳制：0.3s~2s，且不超过clip时长的一半（保守限制） - ✅ 14种转场预设，分类清晰（基础/滑入/缩放/擦除/特殊） - ✅ 490行测试覆盖：枚举解析、配置验证、降级策略、xfade链构建 - ✅ UnifiedRenderService 集成点干净，替换了原有的 build_xfade_filter_chain 直接调用 **架构亮点：** 新增转场只需加枚举项 + XFADE_TRANSITION_MAP映射，无需改核心逻辑
xiaoxia force-pushed feat/transition-engine from 80edb5dd91 to 762d7838c9 2026-07-14 09:35:49 +08:00 Compare
xiaoxia force-pushed feat/transition-engine from b49d3683a8 to 27f92a5aaf 2026-07-14 10:13:18 +08:00 Compare
xiaoxia force-pushed feat/transition-engine from 27f92a5aaf to ed367de689 2026-07-14 10:36:49 +08:00 Compare
xiaoxia added 1 commit 2026-07-14 10:59:41 +08:00
feat: 转场特效引擎 — TransitionEngine + 14种转场预设 + 时长边界校验 + 降级策略
CI/CD Pipeline / Unit Tests (pull_request) Successful in 1m14s
Details
CI/CD Pipeline / Frontend Lint (pull_request) Successful in 1m23s
Details
CI/CD Pipeline / Validate Code Quality And Tests (pull_request) Successful in 3m11s
Details
CI/CD Pipeline / Build & Push Staging (Watchtower auto-deploy) (pull_request) Has been skipped
Details
CI/CD Pipeline / Build Production Runtime Images (pull_request) Has been skipped
Details
CI/CD Pipeline / Staging E2E Tests (pull_request) Has been skipped
Details
CI/CD Pipeline / Staging API Integration Tests (pull_request) Has been skipped
Details
CI/CD Pipeline / Deploy Production (pull_request) Has been skipped
Details
CI/CD Pipeline / Production Browser E2E (pull_request) Has been skipped
Details
CI/CD Pipeline / Integration Tests (pull_request) Failing after 1m32s
Details
7dbff690cd
xiaoxia force-pushed feat/transition-engine from d85a53ef7a to 7dbff690cd 2026-07-14 10:59:41 +08:00 Compare
xiaoxia merged commit ff38ee0f2b into develop 2026-07-14 11:03:56 +08:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
P0
阻塞性，必须立即处理
 P1
高优先级
 P2
中优先级
 P3
低优先级/后考虑
 architecture
架构设计
 backend
后端相关
 blocked
阻塞中
 bug
Bug修复
 ci-bug
CI本身的bug
 ci-optimization
CI优化类任务
 ci-pipeline
CI流水线/workflow相关
 cleanup
代码清理
 devops
运维/部署/CI
 documentation
文档相关
 feature
新功能
 frontend
前端相关
 question
需要讨论确认
 ready
PR CI通过，可合并
 refactor
代码重构
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
auto-approve-bot xiaoxia
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#293
Delete Branch "feat/transition-engine"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?