feat: 视频调速引擎（快进/慢放） #294

Merged

xiaoxia merged 1 commits from feat/video-speed-control into develop 2026-07-14 11:36:24 +08:00

Conversation 1 Commits 1 Files Changed 11

+624 -31

xiaoxia commented 2026-07-14 00:36:48 +08:00

Owner

Copy Link

Copy Source

功能描述

在统一渲染管道中加入视频播放速度调整能力，支持快进/慢放。

核心能力

1. 调速核心引擎 (speed_engine.py)

• SpeedConfig 配置模型：speed (0.25-4.0) + pitch_correct (默认true)
• SpeedEngine 引擎类：封装视频/音频滤镜构建、时长计算、边界校验
• 速度范围 0.25x ~ 4x，超出自动钳制，不阻断渲染

2. 视频调速

• 基于 FFmpeg setpts 滤镜
• 在 clip 预处理环节（trim 之后、scale 之前）插入
• 支持分段调速：每个 clip 独立 playback_speed 字段

3. 音频调速（音画同步）

• 基于 FFmpeg atempo 滤镜，保持音调不变
• 超范围（<0.5x 或 >2.0x）自动多级串联：
  • 0.25x → atempo=0.5,atempo=0.5
  • 4x → atempo=2.0,atempo=2.0
  • 3x → atempo=2.0,atempo=1.5
• 视频和音频同步变速，确保音画同步

4. 整段/分段调速

• 分段调速：每个 clip 独立设置速度
• 整段调速：所有 clip 设相同 speed 即可

5. 降级策略

• 速度超出 0.25~4.0 范围自动钳制
• 无效值回退到 1.0（原速）
• 不阻断渲染流程

改动文件

文件	说明
apps/worker/video_processing/speed_engine.py	新增：调速引擎核心模块
apps/worker/video_processing/unified_render_service.py	修改：Step 1 插入视频调速 + ResolvedClip 扩展 + 时长计算
apps/worker/video_processing/render_audio.py	修改：音频 atempo 调速
packages/domain/edit_plan_clip.py	修改：新增 playback_speed 字段
packages/adapters/sqlalchemy_impl/models.py	修改：新增 playback_speed 列
packages/adapters/sqlalchemy_impl/edit_plan_clip_repository.py	修改：同步字段映射
apps/api/app/services/edit_plan_service.py	修改：create/update 支持 playback_speed
apps/api/app/api/routes/edit_plans.py	修改：响应体新增字段
tests/unit/test_speed_engine.py	新增：45 个单测

测试

• ✅ 45 个新增单测全绿
• ✅ 100 个现有渲染/适配器测试全绿，无回归

向后兼容

• playback_speed 默认 1.0（原速），不传则不启用
• 旧数据不受影响，默认原速渲染
• 数据库字段有默认值，无需数据迁移

## 功能描述 在统一渲染管道中加入视频播放速度调整能力，支持快进/慢放。 ## 核心能力 ### 1. 调速核心引擎 (speed_engine.py) - SpeedConfig 配置模型：speed (0.25-4.0) + pitch_correct (默认true) - SpeedEngine 引擎类：封装视频/音频滤镜构建、时长计算、边界校验 - 速度范围 0.25x ~ 4x，超出自动钳制，不阻断渲染 ### 2. 视频调速 - 基于 FFmpeg setpts 滤镜 - 在 clip 预处理环节（trim 之后、scale 之前）插入 - 支持分段调速：每个 clip 独立 playback_speed 字段 ### 3. 音频调速（音画同步） - 基于 FFmpeg atempo 滤镜，保持音调不变 - 超范围（<0.5x 或 >2.0x）自动多级串联： - 0.25x → atempo=0.5,atempo=0.5 - 4x → atempo=2.0,atempo=2.0 - 3x → atempo=2.0,atempo=1.5 - 视频和音频同步变速，确保音画同步 ### 4. 整段/分段调速 - 分段调速：每个 clip 独立设置速度 - 整段调速：所有 clip 设相同 speed 即可 ### 5. 降级策略 - 速度超出 0.25~4.0 范围自动钳制 - 无效值回退到 1.0（原速） - 不阻断渲染流程 ## 改动文件 | 文件 | 说明 | |------|------| | apps/worker/video_processing/speed_engine.py | 新增：调速引擎核心模块 | | apps/worker/video_processing/unified_render_service.py | 修改：Step 1 插入视频调速 + ResolvedClip 扩展 + 时长计算 | | apps/worker/video_processing/render_audio.py | 修改：音频 atempo 调速 | | packages/domain/edit_plan_clip.py | 修改：新增 playback_speed 字段 | | packages/adapters/sqlalchemy_impl/models.py | 修改：新增 playback_speed 列 | | packages/adapters/sqlalchemy_impl/edit_plan_clip_repository.py | 修改：同步字段映射 | | apps/api/app/services/edit_plan_service.py | 修改：create/update 支持 playback_speed | | apps/api/app/api/routes/edit_plans.py | 修改：响应体新增字段 | | tests/unit/test_speed_engine.py | 新增：45 个单测 | ## 测试 - ✅ 45 个新增单测全绿 - ✅ 100 个现有渲染/适配器测试全绿，无回归 ## 向后兼容 - playback_speed 默认 1.0（原速），不传则不启用 - 旧数据不受影响，默认原速渲染 - 数据库字段有默认值，无需数据迁移

xiaoxia commented 2026-07-14 09:17:32 +08:00

Author

Owner

Copy Link

Copy Source

✅ 代码审计通过

9个文件/582行，调速引擎实现质量高。

审查要点确认：

• ✅ SpeedConfig 边界钳制完善：0.25x~4x，负值/零值自动回退到1.0
• ✅ 音频 atempo 多级串联算法正确：所有级联乘积等于原速度，每级都在0.5~2.0范围内
• ✅ 视频 setpts + 音频 atempo 音画同步
• ✅ 270行测试全覆盖：配置解析、视频滤镜、音频滤镜、时长计算、便捷方法
• ✅ 单clip和多clip场景都做了调速适配
• ✅ 与现有架构无缝集成，默认speed=1.0完全不影响现有渲染

测试亮点： _split_atempo_stages 的乘积验证 + 范围验证，非常严谨

## ✅ 代码审计通过 9个文件/582行，调速引擎实现质量高。 **审查要点确认：** - ✅ SpeedConfig 边界钳制完善：0.25x~4x，负值/零值自动回退到1.0 - ✅ 音频 atempo 多级串联算法正确：所有级联乘积等于原速度，每级都在0.5~2.0范围内 - ✅ 视频 setpts + 音频 atempo 音画同步 - ✅ 270行测试全覆盖：配置解析、视频滤镜、音频滤镜、时长计算、便捷方法 - ✅ 单clip和多clip场景都做了调速适配 - ✅ 与现有架构无缝集成，默认speed=1.0完全不影响现有渲染 **测试亮点：** _split_atempo_stages 的乘积验证 + 范围验证，非常严谨

xiaoxia force-pushed feat/video-speed-control from ddba3eca29 to 82a4f35814 2026-07-14 09:37:17 +08:00 Compare

xiaoxia force-pushed feat/video-speed-control from 82a4f35814 to 9c19da3c34 2026-07-14 10:13:53 +08:00 Compare

xiaoxia force-pushed feat/video-speed-control from 9c19da3c34 to 11f3635b72 2026-07-14 10:32:59 +08:00 Compare

xiaoxia force-pushed feat/video-speed-control from 74145ea9ec to 1e842f2e17 2026-07-14 11:29:14 +08:00 Compare

xiaoxia added 1 commit 2026-07-14 11:32:28 +08:00

feat: 视频调速引擎（快进/慢放） ... ca2e044246

- SpeedEngine 抽象层：SpeedConfig + SpeedEngine，支持 0.25x~4x 变速
- 视频调速：基于 FFmpeg setpts，在 clip 预处理环节插入
- 音频调速：基于 atempo，超范围自动多级串联（如 4x=2.0*2.0）
- 音画同步：视频音频同时调速，音调自动修正
- 分段调速：每个 clip 独立 playback_speed 字段
- 整段调速：所有 clip 设相同 speed 即可实现
- 降级策略：速度超出范围自动钳制，不阻断渲染
- 领域模型：EditPlanClip 新增 playback_speed 字段
- 数据库：EditPlanClipModel 新增 playback_speed 列
- API：create_clip / update_clip 支持 playback_speed 参数
- 45 个新增单测全绿 + 100 个现有测试全绿，无回归

xiaoxia force-pushed feat/video-speed-control from 1e842f2e17 to ca2e044246 2026-07-14 11:32:28 +08:00 Compare

xiaoxia merged commit 2081c72be6 into develop 2026-07-14 11:36:24 +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

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#294