feat: 片段时长自动对齐配音时长 #1693

Merged

xiaoxia merged 1 commits from feature/clip-duration-voice-alignment into develop 2026-09-04 16:09:24 +08:00

Conversation 3 Commits 1 Files Changed 2

+361 -9

xiaoxia commented 2026-09-04 16:05:50 +08:00

Owner

Copy Link

Copy Source

需求

后端生成视频时，片段总时长自动对齐配音时长，最终视频时长 = 配音时长。

实现

核心逻辑（在渲染前执行）

1. 探测配音音频时长 (_get_voice_audio_duration)

   • 使用 probe_duration 获取配音文件时长
   • 无配音或探测失败时返回 0.0

2. 调整片段时长 (_align_clips_to_voice_duration)

   • 计算片段总时长与配音时长的比例 ratio = voice_duration / total_clips_duration
   • abs(ratio - 1.0) <= 0.05（±5% 以内）→ 不调整
   • ratio < 1.0（片段比配音长）→ 按比例裁剪每段末尾
   • ratio > 1.0（片段比配音短）→ 按比例慢放每段（下限 0.25x）

3. 调用时机

   • 在 render() 中，clips 分组为 layers 后、计算视频总时长前调用
   • 调整后重新计算 video_duration_final 用于后续渲染

调整范围

• ✅ 调整：main、broll、background 视频图层
• ❌ 不调整：audio、overlay、pip 等非视频图层

边界处理

• 速度下限 0.25x（避免过慢）
• 裁剪下限 0.1s（避免过短）
• trim_config 同步调整

测试

新增 tests/unit/test_voice_duration_alignment.py（11 个测试）：

• test_no_voice_audio_no_adjustment - 无配音不调整
• test_ratio_within_5_percent_no_adjustment - ±5% 内不调整
• test_ratio_less_than_1_trim_clips - ratio < 1 裁剪
• test_ratio_greater_than_1_slowdown_clips - ratio > 1 减速
• test_speed_lower_bound_025 - 速度下限 0.25x
• test_only_video_layers_adjusted - 只调整视频图层
• test_multiple_video_layers_all_adjusted - 多图层全部调整
• test_trim_config_also_adjusted - trim_config 同步调整
• test_no_voiceover_path_returns_zero - 无路径返回 0
• test_nonexistent_file_returns_zero - 文件不存在返回 0
• test_probes_duration_from_file - 正确探测时长

153 个相关测试全通过

未实现的边界场景

以下场景本次未实现，后续如有需要可补充：

• ratio > 1.1 时最后一段末尾冻结定格（需要 FFmpeg tpad 滤镜）
• ratio > 1.5 时最后一段循环播放（需要复制 clip 或 FFmpeg loop 滤镜）

## 需求 后端生成视频时，片段总时长自动对齐配音时长，最终视频时长 = 配音时长。 ## 实现 ### 核心逻辑（在渲染前执行） 1. **探测配音音频时长** (`_get_voice_audio_duration`) - 使用 `probe_duration` 获取配音文件时长 - 无配音或探测失败时返回 0.0 2. **调整片段时长** (`_align_clips_to_voice_duration`) - 计算片段总时长与配音时长的比例 `ratio = voice_duration / total_clips_duration` - `abs(ratio - 1.0) <= 0.05`（±5% 以内）→ 不调整 - `ratio < 1.0`（片段比配音长）→ 按比例裁剪每段末尾 - `ratio > 1.0`（片段比配音短）→ 按比例慢放每段（下限 0.25x） 3. **调用时机** - 在 `render()` 中，clips 分组为 layers 后、计算视频总时长前调用 - 调整后重新计算 `video_duration_final` 用于后续渲染 ### 调整范围 - ✅ 调整：`main`、`broll`、`background` 视频图层 - ❌ 不调整：`audio`、`overlay`、`pip` 等非视频图层 ### 边界处理 - 速度下限 0.25x（避免过慢） - 裁剪下限 0.1s（避免过短） - trim_config 同步调整 ## 测试 新增 `tests/unit/test_voice_duration_alignment.py`（11 个测试）： - `test_no_voice_audio_no_adjustment` - 无配音不调整 - `test_ratio_within_5_percent_no_adjustment` - ±5% 内不调整 - `test_ratio_less_than_1_trim_clips` - ratio < 1 裁剪 - `test_ratio_greater_than_1_slowdown_clips` - ratio > 1 减速 - `test_speed_lower_bound_025` - 速度下限 0.25x - `test_only_video_layers_adjusted` - 只调整视频图层 - `test_multiple_video_layers_all_adjusted` - 多图层全部调整 - `test_trim_config_also_adjusted` - trim_config 同步调整 - `test_no_voiceover_path_returns_zero` - 无路径返回 0 - `test_nonexistent_file_returns_zero` - 文件不存在返回 0 - `test_probes_duration_from_file` - 正确探测时长 **153 个相关测试全通过** ## 未实现的边界场景 以下场景本次未实现，后续如有需要可补充： - `ratio > 1.1` 时最后一段末尾冻结定格（需要 FFmpeg `tpad` 滤镜） - `ratio > 1.5` 时最后一段循环播放（需要复制 clip 或 FFmpeg `loop` 滤镜）

xiaoxia added 1 commit 2026-09-04 16:05:51 +08:00

feat: 片段时长自动对齐配音时长 ... 2bf63c0662

核心逻辑（在渲染前执行）：
- 探测配音音频文件时长
- 计算片段总时长与配音时长的比例
- ±5% 以内不调整
- ratio < 1（片段比配音长）：按比例裁剪每段末尾
- ratio > 1（片段比配音短）：按比例慢放每段（下限 0.25x）

实现：
- 新增 _get_voice_audio_duration() 方法探测配音音频时长
- 新增 _align_clips_to_voice_duration() 方法调整片段时长
- 在 render() 中 clips 分组后、时长计算前调用对齐逻辑
- 调整后重新计算视频总时长用于后续渲染

测试：
- 新增 11 个单元测试覆盖各种场景
- 153 个相关测试全通过

gitea-actions bot commented 2026-09-04 16:07:36 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

项目	详情
PR号	#1693
预览链接	https://pr-1693.preview.xiaoxiajianji.com
API环境	staging

💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。

🔄 每次提交新代码后预览环境会自动更新。

🗑️ PR 关闭或合并后，预览环境会自动清理。

🚀 **预览环境已部署** | 项目 | 详情 | |------|------| | PR号 | #1693 | | 预览链接 | [https://pr-1693.preview.xiaoxiajianji.com](https://pr-1693.preview.xiaoxiajianji.com) | | API环境 | staging | > 💡 预览环境使用 staging API 数据，请勿在预览环境中操作重要数据。 > > 🔄 每次提交新代码后预览环境会自动更新。 > > 🗑️ PR 关闭或合并后，预览环境会自动清理。

xiaoxia reviewed 2026-09-04 16:09:18 +08:00

xiaoxia left a comment

Author

Owner

Copy Link

Copy Source

LGTM ✅ CI 全绿

LGTM ✅ CI 全绿

xiaoxia merged commit db244fe14c into develop 2026-09-04 16:09:24 +08:00

gitea-actions bot commented 2026-09-04 16:09:53 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

PR #1693 已关闭或合并，对应的预览环境已被清理。

如有需要，可以重新打开 PR 来重新生成预览环境。

🗑️ **预览环境已清理** PR #1693 已关闭或合并，对应的预览环境已被清理。 > 如有需要，可以重新打开 PR 来重新生成预览环境。

xiaoxia referenced this pull request 2026-09-04 23:31:28 +08:00

Release: 同步 develop 到 main（PR #1654~#1698 全量同步） #1699

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

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1693