apps/web/src/pages/generate/GeneratePage.tsx

@@ -1,15 +1,15 @@
 /**
- * 智能剪辑页面 — V23 标题样式面板迁移到 Step5 + CSS 实时预览
+ * 智能剪辑页面 — V24 前端预览播放器架构改造
  * 7 步向导：选择模板 → 素材 → 配音 → 标题 → 预览 → 封面 → 确认生成
  * 左右布局：左侧 generate-form + 右侧 generate-preview
- * 主组件仅保留整体布局与事件编排
- * 状态管理 → hooks/useGenerateFormState
- * 步骤导航 → hooks/useStepNavigation
- * 步骤内容 → components/GenerateStepContent
- * 底部按钮 → components/GenerateStepActions
- * 生成核心逻辑 → hooks/useGenerateVideo
+ *
+ * 架构改造：
+ * - Step5 预览改为前端素材切片播放（FrontendPreviewPlayer）
+ * - 完全去除后端 FFmpeg 预览依赖
+ * - 标题样式通过 CSS 层实时叠加，所见即所得
+ * - 最终成片仍走后端 FFmpeg 渲染（Step7 确认生成）
  */
-import React, { useState, useMemo } from "react"
+import React, { useMemo } from "react"
 import { Modal, message } from "antd"
 import { useNavigate } from "react-router-dom"
 import type { VoiceClone } from "@/api/voice-clone"
@@ -24,7 +24,7 @@ import GenerateStepActions from "./components/GenerateStepActions"
 import { useGenerateFormState } from "./hooks/useGenerateFormState"
 import { useStepNavigation } from "./hooks/useStepNavigation"
 import { useGenerateVideo } from "./hooks/useGenerateVideo"
-import { useStep5Preview } from "./hooks/useStep5Preview"
+import { usePreviewAssets } from "./hooks/usePreviewAssets"
 import { useTitleStyleUpdaters } from "./hooks/useStep4Title/useTitleStyleUpdaters"
 import "./generate.css"
 
@@ -87,36 +87,23 @@ const GeneratePage: React.FC = () => {
     message.success("音色克隆成功！")
   }
 
-  /* ── 预览数量（多预览） ── */
-  const [previewCount, setPreviewCount] = useState(1)
+  /* ── 前端预览：加载选中素材的视频文件信息 ── */
+  const previewAssetIds = useMemo(
+    () => (materialMode === "auto" ? smartSelectedIds : selectedMaterials),
+    [materialMode, smartSelectedIds, selectedMaterials],
+  )
+  const previewAssetsEnabled = currentStep >= 4 && previewAssetIds.length > 0
+  const {
+    assets: previewAssets,
+    loading: previewAssetsLoading,
+    ready: previewAssetsReady,
+  } = usePreviewAssets(previewAssetIds, previewAssetsEnabled)
 
-  /* ── 根据 voiceMode 构建 voiceIds 传给预览接口 ── */
-  /* selectedVoice / selectedClonedVoice 均为 string 类型（voice ID），
-     见 useGenerateFormState 返回值类型定义 */
-  const previewVoiceIds = useMemo((): string[] => {
-    if (voiceMode === "clone") {
-      const id: string = selectedClonedVoice
-      return id ? [id] : []
-    }
-    // preset / custom 模式
-    const id: string = selectedVoice
-    return id ? [id] : []
-  }, [voiceMode, selectedVoice, selectedClonedVoice])
-
-  /* ── Step5 预览生成（多预览 + voice_ids） ── */
-  const step5Preview = useStep5Preview({
-    templates: userTemplates,
-    selectedTemplate,
-    materialMode,
-    selectedMaterials,
-    smartSelectedIds,
-    duration,
-    videoRatio,
-    voiceIds: previewVoiceIds,
-    voiceLibraryId: selectedVoice || undefined,
-    previewCount,
-    titleSettings,
-  })
+  /* ── 当前模板对象（传给前端预览播放器） ── */
+  const currentTemplate = useMemo(
+    () => userTemplates.find((t) => t.id === selectedTemplate) || null,
+    [userTemplates, selectedTemplate],
+  )
 
   /* ── 步骤导航 ── */
   const { goNext, goPrev } = useStepNavigation({
@@ -127,7 +114,7 @@ const GeneratePage: React.FC = () => {
     selectedMaterials,
     smartSelectedIds,
     titleSettings,
-    previewReady: step5Preview.canProceed,
+    previewReady: previewAssetsReady,
   })
 
   /* ── 视频生成核心逻辑 ── */
@@ -158,7 +145,7 @@ const GeneratePage: React.FC = () => {
     autoSubtitles,
     bgm,
     generateCount,
-    previewTaskId: step5Preview.selectedTaskId,
+    previewTaskId: "",
   })
 
   /* ================================================================
@@ -225,16 +212,6 @@ const GeneratePage: React.FC = () => {
             onRetry={handleRetryGenerate}
             onDismissError={handleDismissError}
             presetVoices={presetVoices}
-            /* Step5 多预览 */
-            previewCount={previewCount}
-            onPreviewCountChange={setPreviewCount}
-            previewItems={step5Preview.items}
-            previewOverallStatus={step5Preview.previewStatus}
-            previewOverallError={step5Preview.previewError}
-            previewOverallProgress={step5Preview.progress}
-            previewAnyGenerating={step5Preview.anyGenerating}
-            onGeneratePreview={step5Preview.generatePreview}
-            onRegeneratePreview={step5Preview.regeneratePreview}
           />
 
           <GenerateStepActions
@@ -253,12 +230,11 @@ const GeneratePage: React.FC = () => {
           {/* 预览视频面板（Step4+ 显示，含 CSS 标题实时预览层） */}
           {currentStep >= 4 && (
             <PreviewVideoPanel
-              previewStatus={step5Preview.previewStatus}
-              previewResult={step5Preview.previewResult}
-              previewError={step5Preview.previewError}
-              progress={step5Preview.progress}
+              assets={previewAssets}
+              template={currentTemplate}
               videoRatio={videoRatio}
-              onRegenerate={step5Preview.regeneratePreview}
+              assetsReady={previewAssetsReady}
+              assetsLoading={previewAssetsLoading}
               titleSettings={titleSettings}
             />
           )}

apps/web/src/pages/generate/components/FrontendPreviewPlayer.tsx

@@ -0,0 +1,300 @@
+/**
+ * 前端预览播放器
+ * 用原生 <video> 标签按时间线播放素材片段
+ * 替代后端 FFmpeg 渲染预览，实现真正的实时预览
+ */
+import React, { useMemo, useCallback, useState, useRef, useEffect } from "react"
+import { PlayCircleOutlined, PauseCircleOutlined, SoundOutlined } from "@ant-design/icons"
+import type { AssetItem } from "@/api/assets"
+import type { EditingTemplate } from "@/api/editing-planner"
+import { useSegmentScheduler, type PlaybackSegment } from "../hooks/useSegmentScheduler"
+
+interface FrontendPreviewPlayerProps {
+  /** 选中的素材列表 */
+  assets: AssetItem[]
+  /** 当前模板（用于获取片段时长配置） */
+  template: EditingTemplate | null
+  /** 视频比例 */
+  videoRatio: string
+  /** 是否准备好播放（素材已加载） */
+  ready: boolean
+}
+
+/** 格式化时间 mm:ss */
+function formatTime(seconds: number): string {
+  const m = Math.floor(seconds / 60)
+  const s = Math.floor(seconds % 60)
+  return `${m}:${s.toString().padStart(2, "0")}`
+}
+
+/**
+ * 将素材映射为播放片段
+ * 每个素材对应一个模板片段，按顺序分配
+ */
+function buildPlaybackSegments(
+  assets: AssetItem[],
+  template: EditingTemplate | null,
+): PlaybackSegment[] {
+  if (!assets.length) return []
+
+  const templateSegments = template?.segments || []
+  const segments: PlaybackSegment[] = []
+
+  assets.forEach((asset, i) => {
+    // 获取素材时长（从 metadata 或顶层字段）
+    const assetDuration = asset.duration || asset.metadata?.duration || 30
+    // 模板片段的时长约束
+    const tplSeg = templateSegments[i] || templateSegments[templateSegments.length - 1]
+    const segDuration = tplSeg
+      ? Math.min(tplSeg.duration_max, Math.max(tplSeg.duration_min, assetDuration))
+      : Math.min(assetDuration, 10)
+
+    const startTime = 0
+    const endTime = Math.min(startTime + segDuration, assetDuration)
+
+    segments.push({
+      assetId: asset.id,
+      videoUrl: asset.file_url || asset.storage_key,
+      startTime,
+      endTime,
+      order: i,
+    })
+  })
+
+  return segments
+}
+
+const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
+  assets,
+  template,
+  videoRatio,
+  ready,
+}) => {
+  // 构建播放片段
+  const segments = useMemo(() => buildPlaybackSegments(assets, template), [assets, template])
+
+  const {
+    isPlaying,
+    currentTime,
+    totalDuration,
+    currentSegmentIndex,
+    isEnded,
+    canPlay,
+    togglePlayPause,
+    seekTo,
+    videoRef,
+  } = useSegmentScheduler(segments)
+
+  // 进度条拖拽
+  const [isDragging, setIsDragging] = useState(false)
+  const progressRef = useRef<HTMLDivElement>(null)
+
+  const handleProgressClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (!progressRef.current || totalDuration <= 0) return
+      const rect = progressRef.current.getBoundingClientRect()
+      const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
+      seekTo(ratio * totalDuration)
+    },
+    [totalDuration, seekTo],
+  )
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      setIsDragging(true)
+      handleProgressClick(e)
+    },
+    [handleProgressClick],
+  )
+
+  useEffect(() => {
+    if (!isDragging) return
+    const handleMouseMove = (e: MouseEvent) => {
+      if (!progressRef.current || totalDuration <= 0) return
+      const rect = progressRef.current.getBoundingClientRect()
+      const ratio = Math.max(0, Math.min(1, (e.clientX - rect.left) / rect.width))
+      seekTo(ratio * totalDuration)
+    }
+    const handleMouseUp = () => setIsDragging(false)
+    window.addEventListener("mousemove", handleMouseMove)
+    window.addEventListener("mouseup", handleMouseUp)
+    return () => {
+      window.removeEventListener("mousemove", handleMouseMove)
+      window.removeEventListener("mouseup", handleMouseUp)
+    }
+  }, [isDragging, totalDuration, seekTo])
+
+  const videoAspectStyle = { aspectRatio: (videoRatio || "16:9").replace(":", "/") }
+  const progressPercent = totalDuration > 0 ? (currentTime / totalDuration) * 100 : 0
+
+  // 未就绪状态
+  if (!ready || !assets.length) {
+    return (
+      <div className="xx-preview-empty">
+        <SoundOutlined style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }} />
+        <p className="xx-preview-empty-title">准备预览素材...</p>
+        <p className="xx-preview-empty-desc">加载素材后即可预览播放</p>
+      </div>
+    )
+  }
+
+  // 无播放片段
+  if (!canPlay) {
+    return (
+      <div className="xx-preview-empty">
+        <PlayCircleOutlined
+          style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }}
+        />
+        <p className="xx-preview-empty-title">暂无可播放素材</p>
+        <p className="xx-preview-empty-desc">请先在左侧选择素材</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="xx-frontend-preview-player">
+      {/* 视频区域 */}
+      <div className="xx-preview-video" style={{ ...videoAspectStyle, position: "relative" }}>
+        <video
+          ref={videoRef}
+          preload="auto"
+          style={{
+            width: "100%",
+            height: "100%",
+            objectFit: "contain",
+            background: "#000",
+          }}
+          playsInline
+        />
+
+        {/* 播放/暂停按钮覆盖 */}
+        {!isPlaying && (
+          <button
+            className="xx-preview-play-btn"
+            onClick={togglePlayPause}
+            style={{
+              position: "absolute",
+              top: "50%",
+              left: "50%",
+              transform: "translate(-50%, -50%)",
+              background: "rgba(0,0,0,0.5)",
+              border: "none",
+              borderRadius: "50%",
+              width: 56,
+              height: 56,
+              cursor: "pointer",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              color: "#fff",
+              fontSize: 28,
+              zIndex: 10,
+              transition: "opacity 0.2s",
+            }}
+          >
+            {isEnded ? <PlayCircleOutlined /> : <PlayCircleOutlined />}
+          </button>
+        )}
+
+        {/* 当前片段指示器 */}
+        <div
+          style={{
+            position: "absolute",
+            top: 8,
+            left: 8,
+            background: "rgba(0,0,0,0.6)",
+            color: "#fff",
+            fontSize: 11,
+            padding: "2px 8px",
+            borderRadius: 4,
+            zIndex: 10,
+          }}
+        >
+          片段 {currentSegmentIndex + 1}/{segments.length}
+        </div>
+      </div>
+
+      {/* 控制条 */}
+      <div
+        className="xx-preview-controls"
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          padding: "8px 0",
+        }}
+      >
+        {/* 播放/暂停 */}
+        <button
+          onClick={togglePlayPause}
+          style={{
+            background: "none",
+            border: "none",
+            color: "var(--text-primary, #fff)",
+            fontSize: 18,
+            cursor: "pointer",
+            padding: 4,
+            display: "flex",
+            alignItems: "center",
+          }}
+        >
+          {isPlaying ? <PauseCircleOutlined /> : <PlayCircleOutlined />}
+        </button>
+
+        {/* 时间 */}
+        <span
+          style={{
+            fontSize: 12,
+            color: "var(--text-secondary, #999)",
+            minWidth: 80,
+            fontVariantNumeric: "tabular-nums",
+          }}
+        >
+          {formatTime(currentTime)} / {formatTime(totalDuration)}
+        </span>
+
+        {/* 进度条 */}
+        <div
+          ref={progressRef}
+          onMouseDown={handleMouseDown}
+          style={{
+            flex: 1,
+            height: 4,
+            background: "rgba(255,255,255,0.15)",
+            borderRadius: 2,
+            cursor: "pointer",
+            position: "relative",
+          }}
+        >
+          <div
+            style={{
+              height: "100%",
+              width: `${progressPercent}%`,
+              background: "#3b82f6",
+              borderRadius: 2,
+              transition: isDragging ? "none" : "width 0.1s linear",
+            }}
+          />
+          {/* 进度指示点 */}
+          <div
+            style={{
+              position: "absolute",
+              top: "50%",
+              left: `${progressPercent}%`,
+              transform: "translate(-50%, -50%)",
+              width: 10,
+              height: 10,
+              borderRadius: "50%",
+              background: "#3b82f6",
+              border: "2px solid #fff",
+              opacity: isDragging ? 1 : 0,
+              transition: "opacity 0.15s",
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default FrontendPreviewPlayer

apps/web/src/pages/generate/components/GenerateStepContent.tsx

@@ -2,6 +2,8 @@
  * GeneratePage 步骤内容渲染
  * 根据当前步骤渲染对应的 Step 组件
  * 步骤顺序：模板(1) → 素材(2) → 配音(3) → 标题(4) → 预览(5) → 封面(6) → 确认(7)
+ *
+ * V24: 移除 Step5 预览生成相关 props，改为纯标题样式编辑
  */
 import React from "react"
 import type { EditingTemplate } from "@/api/editing-planner"
@@ -9,7 +11,6 @@ import type { PresetVoiceItem } from "@/api/voices"
 import type { VoiceClone } from "@/api/voice-clone"
 import type { CoverConfig } from "../types/cover"
 import type { TitleSettings } from "../types"
-import type { PreviewItem, PreviewStatus } from "../hooks/useStep5Preview"
 import Step1TemplateSelect from "../components/Step1TemplateSelect"
 import Step2MaterialSelect from "../components/Step2MaterialSelect"
 import Step3VoiceSelect from "../components/Step5VoiceSelect"
@@ -74,16 +75,6 @@ export interface GenerateStepContentProps {
   onDismissError: () => void
   /* 其他 */
   presetVoices: PresetVoiceItem[]
-  /* Step5 预览（多预览） */
-  previewCount: number
-  onPreviewCountChange: (count: number) => void
-  previewItems: PreviewItem[]
-  previewOverallStatus: PreviewStatus
-  previewOverallError: string
-  previewOverallProgress: number
-  previewAnyGenerating: boolean
-  onGeneratePreview: () => void
-  onRegeneratePreview: () => void
 }
 
 export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) => {
@@ -128,15 +119,6 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     onRetry,
     onDismissError,
     presetVoices,
-    previewCount,
-    onPreviewCountChange,
-    previewItems,
-    previewOverallStatus,
-    previewOverallError,
-    previewOverallProgress,
-    previewAnyGenerating,
-    onGeneratePreview,
-    onRegeneratePreview,
   } = props
 
   switch (currentStep) {
@@ -176,15 +158,6 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     case 5:
       return (
         <Step5GeneratePreview
-          previewCount={previewCount}
-          onPreviewCountChange={onPreviewCountChange}
-          items={previewItems}
-          overallStatus={previewOverallStatus}
-          overallError={previewOverallError}
-          overallProgress={previewOverallProgress}
-          anyGenerating={previewAnyGenerating}
-          onGeneratePreview={onGeneratePreview}
-          onRegeneratePreview={onRegeneratePreview}
           titleSettings={titleSettings}
           onUpdatePosition={onUpdatePosition}
           onUpdateFont={onUpdateFont}

apps/web/src/pages/generate/components/PreviewVideoPanel.tsx

@@ -1,32 +1,35 @@
 /**
  * 右侧预览视频面板
  * Step4+: 显示预览视频面板
- * Step5+: 显示后端生成的预览视频
+ * Step5: 前端实时预览 — 用原生 video 播放素材片段 + CSS 标题叠加
  *
- * 设计说明：
- * - Step4（标题设置页）：右侧显示空状态提示，引导用户输入标题
- * - Step5（预览生成页）：显示后端返回的预览视频
- * - 标题 CSS 实时预览层：在预览视频上方叠加 CSS 标题，所见即所得
- *   渲染参数与后端 FFmpeg ASS 字幕完全对齐（PR #1401 坐标系）
+ * 架构改造：完全去除后端 FFmpeg 预览依赖
+ * - 使用 FrontendPreviewPlayer 直接播放素材片段
+ * - TitleOverlay CSS 层实时响应标题样式变化
  */
 import React, { useMemo } from "react"
-import { PlayCircleOutlined, LoadingOutlined } from "@ant-design/icons"
-import type { PreviewResult, PreviewStatus } from "../hooks/useStep5Preview"
+import { LoadingOutlined } from "@ant-design/icons"
+import type { AssetItem } from "@/api/assets"
+import type { EditingTemplate } from "@/api/editing-planner"
 import type { TitleSettings } from "../types"
+import FrontendPreviewPlayer from "./FrontendPreviewPlayer"
 
 interface PreviewVideoPanelProps {
-  previewStatus: PreviewStatus
-  previewResult: PreviewResult | null
-  previewError: string
-  progress: number
+  /** 已加载的素材列表 */
+  assets: AssetItem[]
+  /** 当前模板 */
+  template: EditingTemplate | null
+  /** 视频比例 */
   videoRatio: string
-  onRegenerate: () => void
+  /** 素材是否已加载就绪 */
+  assetsReady: boolean
+  /** 素材是否正在加载 */
+  assetsLoading: boolean
   /** 标题设置 — 用于 CSS 实时预览层 */
   titleSettings?: TitleSettings
 }
 
 /* ── ASS 坐标系参数（与后端 ass_subtitle_builder.py 一致） ── */
-/** 后端默认视频高度，用于百分比换算 */
 const ASS_VIDEO_HEIGHT = 720
 const ASS_TITLE_MARGIN_TOP = 60
 const ASS_TITLE_MARGIN_BOTTOM = 60
@@ -35,10 +38,9 @@ const ASS_TITLE_MARGIN_SIDE = 40
 /**
  * 根据 position 计算 CSS 垂直定位
  * 与后端 position_to_ass_alignment() 对齐：top→8, center→5, bottom→2
- * 使用百分比，与容器尺寸无关
  */
 function getPositionStyle(position: string): React.CSSProperties {
-  const sidePercent = (ASS_TITLE_MARGIN_SIDE / 1280) * 100 // ≈ 3.125%
+  const sidePercent = (ASS_TITLE_MARGIN_SIDE / 1280) * 100
 
   switch (position) {
     case "bottom":
@@ -72,10 +74,6 @@ function getPositionStyle(position: string): React.CSSProperties {
  * 所有渲染参数与后端 FFmpeg ASS 字幕一致
  */
 function buildTitleStyle(settings: TitleSettings): React.CSSProperties {
-  // 字号缩放：后端在 720p 视频上渲染，CSS 在预览容器上渲染
-  // 预览容器 max-height: 400px，用容器高度的百分比实现等比缩放
-  // fontSize = (settings.size / 720) * containerHeight → 用百分比表达
-  // 例如 size=28 → (28/720)*100 ≈ 3.89% of container height
   const fontSizePercent = (Math.min(settings.size, 36) / ASS_VIDEO_HEIGHT) * 100
 
   const base: React.CSSProperties = {
@@ -88,17 +86,14 @@ function buildTitleStyle(settings: TitleSettings): React.CSSProperties {
     wordBreak: "break-word",
     pointerEvents: "none",
     userSelect: "none",
-    // 水平内边距与 ASS margin_l/r 对齐
     paddingLeft: `${(ASS_TITLE_MARGIN_SIDE / 1280) * 100}%`,
     paddingRight: `${(ASS_TITLE_MARGIN_SIDE / 1280) * 100}%`,
   }
 
-  // 描边（stroke）→ CSS -webkit-text-stroke（与后端 outline_width=2 对齐）
   if (settings.stroke) {
     base.WebkitTextStroke = "1px #000000"
   }
 
-  // 阴影（shadow）→ CSS text-shadow（与后端 shadow_blur=4, offset=(2,2) 对齐）
   if (settings.shadow) {
     base.textShadow = "2px 2px 4px rgba(0,0,0,0.8)"
   }
@@ -108,7 +103,6 @@ function buildTitleStyle(settings: TitleSettings): React.CSSProperties {
 
 /**
  * CSS 标题预览覆盖层
- * 仅在预览视频已生成（status === ready）且有标题文字时显示
  */
 const TitleOverlay: React.FC<{ titleSettings: TitleSettings }> = ({ titleSettings }) => {
   const positionStyle = useMemo(
@@ -158,97 +152,62 @@ const TitleOverlay: React.FC<{ titleSettings: TitleSettings }> = ({ titleSetting
 /* ── 主组件 ── */
 
 export const PreviewVideoPanel: React.FC<PreviewVideoPanelProps> = ({
-  previewStatus,
-  previewResult,
-  previewError,
-  progress,
+  assets,
+  template,
   videoRatio,
-  onRegenerate,
+  assetsReady,
+  assetsLoading,
   titleSettings,
 }) => {
-  const hasPreview = previewStatus === "ready" && previewResult
-  const isLoading = previewStatus === "pending" || previewStatus === "generating"
-  const isError = previewStatus === "error"
   const videoAspectStyle = { aspectRatio: (videoRatio || "16:9").replace(":", "/") }
 
   return (
     <div className="xx-generate-preview">
       <div className="xx-preview-header">
         <h3>预览视频</h3>
-        {hasPreview && <span className="xx-preview-badge">480p 预览版</span>}
+        {assetsReady && assets.length > 0 && <span className="xx-preview-badge">实时预览</span>}
       </div>
 
-      {/* 空状态：还没生成预览 */}
-      {previewStatus === "idle" && (
-        <div className="xx-preview-empty">
-          <PlayCircleOutlined
-            style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }}
-          />
-          <p className="xx-preview-empty-title">暂无预览</p>
-          <p className="xx-preview-empty-desc">在左侧生成预览后在此查看</p>
-        </div>
-      )}
-
-      {/* 生成中 */}
-      {isLoading && (
+      {/* 加载中 */}
+      {assetsLoading && (
         <div className="xx-preview-loading-panel">
           <div className="xx-preview-video" style={videoAspectStyle}>
             <div className="xx-preview-loading-center">
               <LoadingOutlined style={{ fontSize: 36, color: "#fff" }} spin />
               <p style={{ marginTop: 12, color: "rgba(255,255,255,0.8)", fontSize: 14 }}>
-                {previewStatus === "pending" ? "排队中..." : `生成中 ${progress}%`}
+                加载素材中...
               </p>
             </div>
           </div>
-          <div className="xx-preview-progress-bar-wrap">
-            <div className="xx-preview-progress-fill" style={{ width: `${progress}%` }} />
-          </div>
         </div>
       )}
 
-      {/* 生成失败 */}
-      {isError && (
-        <div className="xx-preview-error-panel">
-          <div className="xx-preview-video xx-preview-video--error" style={videoAspectStyle}>
-            <p style={{ color: "rgba(255,255,255,0.8)", fontSize: 14 }}>预览生成失败</p>
-          </div>
-          <p className="xx-preview-error-msg">
-            {typeof previewError === "string" && previewError ? previewError : "请重试"}
-          </p>
-          <button className="xx-btn xx-btn-ghost xx-btn-block" onClick={onRegenerate}>
-            重新生成
-          </button>
+      {/* 前端预览播放器 + CSS 标题叠加 */}
+      {!assetsLoading && (
+        <div className="xx-preview-video" style={{ ...videoAspectStyle, position: "relative" }}>
+          <FrontendPreviewPlayer
+            assets={assets}
+            template={template}
+            videoRatio={videoRatio}
+            ready={assetsReady}
+          />
+          {/* CSS 标题实时预览层 — 与 FFmpeg ASS 渲染坐标对齐 */}
+          {titleSettings && <TitleOverlay titleSettings={titleSettings} />}
         </div>
       )}
 
-      {/* 预览成功 */}
-      {hasPreview && (
-        <>
-          <div className="xx-preview-video" style={{ ...videoAspectStyle, position: "relative" }}>
-            <video src={previewResult.videoUrl} controls preload="metadata" />
-            {/* CSS 标题实时预览层 — 与 FFmpeg ASS 渲染坐标对齐 */}
-            {titleSettings && <TitleOverlay titleSettings={titleSettings} />}
+      {/* 素材信息 */}
+      {assetsReady && assets.length > 0 && (
+        <div className="xx-preview-info">
+          <div className="xx-preview-info-row">
+            <span>素材数</span>
+            <span>{assets.length} 个</span>
           </div>
-          <div className="xx-preview-info">
-            <div className="xx-preview-info-row">
-              <span>时长</span>
-              <span>
-                {(typeof previewResult.duration === "number" ? previewResult.duration : 0).toFixed(
-                  1,
-                )}{" "}
-                秒
-              </span>
-            </div>
-            <div className="xx-preview-info-row">
-              <span>片段数</span>
-              <span>{previewResult.clipCount} 段</span>
-            </div>
-            <div className="xx-preview-info-row">
-              <span>比例</span>
-              <span>{videoRatio}</span>
-            </div>
+          <div className="xx-preview-info-row">
+            <span>比例</span>
+            <span>{videoRatio}</span>
           </div>
-        </>
+        </div>
       )}
     </div>
   )

apps/web/src/pages/generate/components/Step5GeneratePreview.tsx

@@ -1,33 +1,15 @@
 /**
- * Step 5 生成预览组件（支持多预览）
- * 调用后端预览生成接口，展示预览生成状态
- * 预览视频由右侧 PreviewVideoPanel 展示，本组件不重复显示预览网格
- * 标题样式面板（TitleStylePanel）在此展示，用户可实时调整标题样式
+ * Step 5 生成预览组件
+ * 架构改造：移除后端预览生成，改为前端实时预览
+ * 左侧仅保留标题样式面板，视频在右侧 PreviewVideoPanel 实时播放
  */
 import React from "react"
-import {
-  CheckCircleFilled,
-  ReloadOutlined,
-  PlayCircleOutlined,
-  ExclamationCircleFilled,
-  ClockCircleOutlined,
-} from "@ant-design/icons"
-import { InputNumber } from "antd"
+import { PlayCircleOutlined } from "@ant-design/icons"
 import { POSITION_OPTIONS, FONT_OPTIONS } from "../constants"
 import type { TitleSettings } from "../types"
-import type { PreviewItem, PreviewStatus } from "../hooks/useStep5Preview"
 import TitleStylePanel from "./title/TitleStylePanel"
 
 interface Step5GeneratePreviewProps {
-  previewCount: number
-  onPreviewCountChange: (count: number) => void
-  items: PreviewItem[]
-  overallStatus: PreviewStatus
-  overallError: string
-  overallProgress: number
-  anyGenerating: boolean
-  onGeneratePreview: () => void
-  onRegeneratePreview: () => void
   /* 标题样式 */
   titleSettings: TitleSettings
   onUpdatePosition: (position: string) => void
@@ -42,23 +24,7 @@ interface Step5GeneratePreviewProps {
   titlePresets: { key: string; label: string; previewStyle: React.CSSProperties }[]
 }
 
-/** 预览数量选项 */
-const PREVIEW_COUNT_OPTIONS = [
-  { value: 1, label: "1个" },
-  { value: 2, label: "2个" },
-  { value: 3, label: "3个" },
-]
-
 const Step5GeneratePreview: React.FC<Step5GeneratePreviewProps> = ({
-  previewCount,
-  onPreviewCountChange,
-  items,
-  overallStatus,
-  overallError,
-  overallProgress,
-  anyGenerating,
-  onGeneratePreview,
-  onRegeneratePreview,
   titleSettings,
   onUpdatePosition,
   onUpdateFont,
@@ -71,14 +37,31 @@ const Step5GeneratePreview: React.FC<Step5GeneratePreviewProps> = ({
   activePreset,
   titlePresets,
 }) => {
-  const isIdle = overallStatus === "idle"
-  const isError = overallStatus === "error" && !items.some((it) => it.status === "ready")
-
   return (
     <div className="xx-form-section">
-      <h3>🎬 生成预览</h3>
+      <h3>🎬 预览设置</h3>
 
-      {/* 标题样式面板 — 用户可实时调整标题样式，右侧预览同步更新 */}
+      {/* 前端实时预览提示 */}
+      <div
+        className="xx-preview-tip"
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: 8,
+          padding: "12px 16px",
+          background: "rgba(59, 130, 246, 0.08)",
+          borderRadius: 8,
+          marginBottom: 16,
+          border: "1px solid rgba(59, 130, 246, 0.15)",
+        }}
+      >
+        <PlayCircleOutlined style={{ fontSize: 18, color: "#3b82f6" }} />
+        <span style={{ fontSize: 13, color: "var(--text-secondary, #666)" }}>
+          右侧面板直接播放素材片段，调整标题样式可实时预览效果
+        </span>
+      </div>
+
+      {/* 标题样式面板 */}
       <TitleStylePanel
         settings={titleSettings}
         onUpdatePosition={onUpdatePosition}
@@ -94,116 +77,6 @@ const Step5GeneratePreview: React.FC<Step5GeneratePreviewProps> = ({
         POSITION_OPTIONS={POSITION_OPTIONS}
         FONT_OPTIONS={FONT_OPTIONS}
       />
-
-      {/* 预览数量选择器（仅在 idle 状态显示） */}
-      {isIdle && (
-        <div style={{ marginBottom: 16, display: "flex", alignItems: "center", gap: 12 }}>
-          <span style={{ fontSize: 14, color: "#666" }}>预览数量：</span>
-          <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
-            {PREVIEW_COUNT_OPTIONS.map((opt) => (
-              <button
-                key={opt.value}
-                type="button"
-                onClick={() => onPreviewCountChange(opt.value)}
-                style={{
-                  padding: "4px 12px",
-                  borderRadius: 6,
-                  border: previewCount === opt.value ? "1px solid #1677ff" : "1px solid #d9d9d9",
-                  background: previewCount === opt.value ? "#e6f4ff" : "#fff",
-                  color: previewCount === opt.value ? "#1677ff" : "#666",
-                  cursor: "pointer",
-                  fontSize: 13,
-                  fontWeight: previewCount === opt.value ? 600 : 400,
-                }}
-              >
-                {opt.label}
-              </button>
-            ))}
-            <InputNumber
-              min={1}
-              max={10}
-              value={previewCount}
-              onChange={(val) => val && onPreviewCountChange(val)}
-              style={{ width: 70 }}
-              placeholder="自定义"
-            />
-            <span style={{ fontSize: 12, color: "#999", marginLeft: 4 }}>（1~10）</span>
-          </div>
-          {previewCount > 1 && (
-            <span style={{ fontSize: 12, color: "#999" }}>生成多个预览可对比不同剪辑效果</span>
-          )}
-        </div>
-      )}
-
-      {/* 预览生成按钮（idle 状态） */}
-      {isIdle && (
-        <div className="xx-preview-generate-section">
-          <div className="xx-preview-generate-hint">
-            <PlayCircleOutlined style={{ fontSize: 32, color: "#3b82f6", marginBottom: 12 }} />
-            <p className="xx-preview-generate-title">一键生成剪辑预览</p>
-            <p className="xx-preview-generate-desc">
-              AI 将根据您选择的模板、素材和配音，智能生成
-              {previewCount > 1 ? `${previewCount}个不同版本的` : ""}视频预览（480p 低清版）
-            </p>
-          </div>
-          <button
-            className="xx-btn xx-btn-primary xx-preview-generate-btn"
-            onClick={onGeneratePreview}
-          >
-            ✨ 生成预览{previewCount > 1 ? `（${previewCount}个）` : ""}
-          </button>
-        </div>
-      )}
-
-      {/* 整体排队中（所有都在 pending） */}
-      {anyGenerating && items.every((it) => it.status === "pending") && (
-        <div className="xx-preview-loading">
-          <ClockCircleOutlined style={{ fontSize: 32, color: "#faad14" }} spin />
-          <p className="xx-preview-loading-text">预览排队中...</p>
-          <p className="xx-preview-loading-desc">正在等待渲染资源，请稍候</p>
-        </div>
-      )}
-
-      {/* 预览网格已移除 — 右侧 PreviewVideoPanel 已展示实际预览视频，左侧不再重复显示 */}
-
-      {/* 整体进度条（多预览生成中） */}
-      {anyGenerating && (
-        <div className="xx-preview-progress-bar" style={{ marginBottom: 12 }}>
-          <div className="xx-preview-progress-fill" style={{ width: `${overallProgress}%` }} />
-        </div>
-      )}
-
-      {/* 全部完成提示 */}
-      {overallStatus === "ready" && (
-        <div className="xx-preview-tip">
-          <CheckCircleFilled style={{ color: "#52c41a", marginRight: 8 }} />
-          <span>
-            {items.filter((it) => it.status === "ready").length} 个预览生成成功
-            "，请在右侧预览面板查看效果"
-          </span>
-          <button
-            className="xx-preview-regenerate-btn"
-            onClick={onRegeneratePreview}
-            title="重新生成"
-          >
-            <ReloadOutlined /> 重新生成
-          </button>
-        </div>
-      )}
-
-      {/* 全部失败 */}
-      {isError && (
-        <div className="xx-preview-error">
-          <ExclamationCircleFilled style={{ fontSize: 28, color: "#ef4444" }} />
-          <p className="xx-preview-error-text">预览生成失败</p>
-          <p className="xx-preview-error-desc">
-            {typeof overallError === "string" && overallError ? overallError : "请稍后重试"}
-          </p>
-          <button className="xx-btn xx-btn-primary" onClick={onRegeneratePreview}>
-            <ReloadOutlined /> 重新生成
-          </button>
-        </div>
-      )}
     </div>
   )
 }

apps/web/src/pages/generate/hooks/useGenerateVideo.ts

@@ -5,7 +5,7 @@
 import { useState, useCallback } from "react"
 import { message } from "antd"
 import type { GeneratedVideo } from "@/api/template-editor"
-import { confirmGeneration } from "@/api/generation"
+import { confirmGeneration, createPreview } from "@/api/generation"
 import type { UseGenerateVideoProps } from "./generate-video/types"
 import { getGenerationPhase } from "./generate-video/phase"
 import { useGenerationPolling } from "./generate-video/useGenerationPolling"
@@ -55,21 +55,17 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
     clearTimer()
 
     try {
-      // 使用确认生成 API（基于预览任务）
       // 解析分辨率：videoRatio 可能是 "9:16"（宽高比）或 "1080x1920"（分辨率）
       const ratio = props.videoRatio || "9:16"
       let outputWidth: number
       let outputHeight: number
 
       if (ratio.includes(":")) {
-        // 宽高比格式，如 "9:16" → 基于基准高度 1920 计算
         const [rw, rh] = ratio.split(":").map(Number)
         if (rw > 0 && rh > 0) {
-          // 基准：长边 1920，短边按比例计算
           const [longSide, shortSide] = rw < rh ? [rh, rw] : [rw, rh]
           const baseLong = 1920
           const baseShort = Math.round((baseLong * shortSide) / longSide)
-          // 确保偶数（FFmpeg 要求）
           const evenShort = baseShort - (baseShort % 2)
           if (rw < rh) {
             outputWidth = evenShort
@@ -83,7 +79,6 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
           outputHeight = 1920
         }
       } else if (ratio.includes("x")) {
-        // 分辨率格式，如 "1080x1920"
         const [wStr, hStr] = ratio.split("x")
         outputWidth = parseInt(wStr, 10) || 1080
         outputHeight = parseInt(hStr, 10) || 1920
@@ -92,7 +87,35 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
         outputHeight = 1920
       }
 
-      await confirmGeneration(props.previewTaskId, {
+      // 获取或创建后端任务 ID
+      // 预览改为前端播放后，不再有预览任务，需要在此处创建
+      let taskId = props.previewTaskId
+      if (!taskId) {
+        const assetIds =
+          props.materialMode === "auto" ? props.smartSelectedIds : props.selectedMaterials
+        const previewResp = await createPreview({
+          template_id: selectedTemplate,
+          asset_ids: assetIds,
+          duration: props.duration || undefined,
+          video_ratio: props.videoRatio,
+          voice_ids: undefined,
+          title_config: props.titleSettings?.title
+            ? {
+                text: props.titleSettings.title,
+                font: props.titleSettings.font,
+                font_size: props.titleSettings.size,
+                font_color: props.titleSettings.color,
+                position: props.titleSettings.position,
+                bold: props.titleSettings.bold,
+                stroke: props.titleSettings.stroke,
+                shadow: props.titleSettings.shadow,
+              }
+            : undefined,
+        })
+        taskId = previewResp.task_id
+      }
+
+      await confirmGeneration(taskId, {
         output_width: outputWidth,
         output_height: outputHeight,
         cover_url: props.coverSettings.upload_url || "",
@@ -109,7 +132,7 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
       setGenerateError(finalMsg)
       message.error(finalMsg)
     }
-  }, [props, clearTimer, startPolling])
+  }, [props, clearTimer, startPolling, selectedTemplate])
 
   /* 重新生成（失败后重试） */
   const retry = useCallback(() => {

apps/web/src/pages/generate/hooks/usePreviewAssets.ts

@@ -0,0 +1,104 @@
+/**
+ * 预览素材加载 Hook
+ * 根据选中的素材 ID 列表，批量获取素材详情（含 file_url、duration 等）
+ * 供前端预览播放器使用
+ */
+import { useState, useEffect, useCallback, useRef } from "react"
+import type { AssetItem } from "@/api/assets"
+import type { AxiosResponse } from "axios"
+
+/** 批量获取素材详情的 API 路径 */
+const ASSETS_BATCH_URL = "/assets/batch"
+
+/**
+ * 通过 ID 列表批量获取素材
+ * 优先使用批量接口，失败则回退为逐个获取
+ */
+async function fetchAssetsByIds(ids: string[]): Promise<AssetItem[]> {
+  if (!ids.length) return []
+
+  try {
+    // 尝试批量接口
+    const { default: apiClient } = await import("@/api/client")
+    const response = await apiClient.post(ASSETS_BATCH_URL, { ids })
+    const items: AssetItem[] = response.data?.items || response.data || []
+    if (items.length > 0) return items
+  } catch {
+    // 批量接口不存在，回退为逐个获取
+  }
+
+  // 回退：逐个获取
+  try {
+    const { default: apiClient } = await import("@/api/client")
+    const results = await Promise.allSettled(
+      ids.map((id) => apiClient.get<AssetItem>(`/assets/${id}`)),
+    )
+    return results
+      .filter(
+        (r): r is PromiseFulfilledResult<AxiosResponse<AssetItem>> =>
+          r.status === "fulfilled" && !!r.value?.data,
+      )
+      .map((r) => r.value.data)
+  } catch {
+    return []
+  }
+}
+
+interface UsePreviewAssetsReturn {
+  /** 加载后的素材列表 */
+  assets: AssetItem[]
+  /** 是否正在加载 */
+  loading: boolean
+  /** 是否已就绪（加载完成） */
+  ready: boolean
+  /** 手动触发重新加载 */
+  reload: () => void
+}
+
+/**
+ * usePreviewAssets — 加载选中素材的视频文件信息
+ */
+export function usePreviewAssets(assetIds: string[], enabled: boolean): UsePreviewAssetsReturn {
+  const [assets, setAssets] = useState<AssetItem[]>([])
+  const [loading, setLoading] = useState(false)
+  const [ready, setReady] = useState(false)
+  const requestIdRef = useRef(0)
+
+  const load = useCallback(async () => {
+    if (!assetIds.length || !enabled) {
+      setAssets([])
+      setReady(false)
+      return
+    }
+
+    const thisRequestId = ++requestIdRef.current
+    setLoading(true)
+    setReady(false)
+
+    try {
+      const result = await fetchAssetsByIds(assetIds)
+      // 防止竞态：只保留最新请求的结果
+      if (requestIdRef.current === thisRequestId) {
+        setAssets(result)
+        setReady(result.length > 0)
+      }
+    } catch {
+      if (requestIdRef.current === thisRequestId) {
+        setAssets([])
+        setReady(false)
+      }
+    } finally {
+      if (requestIdRef.current === thisRequestId) {
+        setLoading(false)
+      }
+    }
+  }, [assetIds, enabled])
+
+  useEffect(() => {
+    load()
+  }, [load])
+
+  return { assets, loading, ready, reload: load }
+}
+
+export default usePreviewAssets

apps/web/src/pages/generate/hooks/useSegmentScheduler.ts

@@ -0,0 +1,311 @@
+/**
+ * 素材片段调度器 Hook
+ * 控制原生 <video> 元素按时间线依次播放素材片段（入点→出点）
+ * 实现前端预览播放，替代后端 FFmpeg 渲染
+ */
+import React, { useState, useRef, useCallback, useEffect, useMemo } from "react"
+
+/** 单个播放片段 */
+export interface PlaybackSegment {
+  /** 素材 ID */
+  assetId: string
+  /** 素材视频 URL */
+  videoUrl: string
+  /** 片段在素材中的入点（秒） */
+  startTime: number
+  /** 片段在素材中的出点（秒） */
+  endTime: number
+  /** 片段在时间线中的顺序 */
+  order: number
+}
+
+/** 调度器返回 */
+export interface SegmentSchedulerState {
+  /** 是否正在播放 */
+  isPlaying: boolean
+  /** 当前播放的全局时间（秒） */
+  currentTime: number
+  /** 总时长（秒） */
+  totalDuration: number
+  /** 当前片段索引（在 segments 数组中的位置） */
+  currentSegmentIndex: number
+  /** 当前片段的本地播放时间 */
+  segmentLocalTime: number
+  /** 是否已播完 */
+  isEnded: boolean
+  /** 是否可以播放（至少有 1 个片段） */
+  canPlay: boolean
+  /** 播放 */
+  play: () => void
+  /** 暂停 */
+  pause: () => void
+  /** 切换播放/暂停 */
+  togglePlayPause: () => void
+  /** 跳转到全局时间 */
+  seekTo: (time: number) => void
+  /** 绑定到 <video> 元素 */
+  videoRef: React.RefObject<HTMLVideoElement>
+}
+
+/**
+ * 根据全局时间定位对应的片段和本地时间
+ */
+function findSegmentAtTime(
+  segments: PlaybackSegment[],
+  globalTime: number,
+): { index: number; localTime: number } {
+  let accumulated = 0
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i]
+    const segDuration = seg.endTime - seg.startTime
+    if (globalTime < accumulated + segDuration || i === segments.length - 1) {
+      return { index: i, localTime: seg.startTime + (globalTime - accumulated) }
+    }
+    accumulated += segDuration
+  }
+  return { index: segments.length - 1, localTime: segments[segments.length - 1].endTime }
+}
+
+/**
+ * 计算每个片段的全局起始时间
+ */
+function buildTimeline(segments: PlaybackSegment[]): number[] {
+  const starts: number[] = []
+  let acc = 0
+  for (const seg of segments) {
+    starts.push(acc)
+    acc += seg.endTime - seg.startTime
+  }
+  return starts
+}
+
+/**
+ * useSegmentScheduler — 素材片段调度器
+ */
+export function useSegmentScheduler(segments: PlaybackSegment[]): SegmentSchedulerState {
+  const videoRef = useRef<HTMLVideoElement | null>(null)
+  const [isPlaying, setIsPlaying] = useState(false)
+  const [currentTime, setCurrentTime] = useState(0)
+  const [currentSegmentIndex, setCurrentSegmentIndex] = useState(0)
+  const [isEnded, setIsEnded] = useState(false)
+  const rafRef = useRef<number>(0)
+  const isSeekingRef = useRef(false)
+
+  // 预加载用的隐藏 video 元素
+  const preloadVideoRef = useRef<HTMLVideoElement | null>(null)
+
+  // 计算时间线
+  const timelineStarts = useMemo(() => buildTimeline(segments), [segments])
+  const totalDuration = useMemo(
+    () => segments.reduce((sum, seg) => sum + (seg.endTime - seg.startTime), 0),
+    [segments],
+  )
+
+  const canPlay = segments.length > 0
+
+  // 当前片段信息
+  const currentSegment = segments[currentSegmentIndex] || null
+  const segmentLocalTime = currentSegment
+    ? currentTime - (timelineStarts[currentSegmentIndex] || 0) + currentSegment.startTime
+    : 0
+
+  /** 切换到指定片段 */
+  const switchToSegment = useCallback(
+    (index: number, seekToLocalTime?: number) => {
+      const video = videoRef.current
+      if (!video || index >= segments.length) return
+
+      const seg = segments[index]
+      video.src = seg.videoUrl
+
+      const localTime = seekToLocalTime ?? seg.startTime
+      // 等待 src 设置后再设置 currentTime
+      const onLoaded = () => {
+        video.currentTime = localTime
+        video.removeEventListener("loadedmetadata", onLoaded)
+      }
+      video.addEventListener("loadedmetadata", onLoaded)
+
+      setCurrentSegmentIndex(index)
+
+      // 预加载下一段
+      if (index + 1 < segments.length) {
+        const nextSeg = segments[index + 1]
+        if (!preloadVideoRef.current) {
+          preloadVideoRef.current = document.createElement("video")
+          preloadVideoRef.current.preload = "auto"
+        }
+        preloadVideoRef.current.src = nextSeg.videoUrl
+      }
+    },
+    [segments],
+  )
+
+  /** 播放循环 — 检测片段边界并切换 */
+  const tick = useCallback(() => {
+    const video = videoRef.current
+    if (!video || isSeekingRef.current) {
+      rafRef.current = requestAnimationFrame(tick)
+      return
+    }
+
+    const seg = segments[currentSegmentIndex]
+    if (!seg) return
+
+    // 检查是否到达出点（容差 0.15s）
+    if (video.currentTime >= seg.endTime - 0.15) {
+      const nextIndex = currentSegmentIndex + 1
+      if (nextIndex < segments.length) {
+        // 切到下一段
+        switchToSegment(nextIndex)
+        const accumulatedTime =
+          (timelineStarts[currentSegmentIndex] || 0) + (seg.endTime - seg.startTime)
+        setCurrentTime(accumulatedTime)
+      } else {
+        // 播放结束
+        video.pause()
+        setIsPlaying(false)
+        setIsEnded(true)
+        setCurrentTime(totalDuration)
+        return
+      }
+    } else {
+      // 更新全局时间
+      const globalTime =
+        (timelineStarts[currentSegmentIndex] || 0) + (video.currentTime - seg.startTime)
+      setCurrentTime(Math.max(0, Math.min(globalTime, totalDuration)))
+    }
+
+    rafRef.current = requestAnimationFrame(tick)
+  }, [segments, currentSegmentIndex, timelineStarts, totalDuration, switchToSegment])
+
+  /** 播放 */
+  const play = useCallback(async () => {
+    const video = videoRef.current
+    if (!video || !canPlay) return
+
+    setIsEnded(false)
+
+    // 如果还没设置 src（首次播放），先加载第一段
+    if (!video.src || video.src === "") {
+      switchToSegment(0)
+    }
+
+    try {
+      await video.play()
+      setIsPlaying(true)
+      rafRef.current = requestAnimationFrame(tick)
+    } catch {
+      // 自动播放可能被浏览器阻止，忽略
+      console.warn("[useSegmentScheduler] auto-play blocked by browser")
+    }
+  }, [canPlay, switchToSegment, tick])
+
+  /** 暂停 */
+  const pause = useCallback(() => {
+    const video = videoRef.current
+    if (video) video.pause()
+    setIsPlaying(false)
+    cancelAnimationFrame(rafRef.current)
+  }, [])
+
+  /** 切换播放/暂停 */
+  const togglePlayPause = useCallback(() => {
+    if (isPlaying) {
+      pause()
+    } else {
+      if (isEnded) {
+        // 播放结束后再次播放，从头开始
+        setIsEnded(false)
+        switchToSegment(0, segments[0]?.startTime)
+        const video = videoRef.current
+        if (video) {
+          const onSeeked = () => {
+            video.play().catch(() => {})
+            setIsPlaying(true)
+            setCurrentTime(0)
+            rafRef.current = requestAnimationFrame(tick)
+            video.removeEventListener("seeked", onSeeked)
+          }
+          video.addEventListener("seeked", onSeeked)
+        }
+      } else {
+        play()
+      }
+    }
+  }, [isPlaying, isEnded, pause, play, switchToSegment, segments, tick])
+
+  /** 跳转到指定全局时间 */
+  const seekTo = useCallback(
+    (time: number) => {
+      const video = videoRef.current
+      if (!video || !canPlay) return
+
+      const clampedTime = Math.max(0, Math.min(time, totalDuration))
+      const { index, localTime } = findSegmentAtTime(segments, clampedTime)
+
+      isSeekingRef.current = true
+
+      // 如果片段变了，需要切换 src
+      if (index !== currentSegmentIndex) {
+        switchToSegment(index, localTime)
+        // switchToSegment 会设置 src 并在 loadedmetadata 后设置 currentTime
+        // 所以这里不需要再设置
+      } else {
+        video.currentTime = localTime
+      }
+
+      setCurrentTime(clampedTime)
+      setCurrentSegmentIndex(index)
+      setIsEnded(false)
+
+      // 延迟恢复 tick 检测
+      setTimeout(() => {
+        isSeekingRef.current = false
+      }, 200)
+    },
+    [canPlay, totalDuration, segments, currentSegmentIndex, switchToSegment],
+  )
+
+  // 组件卸载时清理
+  useEffect(() => {
+    return () => {
+      cancelAnimationFrame(rafRef.current)
+      if (preloadVideoRef.current) {
+        preloadVideoRef.current.src = ""
+        preloadVideoRef.current = null
+      }
+    }
+  }, [])
+
+  // 片段列表变化时重置
+  useEffect(() => {
+    cancelAnimationFrame(rafRef.current)
+    setIsPlaying(false)
+    setCurrentTime(0)
+    setCurrentSegmentIndex(0)
+    setIsEnded(false)
+    const video = videoRef.current
+    if (video) {
+      video.pause()
+      video.src = ""
+    }
+  }, [segments])
+
+  return {
+    isPlaying,
+    currentTime,
+    totalDuration,
+    currentSegmentIndex,
+    segmentLocalTime,
+    isEnded,
+    canPlay,
+    play,
+    pause,
+    togglePlayPause,
+    seekTo,
+    videoRef,
+  }
+}
+
+export default useSegmentScheduler

apps/web/src/pages/generate/hooks/useStep5Preview.ts

@@ -1,476 +0,0 @@
-/**
- * Step 5 生成预览 Hook（支持多预览 + voice_ids）
- * 调用 /generation/preview 接口创建多个预览任务，轮询状态直到全部完成
- */
-import { useState, useCallback, useMemo, useEffect, useRef } from "react"
-import { createPreview, getPreviewStatus } from "@/api/generation"
-import { updateEditPlan } from "@/api/template-editor/editPlans"
-import type { PreviewTaskResponse, PreviewStatus as ApiPreviewStatus } from "@/api/generation"
-import type { EditingTemplate } from "@/api/editing-planner"
-import { safeExtractError } from "./generate-video/errorUtils"
-import type { TitleSettings } from "../types"
-
-/** 安全地将值转为字符串，防止对象被直接渲染导致 React Error #31 */
-const safeString = (val: unknown, fallback: string): string => {
-  if (val == null) return fallback
-  const s = safeExtractError(val)
-  return s || fallback
-}
-
-/** 安全地将值转为数字，防止非数字值进入渲染 */
-const safeNumber = (val: unknown, fallback = 0): number => {
-  if (typeof val === "number" && !Number.isNaN(val)) return val
-  if (typeof val === "string") {
-    const n = Number(val)
-    return Number.isNaN(n) ? fallback : n
-  }
-  return fallback
-}
-
-interface UseStep5PreviewProps {
-  templates: EditingTemplate[]
-  selectedTemplate: string
-  materialMode: "manual" | "auto"
-  selectedMaterials: string[]
-  smartSelectedIds: string[]
-  duration: number
-  videoRatio: string
-  /** 配音 voice_ids（传给后端，让预览包含配音音频） */
-  voiceIds?: string[]
-  /** 配音素材库ID（用户选择的上传音频或AI配音素材） */
-  voiceLibraryId?: string
-  /** 要生成的预览数量 */
-  previewCount?: number
-  /** 标题设置（传递给后端，让预览视频包含标题） */
-  titleSettings?: TitleSettings
-}
-
-export type PreviewStatus = "idle" | "pending" | "generating" | "ready" | "error"
-
-/** 单个预览生成结果 */
-export interface PreviewResult {
-  taskId: string
-  videoUrl: string
-  clipCount: number
-  transitionCount: number
-  materialUsage: number
-  duration: number
-  fileSize: number
-  generateDuration: number
-  progress: number
-}
-
-/** 单个预览项的完整状态（用于多预览） */
-export interface PreviewItem {
-  index: number
-  status: PreviewStatus
-  result: PreviewResult | null
-  error: string
-  progress: number
-}
-
-// 轮询超时时间（10 分钟）
-const POLL_TIMEOUT_MS = 10 * 60 * 1000
-
-/** 初始单项状态 */
-const createInitialItem = (index: number): PreviewItem => ({
-  index,
-  status: "idle",
-  result: null,
-  error: "",
-  progress: 0,
-})
-
-export function useStep5Preview({
-  templates,
-  selectedTemplate,
-  materialMode,
-  selectedMaterials,
-  smartSelectedIds,
-  duration,
-  videoRatio,
-  voiceIds,
-  voiceLibraryId,
-  previewCount = 1,
-  titleSettings,
-}: UseStep5PreviewProps) {
-  const templateName = useMemo(
-    () => templates.find((t) => t.id === selectedTemplate)?.name ?? "未选择",
-    [templates, selectedTemplate],
-  )
-
-  const materialCount = useMemo(() => {
-    if (materialMode === "auto") {
-      return `${smartSelectedIds.length} 个素材（智能匹配）`
-    }
-    return `${selectedMaterials.length} 个素材`
-  }, [materialMode, selectedMaterials.length, smartSelectedIds.length])
-
-  const materialTotal = materialMode === "auto" ? smartSelectedIds.length : selectedMaterials.length
-
-  /* ── 多预览状态 ── */
-  const [items, setItems] = useState<PreviewItem[]>(() =>
-    Array.from({ length: previewCount }, (_, i) => createInitialItem(i)),
-  )
-  const [selectedIndex, setSelectedIndex] = useState(0)
-
-  // 每个任务 ID + 轮询定时器，用于防止竞态条件（按 index 存储）
-  const taskIdsRef = useRef<Map<number, string>>(new Map())
-  const pollTimersRef = useRef<Map<number, ReturnType<typeof setTimeout>>>(new Map())
-  const startTimeRef = useRef<number>(0)
-
-  const clearPollTimer = useCallback((index?: number) => {
-    if (index !== undefined) {
-      const timer = pollTimersRef.current.get(index)
-      if (timer) {
-        clearTimeout(timer)
-        pollTimersRef.current.delete(index)
-      }
-    } else {
-      pollTimersRef.current.forEach((timer) => clearTimeout(timer))
-      pollTimersRef.current.clear()
-    }
-  }, [])
-
-  // 同步 previewCount 变化（增减项）
-  useEffect(() => {
-    setItems((prev) => {
-      if (prev.length === previewCount) return prev
-      if (prev.length > previewCount) return prev.slice(0, previewCount)
-      return [
-        ...prev,
-        ...Array.from({ length: previewCount - prev.length }, (_, i) =>
-          createInitialItem(prev.length + i),
-        ),
-      ]
-    })
-    // 如果 selectedIndex 超出范围，重置
-    setSelectedIndex((prev) => Math.min(prev, previewCount - 1))
-  }, [previewCount])
-
-  /* ── 参数变化时重置所有预览状态 ── */
-  const prevDepsRef = useRef({
-    selectedTemplate,
-    materialMode,
-    selectedMaterials: [...selectedMaterials].sort().join(","),
-    smartSelectedIds: [...smartSelectedIds].sort().join(","),
-    duration,
-    videoRatio,
-    voiceIds: [...(voiceIds || [])].sort().join(","),
-    titleSettings: titleSettings?.title || "",
-  })
-
-  useEffect(() => {
-    const currentKey = [
-      selectedTemplate,
-      materialMode,
-      [...selectedMaterials].sort().join(","),
-      [...smartSelectedIds].sort().join(","),
-      duration,
-      videoRatio,
-      [...(voiceIds || [])].sort().join(","),
-      titleSettings?.title || "",
-    ].join("|")
-
-    const prevKey = [
-      prevDepsRef.current.selectedTemplate,
-      prevDepsRef.current.materialMode,
-      prevDepsRef.current.selectedMaterials,
-      prevDepsRef.current.smartSelectedIds,
-      prevDepsRef.current.duration,
-      prevDepsRef.current.videoRatio,
-      prevDepsRef.current.voiceIds,
-      prevDepsRef.current.titleSettings,
-    ].join("|")
-
-    if (prevKey !== currentKey && items.some((it) => it.status !== "idle")) {
-      taskIdsRef.current.clear()
-      clearPollTimer()
-      setItems(Array.from({ length: previewCount }, (_, i) => createInitialItem(i)))
-      setSelectedIndex(0)
-    }
-
-    prevDepsRef.current = {
-      selectedTemplate,
-      materialMode,
-      selectedMaterials: [...selectedMaterials].sort().join(","),
-      smartSelectedIds: [...smartSelectedIds].sort().join(","),
-      duration,
-      videoRatio,
-      voiceIds: [...(voiceIds || [])].sort().join(","),
-      titleSettings: titleSettings?.title || "",
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    selectedTemplate,
-    materialMode,
-    selectedMaterials,
-    smartSelectedIds,
-    duration,
-    videoRatio,
-    voiceIds,
-    previewCount,
-    titleSettings,
-  ])
-
-  // 组件卸载时清理所有轮询
-  useEffect(() => {
-    return () => {
-      clearPollTimer()
-    }
-  }, [clearPollTimer])
-
-  /** 轮询单个预览任务状态 */
-  const pollPreviewStatus = useCallback(
-    (index: number, taskId: string) => {
-      const poll = async () => {
-        // 竞态检查
-        if (taskIdsRef.current.get(index) !== taskId) return
-
-        // 超时检查
-        if (Date.now() - startTimeRef.current > POLL_TIMEOUT_MS) {
-          setItems((prev) =>
-            prev.map((it) =>
-              it.index === index ? { ...it, status: "error", error: "预览生成超时，请重试" } : it,
-            ),
-          )
-          return
-        }
-
-        try {
-          const data: PreviewTaskResponse = await getPreviewStatus(taskId)
-
-          if (taskIdsRef.current.get(index) !== taskId) return
-
-          const status = data.status as ApiPreviewStatus
-
-          if (status === "completed") {
-            const result: PreviewResult = {
-              taskId: safeString(data.task_id, ""),
-              videoUrl: safeString(data.video_url, ""),
-              clipCount: safeNumber(data.clip_count),
-              transitionCount: safeNumber(data.transition_count),
-              materialUsage: safeNumber(data.material_usage),
-              duration: safeNumber(data.duration),
-              fileSize: safeNumber(data.file_size),
-              generateDuration: safeNumber(data.generate_duration),
-              progress: 100,
-            }
-            setItems((prev) =>
-              prev.map((it) =>
-                it.index === index ? { ...it, status: "ready", result, progress: 100 } : it,
-              ),
-            )
-
-            // 保存预览视频 URL 到 plan config，供封面生成使用
-            if (result.videoUrl && selectedTemplate) {
-              updateEditPlan(selectedTemplate, {
-                config: { rendered_storage_key: result.videoUrl },
-              }).catch((err) => {
-                console.warn("[Step4] 保存预览视频URL到plan config失败:", err)
-              })
-            }
-            return
-          }
-
-          if (status === "failed") {
-            setItems((prev) =>
-              prev.map((it) =>
-                it.index === index
-                  ? {
-                      ...it,
-                      status: "error",
-                      error: safeString(data.error_message, "预览生成失败，请重试"),
-                    }
-                  : it,
-              ),
-            )
-            return
-          }
-
-          if (status === "cancelled") {
-            setItems((prev) =>
-              prev.map((it) =>
-                it.index === index ? { ...it, status: "error", error: "预览任务已取消" } : it,
-              ),
-            )
-            return
-          }
-
-          // pending / generating 状态继续轮询
-          const prog = safeNumber(data.progress)
-          const nextStatus: PreviewStatus = status === "pending" ? "pending" : "generating"
-          setItems((prev) =>
-            prev.map((it) =>
-              it.index === index ? { ...it, status: nextStatus, progress: prog } : it,
-            ),
-          )
-          const delay = status === "pending" ? 5000 : 2000
-          pollTimersRef.current.set(index, setTimeout(poll, delay))
-        } catch {
-          if (taskIdsRef.current.get(index) !== taskId) return
-          pollTimersRef.current.set(index, setTimeout(poll, 3000))
-        }
-      }
-
-      pollTimersRef.current.set(index, setTimeout(poll, 1000))
-    },
-    [selectedTemplate],
-  )
-
-  /** 生成所有预览 */
-  const generatePreview = useCallback(async () => {
-    if (!selectedTemplate) {
-      setItems((prev) => prev.map((it) => ({ ...it, status: "error", error: "请先选择模板" })))
-      return
-    }
-    if (materialTotal === 0) {
-      setItems((prev) => prev.map((it) => ({ ...it, status: "error", error: "请先选择素材" })))
-      return
-    }
-
-    // 取消之前的所有轮询
-    clearPollTimer()
-    taskIdsRef.current.clear()
-
-    // 初始化所有项为 pending
-    setItems(
-      Array.from({ length: previewCount }, (_, i) => ({
-        index: i,
-        status: "pending" as PreviewStatus,
-        result: null,
-        error: "",
-        progress: 0,
-      })),
-    )
-    setSelectedIndex(0)
-    startTimeRef.current = Date.now()
-
-    const assetIds = materialMode === "auto" ? smartSelectedIds : selectedMaterials
-
-    // 并发创建所有预览任务（Promise.all 并行请求，减少串行等待）
-    const createTasks = Array.from({ length: previewCount }, async (_, i) => {
-      try {
-        const response = await createPreview({
-          template_id: selectedTemplate,
-          asset_ids: assetIds,
-          duration: duration || undefined,
-          video_ratio: videoRatio,
-          voice_ids: voiceIds && voiceIds.length > 0 ? voiceIds : undefined,
-          voice_library_id: voiceLibraryId || undefined,
-          // 标题烧录配置
-          title_config: titleSettings?.title
-            ? {
-                text: titleSettings.title,
-                font: titleSettings.font,
-                font_size: titleSettings.size,
-                font_color: titleSettings.color,
-                position: titleSettings.position,
-                bold: titleSettings.bold,
-                stroke: titleSettings.stroke,
-                shadow: titleSettings.shadow,
-              }
-            : undefined,
-        })
-
-        if (startTimeRef.current === 0) return
-
-        taskIdsRef.current.set(i, response.task_id)
-        pollPreviewStatus(i, response.task_id)
-      } catch (e) {
-        const errMsg = safeString(e instanceof Error ? e.message : e, "预览生成失败")
-        setItems((prev) =>
-          prev.map((it) => (it.index === i ? { ...it, status: "error", error: errMsg } : it)),
-        )
-      }
-    })
-    await Promise.all(createTasks)
-  }, [
-    selectedTemplate,
-    materialTotal,
-    materialMode,
-    smartSelectedIds,
-    selectedMaterials,
-    duration,
-    videoRatio,
-    voiceIds,
-    voiceLibraryId,
-    previewCount,
-    titleSettings,
-    clearPollTimer,
-    pollPreviewStatus,
-  ])
-
-  /** 重新生成所有预览 */
-  const regeneratePreview = useCallback(() => {
-    generatePreview()
-  }, [generatePreview])
-
-  /** 是否所有预览都已完成 */
-  const allReady = items.length > 0 && items.every((it) => it.status === "ready")
-  /** 是否至少有一个预览已完成 */
-  const anyReady = items.some((it) => it.status === "ready")
-  /** 是否有任一正在生成中 */
-  const anyGenerating = items.some((it) => it.status === "pending" || it.status === "generating")
-
-  /** 当前选中的预览结果 */
-  const selectedResult = items[selectedIndex]?.result ?? null
-
-  /** 综合状态（兼容旧逻辑） */
-  const previewStatus: PreviewStatus = useMemo(() => {
-    if (items.every((it) => it.status === "idle")) return "idle"
-    if (items.some((it) => it.status === "pending" || it.status === "generating"))
-      return "generating"
-    if (allReady) return "ready"
-    if (items.every((it) => it.status === "error")) return "error"
-    // 部分完成部分出错
-    if (anyReady) return "ready"
-    return "error"
-  }, [items, allReady, anyReady])
-
-  /** 综合进度（取平均） */
-  const progress = useMemo(() => {
-    if (items.length === 0) return 0
-    return Math.round(items.reduce((sum, it) => sum + it.progress, 0) / items.length)
-  }, [items])
-
-  /** 综合错误信息 */
-  const previewError = useMemo(() => {
-    const errorItems = items.filter((it) => it.status === "error" && it.error)
-    if (errorItems.length === 0) return ""
-    if (errorItems.length === 1) return errorItems[0].error
-    return `${errorItems.length} 个预览生成失败`
-  }, [items])
-
-  const canProceed = anyReady
-
-  /** 当前选中预览的 taskId（用于确认生成时复用预览产物） */
-  const selectedTaskId = selectedResult?.taskId ?? ""
-
-  return {
-    templateName,
-    materialCount,
-    duration,
-    videoRatio,
-    // 多预览状态
-    items,
-    selectedIndex,
-    setSelectedIndex,
-    previewCount,
-    // 综合状态
-    previewStatus,
-    previewResult: selectedResult,
-    previewError,
-    progress,
-    canProceed,
-    allReady,
-    anyReady,
-    anyGenerating,
-    generatePreview,
-    regeneratePreview,
-    // 确认生成复用预览产物
-    selectedTaskId,
-  }
-}
-
-export default useStep5Preview

apps/web/src/pages/generate/hooks/useStepNavigation.ts

@@ -2,6 +2,8 @@
  * GeneratePage 步骤导航
  * 管理步骤切换与各步骤的前置校验
  * 步骤顺序：模板(1) → 素材(2) → 配音(3) → 标题(4) → 预览(5) → 封面(6) → 确认(7)
+ *
+ * V24: previewReady 改为前端素材加载状态
  */
 import { message } from "antd"
 import type { TitleSettings } from "../types"
@@ -14,7 +16,7 @@ export interface UseStepNavigationOptions {
   selectedMaterials: string[]
   smartSelectedIds: string[]
   titleSettings: TitleSettings
-  /** Step4 是否已生成预览 */
+  /** 预览是否就绪（前端素材已加载） */
   previewReady: boolean
 }
 
@@ -54,7 +56,7 @@ export const useStepNavigation = (options: UseStepNavigationOptions): UseStepNav
       return
     }
     if (currentStep === 5 && !previewReady) {
-      message.warning("请先生成剪辑预览")
+      message.warning("请先选择素材以预览效果")
       return
     }
     if (currentStep < 7) {