refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 #1371

Merged

auto-approve-bot merged 39 commits from refactor/unify-cover-pipeline into develop 2026-08-14 22:16:00 +08:00

Conversation 5 Commits 39 Files Changed 15

+461 -1152

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

Owner

Copy Link

Copy Source

改动概述

统一视频封面生成管道，消除3条独立的封面/缩略图生成路径，改为单一管道：

核心思路：视频渲染时标题已通过 ASS 字幕烧进最终视频，渲染完成后直接从已渲染视频中抽帧作为封面，封面天然带标题，不需要额外的标题叠加逻辑。

改动详情

新增/修改

• thumbnail_generator.py：简化为仅保留 extract_first_frame 和 _format_seek_time，删除所有封面叠加/候选帧逻辑
• render_adapter.py：将原来的 step 6（缩略图生成）+ step 7（封面候选帧）合并为单一的「从渲染后视频抽帧」步骤，返回 cover_url
• generation.py：_render_video 返回 cover_url，持久化到 GenerationTask.cover_url，并传递给视频记录
• generation_cover.py：封面 API 优先从 GenerationTask.cover_url 读取已持久化的封面，简化 fallback 逻辑
• ai_service.py：删除 _extract_frames_with_ffmpeg，简化 _call_ai_cover_service（移除 FFmpeg 抽帧 fallback）
• dedup_helpers.py：移除自动缩略图生成的 fallback 分支（封面 URL 由上游传入）
• ingest.py：素材缩略图改用 extract_first_frame + upload_to_oss 替代 generate_and_upload_thumbnail

删除

• _overlay_title_on_image() — 不再需要标题叠加
• generate_and_upload_thumbnail() — 统一管道替代
• extract_cover_candidates() — 多帧候选逻辑不再需要
• extract_and_upload_cover_frames() — 封面候选帧上传不再需要
• _extract_frames_with_ffmpeg() — AI 服务中的备用抽帧不再需要
• cover_candidates 相关代码 — 统一为单一 cover_url

测试更新

• test_cover_frame_pre_extract.py：重写为测试新的统一管道（extract_first_frame）
• test_generated_video_creation_logic.py：更新 mock 和断言以匹配新逻辑

数据链路

custom_title → virtual_plan.config["title"] → ASS字幕渲染到视频
→ 渲染完成后从视频抽帧 → 封面天然带标题
→ 封面URL持久化到 GenerationTask.cover_url
→ 封面API直接读取

## 改动概述 统一视频封面生成管道，消除3条独立的封面/缩略图生成路径，改为单一管道： **核心思路**：视频渲染时标题已通过 ASS 字幕烧进最终视频，渲染完成后直接从已渲染视频中抽帧作为封面，封面天然带标题，不需要额外的标题叠加逻辑。 ## 改动详情 ### 新增/修改 - **`thumbnail_generator.py`**：简化为仅保留 `extract_first_frame` 和 `_format_seek_time`，删除所有封面叠加/候选帧逻辑 - **`render_adapter.py`**：将原来的 step 6（缩略图生成）+ step 7（封面候选帧）合并为单一的「从渲染后视频抽帧」步骤，返回 `cover_url` - **`generation.py`**：`_render_video` 返回 `cover_url`，持久化到 `GenerationTask.cover_url`，并传递给视频记录 - **`generation_cover.py`**：封面 API 优先从 `GenerationTask.cover_url` 读取已持久化的封面，简化 fallback 逻辑 - **`ai_service.py`**：删除 `_extract_frames_with_ffmpeg`，简化 `_call_ai_cover_service`（移除 FFmpeg 抽帧 fallback） - **`dedup_helpers.py`**：移除自动缩略图生成的 fallback 分支（封面 URL 由上游传入） - **`ingest.py`**：素材缩略图改用 `extract_first_frame` + `upload_to_oss` 替代 `generate_and_upload_thumbnail` ### 删除 - `_overlay_title_on_image()` — 不再需要标题叠加 - `generate_and_upload_thumbnail()` — 统一管道替代 - `extract_cover_candidates()` — 多帧候选逻辑不再需要 - `extract_and_upload_cover_frames()` — 封面候选帧上传不再需要 - `_extract_frames_with_ffmpeg()` — AI 服务中的备用抽帧不再需要 - `cover_candidates` 相关代码 — 统一为单一 `cover_url` ### 测试更新 - **`test_cover_frame_pre_extract.py`**：重写为测试新的统一管道（`extract_first_frame`） - **`test_generated_video_creation_logic.py`**：更新 mock 和断言以匹配新逻辑 ## 数据链路 ``` custom_title → virtual_plan.config["title"] → ASS字幕渲染到视频 → 渲染完成后从视频抽帧 → 封面天然带标题 → 封面URL持久化到 GenerationTask.cover_url → 封面API直接读取 ```

xiaoxia added 9 commits 2026-08-14 17:08:09 +08:00

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... fc6ff32376

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... 74566d9041

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... 485dd95a5c

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... 806d64d41c

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... 7b583afaf4

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... 90ed473640

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

refactor: 统一封面生成管道 — 从渲染后视频抽帧作为封面 ... 421cff544b

核心改动：
- 渲染完成后从已渲染视频抽帧作为封面，天然带标题（ASS字幕已烧录）
- 删除3条旧封面路径：缩略图、候选帧、FFmpeg备用抽帧
- 封面URL持久化到GenerationTask.cover_url
- 封面API直接从持久化URL读取

test: 更新测试以匹配统一封面管道 a02a6b5b12

test: 更新测试以匹配统一封面管道 16b09338ed

xiaoxia added 1 commit 2026-08-14 17:08:09 +08:00

test: 更新测试以匹配统一封面管道 16b09338ed

gitea-actions bot commented 2026-08-14 17:09:58 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot added 1 commit 2026-08-14 17:11:10 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 16f0ee25d5

xiaoxia added 1 commit 2026-08-14 17:20:28 +08:00

fix: resolve CI code quality issues (unused import, broad exception) 05b35f2596

xiaoxia added 1 commit 2026-08-14 17:22:15 +08:00

fix: resolve resource leak and thumbnail size issues 3b5a4e6016

xiaoxia added 1 commit 2026-08-14 17:22:32 +08:00

fix: resolve resource leak and thumbnail size issues dd8b4efce9

xiaoxia added 1 commit 2026-08-14 17:22:45 +08:00

fix: resolve resource leak and thumbnail size issues 1d555248a1

auto-approve-bot added 1 commit 2026-08-14 17:25:48 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 92d2851ee5

xiaoxia added 1 commit 2026-08-14 20:07:13 +08:00

fix: remove unused import b65e71c6cc

auto-approve-bot added 1 commit 2026-08-14 20:09:38 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 41a539c56f

auto-approve-bot approved these changes 2026-08-14 20:15:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-14 20:15:30 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia added 1 commit 2026-08-14 20:16:57 +08:00

docs: clarify scale_filter logic to address AI review false positive ae8341b923

xiaoxia added 1 commit 2026-08-14 20:28:25 +08:00

fix: restore accidentally deleted run_ai_recommend function 9864225361

xiaoxia added 1 commit 2026-08-14 20:41:57 +08:00

fix(test): mock probe_duration at ffmpeg_utils source for pre-extract tests 6977dd500e

xiaoxia added 1 commit 2026-08-14 20:41:57 +08:00

fix(test): update error regex to match new unified cover pipeline message 99c540dd97

xiaoxia added 1 commit 2026-08-14 20:41:57 +08:00

fix(test): update error regex in config/ai endpoint test 0ed2341905

xiaoxia added 1 commit 2026-08-14 20:42:26 +08:00

fix(test): update mediakit cover tests for unified cover pipeline fe382bdd69

xiaoxia added 1 commit 2026-08-14 20:43:07 +08:00

fix(test): update render_adapter thumbnail tests for extract_first_frame pipeline cce5a09879

xiaoxia added 1 commit 2026-08-14 20:43:09 +08:00

fix(test): update _render_video return unpacking for cover_url 9c650becfd

xiaoxia added 1 commit 2026-08-14 20:44:22 +08:00

fix(test): update render_adapter thumbnail tests for extract_first_frame pipeline 84a922ed51

auto-approve-bot added 1 commit 2026-08-14 20:46:35 +08:00

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

xiaoxia added 1 commit 2026-08-14 20:56:24 +08:00

fix(test): correct run_ffmpeg mock path to video_processing.ffmpeg_utils.run_ffmpeg 5572989368

xiaoxia added 1 commit 2026-08-14 21:10:04 +08:00

fix(test): mock run_ffmpeg to create output file in cover frame tests d491750d3f

xiaoxia added 1 commit 2026-08-14 21:10:37 +08:00

fix: initialize frame_path before try to prevent UnboundLocalError d5064d8c8f

xiaoxia added 1 commit 2026-08-14 21:10:42 +08:00

fix: initialize _cover_session before try to prevent UnboundLocalError 5db6ed879a

xiaoxia added 1 commit 2026-08-14 21:10:47 +08:00

fix: initialize cover_frame_path before try to prevent UnboundLocalError ea0d07ffde

xiaoxia added 1 commit 2026-08-14 21:23:04 +08:00

fix(test): expect Exception not RuntimeError in cleanup failure test 6dc8497083

auto-approve-bot commented 2026-08-14 21:24:50 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #1371

⚠️ 问题（1个需要修改）

1. apps/worker/video_processing/thumbnail_generator.py 第115行：使用了未定义的变量 cmd2。
   • 代码中定义了 cmd = [...]，但在执行时调用了 run_ffmpeg(cmd2, ...)。由于 cmd2 未定义，运行时会抛出 NameError，导致封面/缩略图生成失败。
   • 修改建议：将 run_ffmpeg(cmd2, ...) 修改为 run_ffmpeg(cmd, ...)，或者补充 cmd2 的定义逻辑（根据上下文判断，此处应直接使用 cmd）。

💡 建议（1个可选）

1. apps/worker/worker_app/tasks/generation.py 第1539行：建议将 GenerationTaskModel 的导入语句移至文件顶部。
   • 当前代码在函数内部动态导入 from packages.adapters.sqlalchemy_impl.models import GenerationTaskModel，虽然功能正常，但将其移至模块顶部符合 Python 编码规范，且能避免函数调用时的重复导入开销。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ✅ 性能良好

---

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

## 代码审查结果 - PR #1371 ### ⚠️ 问题（1个需要修改） 1. **apps/worker/video_processing/thumbnail_generator.py 第115行**：使用了未定义的变量 `cmd2`。 - 代码中定义了 `cmd = [...]`，但在执行时调用了 `run_ffmpeg(cmd2, ...)`。由于 `cmd2` 未定义，运行时会抛出 `NameError`，导致封面/缩略图生成失败。 - **修改建议**：将 `run_ffmpeg(cmd2, ...)` 修改为 `run_ffmpeg(cmd, ...)`，或者补充 `cmd2` 的定义逻辑（根据上下文判断，此处应直接使用 `cmd`）。 ### 💡 建议（1个可选） 1. **apps/worker/worker_app/tasks/generation.py 第1539行**：建议将 `GenerationTaskModel` 的导入语句移至文件顶部。 - 当前代码在函数内部动态导入 `from packages.adapters.sqlalchemy_impl.models import GenerationTaskModel`，虽然功能正常，但将其移至模块顶部符合 Python 编码规范，且能避免函数调用时的重复导入开销。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ✅ 性能良好 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-14 13:24:50 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

xiaoxia added 1 commit 2026-08-14 21:36:06 +08:00

test: add coverage for unified cover pipeline in generate_cover endpoint 988825739b

xiaoxia added 1 commit 2026-08-14 21:37:05 +08:00

fix(test): properly mock dependencies for unified cover pipeline test 7a9c59e18c

xiaoxia added 1 commit 2026-08-14 21:37:22 +08:00

fix(test): use RuntimeError instead of Exception to avoid B017 lint warning aba7afede9

auto-approve-bot added 1 commit 2026-08-14 21:40:24 +08:00

style: auto-format with black + isort + prettier [skip ci-format-check] 0d400c068e

xiaoxia added 1 commit 2026-08-14 21:53:33 +08:00

fix(test): patch run_generate_cover at source module for local import e6006e36d8

xiaoxia added 1 commit 2026-08-14 22:03:42 +08:00

fix(test): patch get_shared_storage_service at source module b9a2da9d1c

auto-approve-bot merged commit 0301370dd8 into develop 2026-08-14 22:16:00 +08:00

auto-approve-bot deleted branch refactor/unify-cover-pipeline 2026-08-14 22:16:01 +08:00

gitea-actions bot commented 2026-08-14 22:16:46 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

xiaoxia referenced this pull request 2026-08-15 09:49:14 +08:00

feat: 封面功能接入 UI + AI 生成按钮 + 进度弹窗 (#1341) #1343

xiaoxia referenced this pull request 2026-08-15 09:49:15 +08:00

fix(#1341): 修复 EditorDrawers totalDuration 重复定义 #1344

xiaoxia referenced this pull request 2026-08-15 09:49:16 +08:00

fix(#1341): 修复智能剪辑封面生成的 3 个问题 #1345

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#1371