refactor: 预览播放器架构改造 - 前端素材切片播放替代FFmpeg预览渲染 #1414

Merged

xiaoxia merged 18 commits from refactor/frontend-preview-player into develop 2026-08-18 11:05:34 +08:00

Conversation 5 Commits 18 Files Changed 10

+856 -811

xiaoxia commented 2026-08-18 01:08:22 +08:00

Owner

Copy Link

Copy Source

改造概述

将 Step5 预览视频从后端 FFmpeg 渲染改为前端素材切片播放，实现真正的实时预览。

改造内容

新增文件

• FrontendPreviewPlayer.tsx — 前端预览播放器组件，用原生 <video> 标签按时间线播放素材片段
• useSegmentScheduler.ts — 素材片段调度器 Hook，控制片段无缝切换、预加载、播放/暂停/拖拽
• usePreviewAssets.ts — 预览素材加载 Hook，根据选中素材 ID 批量获取视频文件信息

修改文件

• PreviewVideoPanel.tsx — 改为渲染 FrontendPreviewPlayer + TitleOverlay CSS 叠加层
• Step5GeneratePreview.tsx — 精简为标题样式编辑面板，移除后端预览生成按钮和轮询状态
• GeneratePage.tsx — 移除 useStep5Preview 调用，改用 usePreviewAssets 加载素材传给预览面板
• GenerateStepContent.tsx — 移除 Step5 预览相关 props 传递
• useGenerateVideo.ts — 当 previewTaskId 为空时，在确认生成时自动创建后端任务
• useStepNavigation.ts — 更新 Step5 导航校验提示文案

删除文件

• useStep5Preview.ts — 整个文件删除，后端预览轮询逻辑全部移除

架构变化

项目	改造前	改造后
Step5 预览	调用后端 /generation/preview，FFmpeg 渲染 480p 视频	前端直接播放素材片段
标题预览	CSS 叠加在 FFmpeg 渲染视频上	CSS 实时叠加在前端播放器上
预览等待时间	数十秒到数分钟	即时（素材加载后即可播放）
标题样式调整	需要重新渲染	实时生效
最终成片(Step7)	FFmpeg 渲染（不变）	FFmpeg 渲染（不变）

技术实现

• 片段调度：useSegmentScheduler 使用 requestAnimationFrame 检测播放位置，到达出点时自动切换下一段
• 预加载：当前片段播放时，预加载下一段素材减少切换延迟
• 素材映射：将选中的素材按顺序映射到模板片段，按 duration_min 截取播放
• CSS 标题叠加：复用原有 TitleOverlay 组件，坐标参数与后端 ASS 字幕对齐

不变的部分

• Step6/Step7 最终成片仍用 FFmpeg 渲染
• TitleStylePanel、TitlePresetsGrid 等样式面板组件不变
• useGenerateVideo 中确认生成流程保留（自动创建后端任务）

验证方式

1. 进入 Step5，右侧面板直接播放素材片段
2. 调整标题字体/字号/位置/颜色，视频上标题实时变化
3. 播放流畅，片段切换无明显卡顿
4. 代码中无 FFmpeg 预览渲染残留

🤖 Generated with Coze

## 改造概述 将 Step5 预览视频从后端 FFmpeg 渲染改为前端素材切片播放，实现真正的实时预览。 ## 改造内容 ### 新增文件 - `FrontendPreviewPlayer.tsx` — 前端预览播放器组件，用原生 `<video>` 标签按时间线播放素材片段 - `useSegmentScheduler.ts` — 素材片段调度器 Hook，控制片段无缝切换、预加载、播放/暂停/拖拽 - `usePreviewAssets.ts` — 预览素材加载 Hook，根据选中素材 ID 批量获取视频文件信息 ### 修改文件 - `PreviewVideoPanel.tsx` — 改为渲染 FrontendPreviewPlayer + TitleOverlay CSS 叠加层 - `Step5GeneratePreview.tsx` — 精简为标题样式编辑面板，移除后端预览生成按钮和轮询状态 - `GeneratePage.tsx` — 移除 useStep5Preview 调用，改用 usePreviewAssets 加载素材传给预览面板 - `GenerateStepContent.tsx` — 移除 Step5 预览相关 props 传递 - `useGenerateVideo.ts` — 当 previewTaskId 为空时，在确认生成时自动创建后端任务 - `useStepNavigation.ts` — 更新 Step5 导航校验提示文案 ### 删除文件 - `useStep5Preview.ts` — 整个文件删除，后端预览轮询逻辑全部移除 ## 架构变化 | 项目 | 改造前 | 改造后 | |------|--------|--------| | Step5 预览 | 调用后端 `/generation/preview`，FFmpeg 渲染 480p 视频 | 前端直接播放素材片段 | | 标题预览 | CSS 叠加在 FFmpeg 渲染视频上 | CSS 实时叠加在前端播放器上 | | 预览等待时间 | 数十秒到数分钟 | 即时（素材加载后即可播放） | | 标题样式调整 | 需要重新渲染 | 实时生效 | | 最终成片(Step7) | FFmpeg 渲染（不变） | FFmpeg 渲染（不变） | ## 技术实现 - **片段调度**：`useSegmentScheduler` 使用 `requestAnimationFrame` 检测播放位置，到达出点时自动切换下一段 - **预加载**：当前片段播放时，预加载下一段素材减少切换延迟 - **素材映射**：将选中的素材按顺序映射到模板片段，按 `duration_min` 截取播放 - **CSS 标题叠加**：复用原有 `TitleOverlay` 组件，坐标参数与后端 ASS 字幕对齐 ## 不变的部分 - Step6/Step7 最终成片仍用 FFmpeg 渲染 - `TitleStylePanel`、`TitlePresetsGrid` 等样式面板组件不变 - `useGenerateVideo` 中确认生成流程保留（自动创建后端任务） ## 验证方式 1. 进入 Step5，右侧面板直接播放素材片段 2. 调整标题字体/字号/位置/颜色，视频上标题实时变化 3. 播放流畅，片段切换无明显卡顿 4. 代码中无 FFmpeg 预览渲染残留 🤖 Generated with [Coze](https://coze.cn)

xiaoxia added 10 commits 2026-08-18 01:08:22 +08:00

refactor: update useSegmentScheduler.ts ada1c19b49

refactor: update FrontendPreviewPlayer.tsx 5e377d18a4

refactor: update usePreviewAssets.ts 4f308926bd

refactor: 更新现有文件适配前端预览播放器架构 7c71f15dd0

refactor: 更新现有文件适配前端预览播放器架构 9f910e0c7f

refactor: 更新现有文件适配前端预览播放器架构 5a7566d2bc

refactor: 更新现有文件适配前端预览播放器架构 85568b4d56

refactor: 更新现有文件适配前端预览播放器架构 b474cc58d8

refactor: 更新现有文件适配前端预览播放器架构 48be85369a

refactor: 删除 useStep5Preview - 前端预览不再依赖后端FFmpeg渲染 00d2e4714c

xiaoxia added 1 commit 2026-08-18 01:35:18 +08:00

fix: remove unused LoadingOutlined import in FrontendPreviewPlayer 361c4fea38

xiaoxia added 1 commit 2026-08-18 01:35:35 +08:00

fix: remove unused PlayCircleOutlined import in PreviewVideoPanel a5eeb0a441

xiaoxia added 1 commit 2026-08-18 01:41:34 +08:00

fix: add missing React import in useSegmentScheduler for React.RefObject type b6d2a19ad7

xiaoxia added 1 commit 2026-08-18 01:54:14 +08:00

fix: RefObject 类型修正 - 去掉多余的 | null a0ad4274e6

xiaoxia added 1 commit 2026-08-18 01:54:33 +08:00

fix: handleMouseDown 事件类型修正为 HTMLDivElement f8276ed4c8

xiaoxia added 1 commit 2026-08-18 01:55:00 +08:00

fix: usePreviewAssets 回退获取添加泛型类型参数修复 TS2677 b08b7be967

xiaoxia added 1 commit 2026-08-18 01:55:41 +08:00

fix: usePreviewAssets 类型谓词修正为 AxiosResponse 包装类型 7065c93cd3

gitea-actions bot commented 2026-08-18 01:57:53 +08:00

Copy Link

Copy Source

🚀 预览环境已部署

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

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

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

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

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

xiaoxia added 1 commit 2026-08-18 02:04:09 +08:00

style: Prettier 格式化修复 de8f06058c

auto-approve-bot commented 2026-08-18 02:05:57 +08:00

Collaborator

Copy Link

Copy Source

【阻塞级判定】

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

📊 审查概览

• 整体评价：需修改
• 建议级问题数量：1 个

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

1. [PreviewVideoPanel.tsx: 48-50] 标题垂直定位单位错误

   • 问题类型：逻辑bug
   • 问题描述：在 getPositionStyle 函数中，top 和 bottom 定位使用了固定像素值（ASS_TITLE_MARGIN_TOP 即 60px），而 left/right 使用了百分比。由于预览容器是响应式的（高度不固定），使用固定像素会导致标题在预览中的垂直位置与后端 FFmpeg 渲染（基于 720p 高度）的实际位置不一致，出现“所见非所得”的严重偏差。
   • 修改建议：将垂直边距也转换为相对于 ASS_VIDEO_HEIGHT (720) 的百分比，例如：top: ${(ASS_TITLE_MARGIN_TOP / ASS_VIDEO_HEIGHT) * 100}%，以保持与字体大小缩放逻辑一致。

2. [FrontendPreviewPlayer.tsx: 52] 缺少视频 URL 有效性校验

   • 问题类型：逻辑bug
   • 问题描述：在 buildPlaybackSegments 中，videoUrl 直接取 asset.file_url || asset.storage_key。如果素材数据异常导致两者均为空，videoUrl 将为 undefined。这会导致后续的播放器逻辑尝试加载无效资源（src="undefined"），可能导致播放器卡死、控制台报错或预览功能失效。
   • 修改建议：添加校验逻辑，如果 URL 缺失，应跳过该素材或记录错误，避免将无效片段加入播放队列。例如：if (!url) continue;。

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

1. [GeneratePage.tsx: 148] 确认生成参数变更风险
   • 具体内容：代码中将 useGenerateVideo 的 previewTaskId 参数从原来的 step5Preview.selectedTaskId 改为硬编码的空字符串 ""。虽然架构改为前端预览，但需确认后端最终生成接口（Step 7）是否不再依赖 preview_task_id 来关联任务或获取缓存。如果后端仍期望该字段，将导致最终生成失败。建议确认 useGenerateVideo 内部实现或后端接口已同步适配。

✅ 良好实践

• FrontendPreviewPlayer.tsx 中使用 useMemo 缓存片段计算，避免不必要的重复计算。
• PreviewVideoPanel.tsx 中字体大小计算使用了百分比 (size / 720) * 100，实现了良好的响应式缩放。
• 移除了不再使用的 useState 和相关导入，代码清理较彻底。
• 进度条拖拽逻辑中使用了 Math.max(0, Math.min(1, ...)) 有效防止了越界。

---

_{🤖 由 AI 代码审查机器人自动生成 | 2026-08-17 18:05:57 | 模型:}

### 【阻塞级判定】 - 是否存在阻塞级问题：是 - 阻塞级问题数量：2 个 ### 📊 审查概览 - 整体评价：需修改 - 建议级问题数量：1 个 ### 🔴 阻塞级问题（必须修复） 1. **[PreviewVideoPanel.tsx: 48-50] 标题垂直定位单位错误** - 问题类型：逻辑bug - 问题描述：在 `getPositionStyle` 函数中，`top` 和 `bottom` 定位使用了固定像素值（`ASS_TITLE_MARGIN_TOP` 即 60px），而 `left/right` 使用了百分比。由于预览容器是响应式的（高度不固定），使用固定像素会导致标题在预览中的垂直位置与后端 FFmpeg 渲染（基于 720p 高度）的实际位置不一致，出现“所见非所得”的严重偏差。 - 修改建议：将垂直边距也转换为相对于 `ASS_VIDEO_HEIGHT` (720) 的百分比，例如：`top: ${(ASS_TITLE_MARGIN_TOP / ASS_VIDEO_HEIGHT) * 100}%`，以保持与字体大小缩放逻辑一致。 2. **[FrontendPreviewPlayer.tsx: 52] 缺少视频 URL 有效性校验** - 问题类型：逻辑bug - 问题描述：在 `buildPlaybackSegments` 中，`videoUrl` 直接取 `asset.file_url || asset.storage_key`。如果素材数据异常导致两者均为空，`videoUrl` 将为 `undefined`。这会导致后续的播放器逻辑尝试加载无效资源（`src="undefined"`），可能导致播放器卡死、控制台报错或预览功能失效。 - 修改建议：添加校验逻辑，如果 URL 缺失，应跳过该素材或记录错误，避免将无效片段加入播放队列。例如：`if (!url) continue;`。 ### 💡 改进建议（不阻塞合并） 1. **[GeneratePage.tsx: 148] 确认生成参数变更风险** - 具体内容：代码中将 `useGenerateVideo` 的 `previewTaskId` 参数从原来的 `step5Preview.selectedTaskId` 改为硬编码的空字符串 `""`。虽然架构改为前端预览，但需确认后端最终生成接口（Step 7）是否不再依赖 `preview_task_id` 来关联任务或获取缓存。如果后端仍期望该字段，将导致最终生成失败。建议确认 `useGenerateVideo` 内部实现或后端接口已同步适配。 ### ✅ 良好实践 - `FrontendPreviewPlayer.tsx` 中使用 `useMemo` 缓存片段计算，避免不必要的重复计算。 - `PreviewVideoPanel.tsx` 中字体大小计算使用了百分比 `(size / 720) * 100`，实现了良好的响应式缩放。 - 移除了不再使用的 `useState` 和相关导入，代码清理较彻底。 - 进度条拖拽逻辑中使用了 `Math.max(0, Math.min(1, ...))` 有效防止了越界。 --- _{🤖 由 AI 代码审查机器人自动生成 | 2026-08-17 18:05:57 | 模型:} <!-- AI_CODE_REVIEW_AUTO_COMMENT -->

auto-approve-bot approved these changes 2026-08-18 02:07:11 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

auto-approve-bot approved these changes 2026-08-18 02:07:11 +08:00

auto-approve-bot left a comment

Collaborator

Copy Link

Copy Source

CI全绿，自动审批通过。

CI全绿，自动审批通过。

xiaoxia referenced this issue from a commit 2026-08-18 02:34:11 +08:00

refactor: 预览播放器架构改造 - 前端素材切片播放替代FFmpeg预览渲染 (#1414)

xiaoxia referenced this issue from a commit 2026-08-18 02:44:35 +08:00

fix: 更新 smoke test 引用 - useStep5Preview 替换为 usePreviewAssets/useSegmentScheduler (#1414)

xiaoxia merged commit 6b16f0c738 into develop 2026-08-18 11:05:34 +08:00

gitea-actions bot commented 2026-08-18 11:05:54 +08:00

Copy Link

Copy Source

🗑️ 预览环境已清理

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

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

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

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