perf: render-time cover frame pre-extraction + FFmpeg fallback, remove MediaKit #1360

Merged

auto-approve-bot merged 6 commits from perf/cover-frame-pre-extract into develop 2026-08-13 20:51:02 +08:00

Conversation 5 Commits 6 Files Changed 10

+891 -148

xiaoxia commented 2026-08-13 19:55:24 +08:00

Owner

Copy Link

Copy Source

Summary

Plan 2: Pre-extract cover frames during render

• thumbnail_generator.py: new extract_cover_candidates() and extract_and_upload_cover_frames() - extract 3 frames at 25%/50%/75% of video duration, upload to OSS
• render_adapter.py: new cover_candidates field on RenderAdapterResult, call frame extraction after thumbnail gen
• edit_plan_generation.py: write cover_candidates into plan.config after render success

Plan 1: FFmpeg local fallback

• generation_cover.py: cover API checks pre-stored frames first (instant return)
• ai_service.py: removed MediaKit remote API, replaced with FFmpeg HTTP range-request streaming seek (no full video download)

Bug fix

• cover_templates.py: fix config=None causing CoverTemplateResponse ValidationError (500 error)

Tests

• New test_cover_frame_pre_extract.py (15 tests)
• Updated test_mediakit_cover.py and test_shared_ai_service.py for new FFmpeg behavior

Changed files

File	Change
thumbnail_generator.py	+2 functions for cover candidate extraction
render_adapter.py	+cover_candidates field + extraction step
edit_plan_generation.py	Write candidates to plan.config
generation_cover.py	Check pre-stored frames before AI service
ai_service.py	MediaKit replaced with FFmpeg local fallback
cover_templates.py	config=t.config or {} null safety

## Summary ### Plan 2: Pre-extract cover frames during render - thumbnail_generator.py: new extract_cover_candidates() and extract_and_upload_cover_frames() - extract 3 frames at 25%/50%/75% of video duration, upload to OSS - render_adapter.py: new cover_candidates field on RenderAdapterResult, call frame extraction after thumbnail gen - edit_plan_generation.py: write cover_candidates into plan.config after render success ### Plan 1: FFmpeg local fallback - generation_cover.py: cover API checks pre-stored frames first (instant return) - ai_service.py: removed MediaKit remote API, replaced with FFmpeg HTTP range-request streaming seek (no full video download) ### Bug fix - cover_templates.py: fix config=None causing CoverTemplateResponse ValidationError (500 error) ### Tests - New test_cover_frame_pre_extract.py (15 tests) - Updated test_mediakit_cover.py and test_shared_ai_service.py for new FFmpeg behavior ## Changed files | File | Change | |------|--------| | thumbnail_generator.py | +2 functions for cover candidate extraction | | render_adapter.py | +cover_candidates field + extraction step | | edit_plan_generation.py | Write candidates to plan.config | | generation_cover.py | Check pre-stored frames before AI service | | ai_service.py | MediaKit replaced with FFmpeg local fallback | | cover_templates.py | config=t.config or {} null safety |

xiaoxia added 1 commit 2026-08-13 19:55:24 +08:00

perf: pre-extract cover frames during render + FFmpeg fallback ... bbf3006d0c

- Add extract_cover_candidates() and extract_and_upload_cover_frames()
  to thumbnail_generator.py: extract 3 frames at 25%/50%/75% of video
- Add cover_candidates field to RenderAdapterResult
- Call frame extraction after thumbnail gen in render_adapter._do_render()
- Write cover_candidates to plan.config in edit_plan_generation worker
- Check pre-stored frames in generation_cover.py before calling AI service
- Replace MediaKit remote API with FFmpeg HTTP range-request in
  _call_ai_cover_service (no full video download needed)
- Fix CoverTemplateResponse ValidationError when config is None
- Add unit tests for all new code paths
- Update existing tests to match new FFmpeg-based behavior

gitea-actions bot commented 2026-08-13 19:56:49 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

xiaoxia added 1 commit 2026-08-13 20:02:05 +08:00

style: apply black + isort + ruff formatting fixes 7ebff0dd62

xiaoxia force-pushed perf/cover-frame-pre-extract from a59c9db81d to 7ebff0dd62 2026-08-13 20:02:05 +08:00 Compare

auto-approve-bot approved these changes 2026-08-13 20:10:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-13 20:10:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-13 20:15:17 +08:00

fix: update error match pattern in test_config_schemas 003ff86115

xiaoxia added 1 commit 2026-08-13 20:27:44 +08:00

test: add diff coverage tests for _extract_frames_with_ffmpeg and pre-stored cover path 768203a794

xiaoxia added 1 commit 2026-08-13 20:34:06 +08:00

test: revert test_batch_download.py to develop original (no changes needed) 823f3fb8a3

xiaoxia force-pushed perf/cover-frame-pre-extract from 1caf9f3e42 to 823f3fb8a3 2026-08-13 20:34:06 +08:00 Compare

auto-approve-bot commented 2026-08-13 20:36:58 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

• 是否存在阻塞级问题：否
• 阻塞级问题数量：0 个

📊 审查概览

• 整体评价：通过
• 建议级问题数量：2 个

🔴 阻塞级问题（必须修复）

无

💡 改进建议（不阻塞合并）

1. [packages/shared/ai_service.py: _extract_frames_with_ffmpeg] 抽帧数量与使用逻辑不匹配

   • 具体内容：函数 _extract_frames_with_ffmpeg 默认抽取 3 帧（num_frames=3），但在调用方 _call_ai_cover_service 中仅使用了 frames[0]。如果第 1 帧抽取失败或质量不佳，代码并未尝试使用第 2、3 帧，导致额外的抽取开销浪费。
   • 建议：如果仅需要一帧，建议将 num_frames 参数改为 1 以提升性能；或者实现降级逻辑，在第 1 帧无效时尝试后续帧。

2. [apps/api/app/api/routes/generation_cover.py: generate_cover] "ai_regenerate" 逻辑可能不符合用户预期

   • 具体内容：当 cover_type 为 ai_regenerate 时，代码逻辑与 ai_frame 一致，直接返回预存的 cover_candidates[0]。如果用户当前封面已经是该帧，再次点击“重新生成”将得到完全相同的结果，造成用户困惑。
   • 建议：确认业务需求。如果“重新生成”意味着“获取一个不同的封面”，建议在 ai_regenerate 分支下从候选列表中随机选择或排除当前已选帧；如果仅为了“确保有封面”，则当前逻辑没问题。

✅ 良好实践

1. 资源清理完善：在 thumbnail_generator.py 和 ai_service.py 中，对生成的临时文件（NamedTemporaryFile）均进行了显式的 unlink 清理，有效避免了磁盘空间泄漏。
2. 异常处理得当：在 render_adapter.py 中，封面候选帧的生成被包裹在 try-except 中且不阻断主流程，符合“非核心功能降级”的最佳实践。
3. 空值保护：多处使用 plan.config or {} 和 .get("key", default) 进行了防御性编程，避免了潜在的 NoneType 错误。
4. 安全性：使用 subprocess.run 列表形式调用外部命令，有效防止了命令注入风险。

---

✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显问题

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-13 12:36:58 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：否 - 阻塞级问题数量：0 个 ### 📊 审查概览 - 整体评价：通过 - 建议级问题数量：2 个 ### 🔴 阻塞级问题（必须修复） 无 ### 💡 改进建议（不阻塞合并） 1. **[packages/shared/ai_service.py: _extract_frames_with_ffmpeg] 抽帧数量与使用逻辑不匹配** - 具体内容：函数 `_extract_frames_with_ffmpeg` 默认抽取 3 帧（`num_frames=3`），但在调用方 `_call_ai_cover_service` 中仅使用了 `frames[0]`。如果第 1 帧抽取失败或质量不佳，代码并未尝试使用第 2、3 帧，导致额外的抽取开销浪费。 - 建议：如果仅需要一帧，建议将 `num_frames` 参数改为 1 以提升性能；或者实现降级逻辑，在第 1 帧无效时尝试后续帧。 2. **[apps/api/app/api/routes/generation_cover.py: generate_cover] "ai_regenerate" 逻辑可能不符合用户预期** - 具体内容：当 `cover_type` 为 `ai_regenerate` 时，代码逻辑与 `ai_frame` 一致，直接返回预存的 `cover_candidates[0]`。如果用户当前封面已经是该帧，再次点击“重新生成”将得到完全相同的结果，造成用户困惑。 - 建议：确认业务需求。如果“重新生成”意味着“获取一个不同的封面”，建议在 `ai_regenerate` 分支下从候选列表中随机选择或排除当前已选帧；如果仅为了“确保有封面”，则当前逻辑没问题。 ### ✅ 良好实践 1. **资源清理完善**：在 `thumbnail_generator.py` 和 `ai_service.py` 中，对生成的临时文件（`NamedTemporaryFile`）均进行了显式的 `unlink` 清理，有效避免了磁盘空间泄漏。 2. **异常处理得当**：在 `render_adapter.py` 中，封面候选帧的生成被包裹在 `try-except` 中且不阻断主流程，符合“非核心功能降级”的最佳实践。 3. **空值保护**：多处使用 `plan.config or {}` 和 `.get("key", default)` 进行了防御性编程，避免了潜在的 `NoneType` 错误。 4. **安全性**：使用 `subprocess.run` 列表形式调用外部命令，有效防止了命令注入风险。 --- ✅ 格式检查通过 | ✅ 逻辑审查通过 | ✅ 性能无明显问题 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-13 12:36:58 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot added 1 commit 2026-08-13 20:38:30 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 306e648641

auto-approve-bot merged commit 21e84c71c4 into develop 2026-08-13 20:51:02 +08:00

auto-approve-bot deleted branch perf/cover-frame-pre-extract 2026-08-13 20:51:02 +08:00

gitea-actions bot commented 2026-08-13 20:51:56 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

xiaoxia referenced this issue from a commit 2026-08-13 21:25:32 +08:00

fix: add ffmpeg to API runtime image for cover fallback

xiaoxia referenced this pull request 2026-08-13 21:25:52 +08:00

fix: add ffmpeg to API runtime image for cover fallback #1362

Sign in to join this conversation.

Reviewers

No Reviewers

auto-approve-bot

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

3 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#1360