xueteng/video-flow-b

Fork 0

forked from 77media/video-flow

moux1024 ce6a6d84d4 项目名批量更新

2025-10-27 15:48:42 +08:00

11 KiB

Raw Blame History

video-flow-b AI 剪辑集成技术文档

📋 项目概述

本文档详细记录了将 OpenCut 项目的 AI 智能剪辑功能集成到 video-flow-b 工作流系统中的完整技术方案。该集成实现了从剧本生成的视频片段到最终成片的自动化 AI 剪辑流程。

🎯 集成目标

自动化剪辑: 在 video-flow-b 工作流中实现一键 AI 剪辑功能
无缝集成: 复用 OpenCut 的核心 AI 剪辑逻辑，无需重复开发
流程优化: 简化从视频片段到最终成片的处理流程
用户体验: 提供直观的进度反馈和错误处理机制

🏗️ 架构设计

整体架构图

graph TB
    subgraph "video-flow-b 前端层"
        A[work-flow.tsx] --> B[ai-editing-button.tsx]
        B --> C[ai-editing-adapter.ts]
    end

    subgraph "API 适配层"
        C --> D[/api/export/ai-clips]
        D --> E[export-adapter.ts]
    end

    subgraph "OpenCut 核心逻辑"
        E --> F[FFmpeg处理]
        F --> G[视频导出]
        G --> H[云存储上传]
    end

    subgraph "video-flow-b 后端"
        H --> I[任务状态更新]
        I --> J[最终成片展示]
    end

核心组件关系

classDiagram
    class WorkFlowPage {
        +handleAIEditingComplete()
        +handleAIEditingError()
        +showGotoCutButton: boolean
    }

    class AIEditingButton {
        +onClick()
        +showProgress()
        +handleComplete()
    }

    class AIEditingAdapter {
        +executeAIEditing()
        +convertVideoFlowData()
        +callExportAPI()
    }

    class ExportAdapter {
        +POST()
        +processFFmpeg()
        +uploadToCloud()
    }

    WorkFlowPage --> AIEditingButton
    AIEditingButton --> AIEditingAdapter
    AIEditingAdapter --> ExportAdapter

📁 文件结构

video-flow-b/
├── components/pages/work-flow/
│   ├── ai-editing-adapter.ts      # AI剪辑逻辑适配器
│   ├── ai-editing-button.tsx      # AI剪辑按钮组件
│   └── work-flow.tsx              # 主工作流页面(已修改)
├── app/api/export/
│   ├── ai-clips/route.ts          # AI剪辑导出API路由
│   └── download/[exportId]/route.ts # 视频下载API路由
├── api/
│   └── export-adapter.ts          # 导出API适配器
└── docs/
    └── AI-EDITING-INTEGRATION.md  # 本技术文档

🔧 核心组件详解

1. AI 剪辑适配器 (`ai-editing-adapter.ts`)

职责: 将 video-flow-b 的数据结构转换为 OpenCut 兼容格式，并管理整个 AI 剪辑流程。

核心功能:

class AIEditingAdapter {
  // 执行完整的AI剪辑流程
  async executeAIEditing(): Promise<string>;

  // 数据格式转换
  private convertVideoFlowToAIClips(): AIClipData[];

  // 调用导出API
  private callExportAPI(): Promise<string>;

  // 进度回调管理
  private onProgress?: (progress: number, message: string) => void;
}

数据转换逻辑:

// video-flow-b格式 -> OpenCut AI剪辑格式
{
  videos: VideoFlowVideoData[]
}
↓
{
  clips: AIClipData[],
  totalDuration: number,
  options: ExportOptions
}

2. AI 剪辑按钮组件 (`ai-editing-button.tsx`)

职责: 提供用户交互界面，显示剪辑进度和状态反馈。

功能特性:

✨ 美观的玻璃态设计
📊 实时进度显示
🔄 状态管理（待机/处理中/完成/错误）
🎭 流畅的动画效果
📱 响应式设计

使用示例:

<AIEditingIconButton
  projectId={episodeId}
  taskObject={taskObject}
  onComplete={handleAIEditingComplete}
  onError={handleAIEditingError}
/>

3. 导出 API 适配器 (`export-adapter.ts`)

职责: 复用 OpenCut 的 FFmpeg 处理逻辑，提供流式进度反馈。

核心流程:

数据验证: 检查输入的视频片段数据
FFmpeg 处理: 执行视频剪辑和合成
进度推送: 通过 Server-Sent Events 推送实时进度
云存储上传: 将处理完成的视频上传到云存储
URL 返回: 返回最终的视频访问链接

🚀 完整工作流程

1. 触发条件

// 当video-flow-b工作流进入video阶段且有视频片段时
if (taskObject.currentStage === "video" && taskObject.videos.data.length > 0) {
  // 显示AI剪辑按钮
  showAIEditingButton = true;
}

2. AI 剪辑执行流程

sequenceDiagram
    participant U as 用户
    participant B as AI剪辑按钮
    participant A as AI适配器
    participant API as 导出API
    participant F as FFmpeg
    participant C as 云存储
    participant W as WorkFlow页面

    U->>B: 点击AI剪辑按钮
    B->>A: executeAIEditing()
    A->>A: convertVideoFlowToAIClips()
    A->>API: POST /api/export/ai-clips
    API->>F: 启动FFmpeg处理

    loop 进度更新
        F->>API: 处理进度
        API->>A: Server-Sent Events
        A->>B: onProgress回调
        B->>U: 更新进度UI
    end

    F->>C: 上传处理完成的视频
    C->>API: 返回视频URL
    API->>A: 完成通知
    A->>B: onComplete回调
    B->>W: handleAIEditingComplete()
    W->>W: 更新任务状态到final_video

3. 数据流转换

输入数据结构:

// video-flow-b视频数据
interface VideoFlowVideoData {
  id: string;
  url: string;
  scene_id: string;
  duration?: number;
  // ... 其他字段
}

转换后数据结构:

// OpenCut AI剪辑格式
interface AIClipData {
  sequence_clip_id: string;
  source_clip_id: string;
  video_url: string;
  source_in_timecode: string;
  source_out_timecode: string;
  sequence_start_timecode: string;
  clip_duration_in_sequence: string;
  corresponding_script_scene_id?: string;
}

🔌 API 接口文档

POST /api/export/ai-clips

描述: AI 剪辑导出接口，复用 OpenCut 的核心导出逻辑

请求体:

{
  clips: AIClipData[];
  subtitles?: string;
  totalDuration: number;
  options: {
    quality: 'low' | 'standard' | 'high';
    format: 'mp4' | 'webm' | 'mov';
    fps?: number;
  };
}

响应格式: Server-Sent Events 流式响应

// 进度更新
data: {"type": "progress", "progress": 45, "message": "处理视频片段 2/5"}

// 完成通知
data: {"type": "completed", "downloadUrl": "https://example.com/video.mp4"}

GET /api/export/download/[exportId]

描述: 导出视频下载接口

参数:

exportId: 导出任务 ID

响应:

成功: 返回视频文件流
失败: 返回错误 JSON

🎨 UI/UX 设计

按钮状态设计

enum AIEditingState {
  IDLE = "idle", // 待机状态 - 显示剪刀图标
  PROCESSING = "processing", // 处理中 - 显示进度环
  COMPLETED = "completed", // 完成 - 显示对勾图标
  ERROR = "error", // 错误 - 显示错误图标
}

进度显示设计

// 进度阶段划分
const PROGRESS_STAGES = {
  DATA_CONVERSION: { start: 0, end: 20, message: "数据转换中..." },
  VIDEO_PROCESSING: { start: 20, end: 80, message: "AI剪辑处理中..." },
  UPLOAD_COMPLETE: { start: 80, end: 100, message: "上传完成！" },
};

视觉效果

玻璃态设计: 使用backdrop-blur-lg实现磨砂玻璃效果
动画效果: 使用 Framer Motion 实现流畅的状态转换
进度指示: 圆形进度条配合百分比显示
状态反馈: 不同状态使用不同的颜色和图标

🔧 配置与部署

环境依赖

{
  "dependencies": {
    "framer-motion": "^10.x.x",
    "lucide-react": "^0.x.x",
    "antd": "^5.x.x"
  }
}

环境变量

# 云存储配置（继承自OpenCut项目）
QINIU_ACCESS_KEY=your_access_key
QINIU_SECRET_KEY=your_secret_key
QINIU_BUCKET=your_bucket_name
QINIU_DOMAIN=your_domain

# FFmpeg配置
FFMPEG_PATH=/usr/local/bin/ffmpeg

部署检查清单

确保 FFmpeg 已正确安装
验证云存储配置
检查 API 路由是否正确注册
测试流式响应功能
验证错误处理机制

🧪 测试策略

单元测试

describe("AIEditingAdapter", () => {
  test("应该正确转换video-flow-b数据格式", () => {
    const adapter = new AIEditingAdapter(mockTaskObject);
    const result = adapter.convertVideoFlowToAIClips();
    expect(result).toHaveLength(mockTaskObject.videos.data.length);
  });

  test("应该正确处理进度回调", () => {
    const onProgress = jest.fn();
    const adapter = new AIEditingAdapter(mockTaskObject, { onProgress });
    adapter.executeAIEditing();
    expect(onProgress).toHaveBeenCalled();
  });
});

集成测试

describe("AI剪辑集成测试", () => {
  test("完整的AI剪辑流程", async () => {
    // 1. 准备测试数据
    const mockTaskObject = createMockTaskObject();

    // 2. 执行AI剪辑
    const result = await executeAIEditing(mockTaskObject);

    // 3. 验证结果
    expect(result).toContain("http");
    expect(result).toMatch(/\.mp4$/);
  });
});

性能测试

响应时间: API 响应时间应在 5 秒内
内存使用: 处理过程中内存使用应保持在合理范围
并发处理: 支持多个 AI 剪辑任务并发执行

🐛 故障排除

常见问题

FFmpeg 未找到

错误: FFmpeg executable not found
解决: 确保FFmpeg已安装并在PATH中

视频格式不支持

错误: Unsupported video format
解决: 检查输入视频格式，确保为支持的格式

云存储上传失败

错误: Upload failed
解决: 检查云存储配置和网络连接

日志分析

// 启用详细日志
console.log("🎬 AI剪辑开始:", { projectId, clipCount });
console.log("📊 数据转换完成:", convertedData);
console.log("🚀 API调用中:", apiEndpoint);
console.log("✅ 处理完成:", finalVideoUrl);

🔮 未来优化方向

性能优化

并行处理: 支持多个视频片段并行处理
缓存机制: 实现处理结果缓存，避免重复计算
压缩优化: 优化视频压缩算法，减小文件大小

功能增强

自定义剪辑规则: 允许用户自定义 AI 剪辑参数
批量处理: 支持批量项目的 AI 剪辑处理
预览功能: 在正式导出前提供剪辑预览

用户体验

进度细化: 提供更详细的处理进度信息
错误恢复: 实现处理失败后的自动重试机制
通知系统: 添加处理完成的通知功能

📚 参考资料

📞 技术支持

如有技术问题，请联系开发团队或在项目仓库中创建 Issue。

文档版本: v1.0.0
最后更新: 2025-01-08
维护者: 资深全栈开发工程师
审核者: 项目技术负责人

11 KiB Raw Blame History Unescape Escape