fix(P0): 视频封面缩略图抽帧时间调整到15%处 #586

Merged

auto-approve-bot merged 1 commits from fix/p0-thumbnail-seek-time into develop 2026-07-19 13:15:01 +08:00

Conversation 6 Commits 1 Files Changed 1

+29 -6

xiaoxia commented 2026-07-19 13:09:26 +08:00

Owner

Copy Link

Copy Source

问题

成片库和视频库中的视频封面缩略图都是纯色（全绿/全蓝），完全看不出视频内容。原因：缩略图抽取的是第1秒帧，视频开头通常是转场/纯色画面。

修复

• 抽帧策略：从固定第1秒改为按视频时长 15% 处抽帧，避开片头转场和纯色画面
• 参数化：新增 seek_ratio（默认0.15）和 min_seek_seconds（默认1秒）可调参数
• 性能优化：-ss 移到 -i 前面（input seeking），速度更快，缩略图精度足够
• 多级兜底：probe失败 → 第1秒；ffmpeg失败 → 第0帧

影响范围

• 成片生成时的缩略图（dedup_helpers 调用 generate_and_upload_thumbnail）
• 渲染结果缩略图（render_adapter 调用 generate_and_upload_thumbnail）
• 所有走 extract_first_frame 的路径

素材库注意

素材库缩略图当前是复用视频文件URL（浏览器自动显示首帧），不走此函数。如需同步优化素材库缩略图，需单独改造ingest流程。

## 问题 成片库和视频库中的视频封面缩略图都是纯色（全绿/全蓝），完全看不出视频内容。原因：缩略图抽取的是第1秒帧，视频开头通常是转场/纯色画面。 ## 修复 - **抽帧策略**：从固定第1秒改为按视频时长 15% 处抽帧，避开片头转场和纯色画面 - **参数化**：新增 seek_ratio（默认0.15）和 min_seek_seconds（默认1秒）可调参数 - **性能优化**：-ss 移到 -i 前面（input seeking），速度更快，缩略图精度足够 - **多级兜底**：probe失败 → 第1秒；ffmpeg失败 → 第0帧 ## 影响范围 - 成片生成时的缩略图（dedup_helpers 调用 generate_and_upload_thumbnail） - 渲染结果缩略图（render_adapter 调用 generate_and_upload_thumbnail） - 所有走 extract_first_frame 的路径 ## 素材库注意 素材库缩略图当前是复用视频文件URL（浏览器自动显示首帧），不走此函数。如需同步优化素材库缩略图，需单独改造ingest流程。

xiaoxia added 1 commit 2026-07-19 13:09:26 +08:00

fix(P0): 视频封面缩略图抽帧时间调整到15%处 ... 0cc797ab22

- 从固定第1秒改为按视频时长15%处抽帧，避开片头转场/纯色画面
- 新增 seek_ratio（默认0.15）和 min_seek_seconds（默认1秒）参数
- 新增 _format_seek_time 工具函数格式化时间
- -ss 移到 -i 前面（input seeking），速度更快，缩略图精度足够
- probe失败或ffmpeg失败都有兜底（第1秒 → 第0帧）

gitea-actions bot commented 2026-07-19 13:10:40 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

auto-approve-bot approved these changes 2026-07-19 13:13:14 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-07-19 13:13:14 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot commented 2026-07-19 13:14:37 +08:00

Collaborator

Copy Link

Copy Source

代码审查结果 - PR #586

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

1. apps/worker/video_processing/thumbnail_generator.py 第53行：Input Seeking（-ss置于-i前）可能导致功能失效。

   • 说明：代码注释提到目的是“避开片头纯色画面”。Input Seeking 是基于关键帧的快速跳转，如果视频的关键帧间隔（GOP）大于计算出的 seek_time（例如 seek 到 1.5秒，但关键帧在 0秒和 10秒），FFmpeg 会强制从 0秒关键帧开始解码，导致生成的封面图仍然是片头画面，违背了修改初衷。
   • 后果：在长 GOP 的视频中无法避开片头黑屏或纯色画面。

2. apps/worker/video_processing/thumbnail_generator.py 第19行：参数 seek_ratio 和 min_seek_seconds 缺乏校验。

   • 说明：如果调用者传入负数（例如 seek_ratio=-1.0, min_seek_seconds=-1.0），计算出的 seek_time 可能为负数，导致 _format_seek_time 生成非法的时间戳字符串（如 -00:00:05.00），进而导致 FFmpeg 执行失败。
   • 后果：极端参数输入会导致程序异常或非预期行为。

💡 建议（2个可选）

1. apps/worker/video_processing/thumbnail_generator.py 第40行：关注 probe_duration 带来的性能开销。

   • 说明：新增的 probe_duration 调用会额外启动一个 ffprobe 进程。在高并发的视频处理场景下，这会增加 CPU 和 I/O 压力。如果业务允许，可考虑在视频上传时预存时长信息，或评估是否接受此开销。

2. apps/worker/video_processing/thumbnail_generator.py 第41行：异常捕获范围过宽。

   • 说明：except Exception 会捕获所有异常（包括键盘中断等）。建议捕获具体的异常（如 RuntimeError, ValueError 或 subprocess.CalledProcessError），并增加日志记录（logging），以便排查 probe_duration 失败的具体原因。

---

✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能

---

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

## 代码审查结果 - PR #586 ### ⚠️ 问题（2个需要修改） 1. **apps/worker/video_processing/thumbnail_generator.py 第53行**：Input Seeking（`-ss`置于`-i`前）可能导致功能失效。 - **说明**：代码注释提到目的是“避开片头纯色画面”。Input Seeking 是基于关键帧的快速跳转，如果视频的关键帧间隔（GOP）大于计算出的 `seek_time`（例如 seek 到 1.5秒，但关键帧在 0秒和 10秒），FFmpeg 会强制从 0秒关键帧开始解码，导致生成的封面图仍然是片头画面，违背了修改初衷。 - **后果**：在长 GOP 的视频中无法避开片头黑屏或纯色画面。 2. **apps/worker/video_processing/thumbnail_generator.py 第19行**：参数 `seek_ratio` 和 `min_seek_seconds` 缺乏校验。 - **说明**：如果调用者传入负数（例如 `seek_ratio=-1.0`, `min_seek_seconds=-1.0`），计算出的 `seek_time` 可能为负数，导致 `_format_seek_time` 生成非法的时间戳字符串（如 `-00:00:05.00`），进而导致 FFmpeg 执行失败。 - **后果**：极端参数输入会导致程序异常或非预期行为。 ### 💡 建议（2个可选） 1. **apps/worker/video_processing/thumbnail_generator.py 第40行**：关注 `probe_duration` 带来的性能开销。 - **说明**：新增的 `probe_duration` 调用会额外启动一个 `ffprobe` 进程。在高并发的视频处理场景下，这会增加 CPU 和 I/O 压力。如果业务允许，可考虑在视频上传时预存时长信息，或评估是否接受此开销。 2. **apps/worker/video_processing/thumbnail_generator.py 第41行**：异常捕获范围过宽。 - **说明**：`except Exception` 会捕获所有异常（包括键盘中断等）。建议捕获具体的异常（如 `RuntimeError`, `ValueError` 或 `subprocess.CalledProcessError`），并增加日志记录（logging），以便排查 `probe_duration` 失败的具体原因。 --- ✅ 格式检查通过 | ❌ 逻辑审查需修改 | ⚠️ 建议关注性能 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-07-19 13:14:37 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot merged commit 12e88dc05c into develop 2026-07-19 13:15:01 +08:00

auto-approve-bot deleted branch fix/p0-thumbnail-seek-time 2026-07-19 13:15:01 +08:00

gitea-actions bot commented 2026-07-19 13:15:13 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

xiaoxia reviewed 2026-07-19 14:20:48 +08:00

xiaoxia left a comment

Author

Owner

Copy Link

Copy Source

LGTM

LGTM

xiaoxia referenced this issue from a commit 2026-07-20 01:39:16 +08:00

feat(phase9): AI能力增强合集 - 智能标题/智能配音/生成体验优化

xiaoxia referenced this issue from a commit 2026-07-20 09:57:07 +08:00

feat(phase9): AI能力增强合集 - 智能标题/智能配音/生成体验优化

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